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..9af521674e486b94c71d0c3d2fec524dea24ed34
--- /dev/null
+++ b/media/audio/shared_mem_synchronizer.h
@@ -0,0 +1,91 @@
+// 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 "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().

[scherkus (not reviewing), 2012/03/08 02:37:08]

I know I can look at unit tests, but I think we could use a tiny code snippet
here to explain how I'm supposed to use this class

for example we've got the following:
  * default ctor
  * ctor w/ IPCHandles
  * ShareToProcess()
  * Create()

which functions do I call, when should I call them, and in which processes?  for
example base/synchronization/condition_variable.h has a nice intro on usage &
gotchas

[tommi (sloooow) - chröme, 2012/03/08 16:10:57]

Done.

+class MEDIA_EXPORT SharedMemSynchronizer {
+ public:
+#if defined(OS_WIN)
+  typedef HANDLE IPCHandle;
+#else
+  typedef base::FileDescriptor IPCHandle;
+#endif
+
+  SharedMemSynchronizer();

[scherkus (not reviewing), 2012/03/08 02:37:08]

docs on ctors considering they can be different

[tommi (sloooow) - chröme, 2012/03/08 16:10:57]

Done.

+  SharedMemSynchronizer(IPCHandle handle_1, IPCHandle handle_2);
+  ~SharedMemSynchronizer();
+
+  void Signal();

[scherkus (not reviewing), 2012/03/08 02:37:08]

docs

[tommi (sloooow) - chröme, 2012/03/08 16:10:57]

Done.

+  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);
+
+  // Initialized a pair of SharedMemSynchronizer instances.  Note that this can

[scherkus (not reviewing), 2012/03/08 02:37:08]

typo?

Initialized -> Initialize ?

[tommi (sloooow) - chröme, 2012/03/08 16:10:57]

Done.

+  // fail (e.g. due to EMFILE on Linux), so the caller must handle that case.
+  static bool Create(SharedMemSynchronizer* a, SharedMemSynchronizer* b);

[scherkus (not reviewing), 2012/03/08 02:37:08]

would it be better to rename this Initialize()?

[tommi (sloooow) - chröme, 2012/03/08 16:10:57]

I kinda borrowed this name from SyncSocket except that I didn't call it
CreatePair... I guess I could call this InitializePair to make it even clearer.

+
+  // 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.

[scherkus (not reviewing), 2012/03/08 02:37:08]

I guess starvation would still occur if a client is constantly recreating their
WaitForMultiple object by adding/removing objects from the end of the array
between calls to Wait() (last_ is always reset to zero)

we could do something like shuffle the synchronizers_ pointer inside of Wait()
but that seems rather tricky haha

[tommi (sloooow) - chröme, 2012/03/08 16:10:57]

Yes.  However, adding/removing to/from the array should be a much rarer case
than synchronizing the shared memory (audio buffers), so at least the problem is
reduced in that case.  To rectify that I guess we could offer a way to reset the
synchronizer array instead of recreating the WaitForMultiple instance, but I
don't think this is going to be a problem in practice (see below).
I wrote this to support the scenario of multiple SharedMemSynchronizer
instances.  But then came up with an alternate solution that is considerably
faster and can use as few as a single pair of synchronizers for thousands of
shared mem objects.  See the "TwoSynchronizersTwoThreads1000Signals" test.  So,
in practice, the number of SharedMemSynchronizers will likely be 1 per process
for audio in the most common case.

+  class MEDIA_EXPORT WaitForMultiple {
+   public:
+    WaitForMultiple(SharedMemSynchronizer* synchronizers, size_t count);
+
+    // Waits for any of the synchronizers to be signaled.  Returns the 0 based
+    // index of a signaled synchronizer.
+    int Wait();
+
+   private:
+    SharedMemSynchronizer* synchronizers_;
+    size_t count_;
+    size_t last_;
+  };
+
+ protected:

[scherkus (not reviewing), 2012/03/08 02:37:08]

this class doesn't appear to have subclasses -- private?

[tommi (sloooow) - chröme, 2012/03/08 16:10:57]

Done.

+  // Only called by the WaitForMultiple class.  See documentation
+  // for WaitForMultiple and comments inside WaitMultiple for details.
+  static int WaitMultiple(SharedMemSynchronizer* synchronizers, size_t count,
+                          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_