Add a SharedMemSynchronizer class.

media/audio/shared_mem_synchronizer.h

Index: media/audio/shared_mem_synchronizer.h
diff --git a/media/audio/shared_mem_synchronizer.h b/media/audio/shared_mem_synchronizer.h
new file mode 100644
index 0000000000000000000000000000000000000000..1fa70e611a4617612db22812c58375cad6042d0b
--- /dev/null
+++ b/media/audio/shared_mem_synchronizer.h
@@ -0,0 +1,166 @@
+// Copyright (c) 2012 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef MEDIA_AUDIO_SHARED_MEM_SYNCHRONIZER_H_
+#define MEDIA_AUDIO_SHARED_MEM_SYNCHRONIZER_H_
+
+#include <vector>
+
+#include "base/basictypes.h"
+#include "base/process.h"
+#include "media/base/media_export.h"
+
+#if defined(OS_WIN)
+#include "base/win/scoped_handle.h"
+#else
+#include "base/file_descriptor_posix.h"
+#include "base/sync_socket.h"
+#endif
+
+// A mechanism to synchronize access to a shared memory segment between
+// two parties when the usage pattern resembles that of two players playing
+// a game of chess.  Each end has an instance of SharedMemSynchronizer and
+// calls Signal() when it has finished reading from/writing to the shared
+// memory section.  Before accessing the memory, it must call Wait() in order
+// to know when the other end has called Signal().
+//
+// Here's some pseudo code for how this class can be used:
+//
+// This method is used by both processes as it's a general way to access the
+// shared memory section, write to it and then grant the privilege to the
+// other process:
+//
+// void WriteToSharedMemory(SharedMemSynchronizer* synchronizer,
+//                          SharedMemory* mem,
+//                          const char my_char) {
+//   synchronizer->Wait();  // Wait for the other process to yield access.
+//   reinterpret_cast<char*>(mem->memory())[0] = my_char;
+//   synchronizer->Signal();  // Grant the other process access.
+// }
+//
+// Process A:
+//
+// class A {
+//  public:
+//   void Initialize(base::ProcessHandle process_b) {
+//     mem_.CreateNamed("foo", false, 1024);
+//
+//     SharedMemSynchronizer b;
+//     CHECK(SharedMemSynchronizer::InitializePair(&synchronizer_, &b));
+//     SharedMemSynchronizer::IPCHandle handle_1, handle_2;
+//     CHECK(b.ShareToProcess(process_b, &handle_1, &handle_2));
+//     // This could be implemented by using some IPC mechanism
+//     // such as MessageLoop.
+//     SendToProcessB(mem_, handle_1, handle_2);
+//     // Allow process B the first chance to write to the memory:
+//     synchronizer_.Signal();
+//     // Once B is done, we'll write 'A' to the shared memory.
+//     WriteToSharedMemory(&synchronizer_, &mem_, 'A');
+//   }
+//
+//   SharedMemSynchronizer synchronizer_;
+//   SharedMemory mem_;
+// };
+//
+// Process B:
+//
+// class B {
+//  public:
+//   // Called when we receive the IPC message from A.
+//   void Initialize(SharedMemoryHandle mem,
+//                   SharedMemSynchronizer::IPCHandle handle_1,
+//                   SharedMemSynchronizer::IPCHandle handle_2) {
+//     mem_.reset(new SharedMemory(mem, false));
+//     synchronizer_.reset(new SharedMemSynchronizer(handle_1, handle_2));
+//     WriteToSharedMemory(&synchronizer_, &mem_, 'B');
+//   }
+//
+//   SharedMemSynchronizer synchronizer_;
+//   scoped_ptr<SharedMemory> mem_;
+// };
+//
+class MEDIA_EXPORT SharedMemSynchronizer {
+ public:
+#if defined(OS_WIN)
+  typedef HANDLE IPCHandle;
+#else
+  typedef base::FileDescriptor IPCHandle;
+#endif
+
+  typedef std::vector<SharedMemSynchronizer*> SynchronizerVector;
+
+  // Default ctor.  Initializes a NULL synchronizer.  User must call
+  // InitializePair() to initialize the instance along with a connected one.
+  SharedMemSynchronizer();
+
+  // Ctor for the user that does not call InitializePair but instead receives
+  // handles from the one that did.  These handles come from a call to
+  // ShareToProcess.
+  SharedMemSynchronizer(IPCHandle handle_1, IPCHandle handle_2);
+  ~SharedMemSynchronizer();
+
+  // Raises a signal that the shared memory now can be accessed by the
+  // other party.
+  void Signal();

[Ami GONE FROM CHROMIUM, 2012/03/13 20:08:02]

My point about blocking was that if a single synchronizer sent 100k Signal()'s,
with nobody calling Wait(), I bet the OS buffer for the socket would fill up and
Signal() would block on the write.
It's fine to say that's not a supported use-case (specifically that only an
initial Signal() is legit without previously Wait()ing), but I was trying to get
you to be explicit about that contract.

[tommi (sloooow) - chröme, 2012/03/14 13:32:43]

Thanks. I added documentation to make that clear.

+
+  // Waits for the other party to finish using the shared memory.
+  void Wait();
+
+  bool IsValid() const;
+
+  // Copies the internal handles to the output parameters, |handle_1| and
+  // |handle_2|.  The operation can fail, so the caller must be prepared to
+  // handle that case.
+  bool ShareToProcess(base::ProcessHandle process, IPCHandle* handle_1,
+                      IPCHandle* handle_2);
+
+  // Initializes a pair of SharedMemSynchronizer instances.  Note that this can
+  // fail (e.g. due to EMFILE on Linux), so the caller must handle that case.
+  static bool InitializePair(SharedMemSynchronizer* a,
+                             SharedMemSynchronizer* b);
+
+  // Use an instance of this class when you have to repeatedly wait
+  // for multiple instances of SharedMemSynchronizer on the same thread.
+  // The class will store information about which synchronizer was last signaled
+  // and try to distribute the signals so that all synchronizers get a chance to
+  // be processed in times of high load and a busy one won't starve the
+  // others.
+  // TODO(tommi): Support a way to abort the wait.
+  class MEDIA_EXPORT WaitForMultiple {
+   public:
+    // Caller must make sure that the lifetime of the array is greater than
+    // that of the WaitForMultiple instance.
+    WaitForMultiple(const SynchronizerVector* synchronizers);
+
+    // Waits for any of the synchronizers to be signaled.  Returns the 0 based
+    // index of a signaled synchronizer.
+    int Wait();
+
+    // Call when the array changes.

[Ami GONE FROM CHROMIUM, 2012/03/13 20:08:02]

Doco the effect on outstanding Wait()'s?
(namely, that this should never be called during an outstanding Wait()?)

[tommi (sloooow) - chröme, 2012/03/14 13:32:43]

Done.

+    void Reset(const SynchronizerVector* synchronizers);
+
+   private:
+    const SynchronizerVector* synchronizers_;
+    size_t last_;
+  };
+
+ private:
+  // Only called by the WaitForMultiple class.  See documentation
+  // for WaitForMultiple and comments inside WaitMultiple for details.
+  static int WaitMultiple(const SynchronizerVector& synchronizers,
+                          size_t last_signaled);
+
+#if defined(OS_WIN)
+  base::win::ScopedHandle mine_;
+  base::win::ScopedHandle other_;
+#else
+  typedef base::CancelableSyncSocket SocketClass;
+  SocketClass socket_;
+#endif
+
+ private:
+  DISALLOW_COPY_AND_ASSIGN(SharedMemSynchronizer);
+};
+
+#endif  // MEDIA_AUDIO_SHARED_MEM_SYNCHRONIZER_H_