Refactor AudioInputDevice to remove race conditions and allow more flexible calling sequences.

content/renderer/media/audio_input_device.h

 // Copyright (c) 2011 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.
 
 // Low-latency audio capturing unit utilizing audio input stream provided
 // by browser process through IPC.
 //
-// Relationship of classes.
+// Relationship of classes:
 //
 //  AudioInputController                 AudioInputDevice
 //           ^                                  ^
 //           |                                  |
 //           v                  IPC             v
 // AudioInputRendererHost  <---------> AudioInputMessageFilter
 //
 // Transportation of audio samples from the browser to the render process
 // is done by using shared memory in combination with a sync socket pair
 // to generate a low latency transport. The AudioInputDevice user registers
 // an AudioInputDevice::CaptureCallback at construction and will be called
 // by the AudioInputDevice with recorded audio from the underlying audio layers.
 //
-// State sequences.
+// State sequences:
 //
 //            Task [IO thread]                  IPC [IO thread]
 //
 // Start -> InitializeOnIOThread -----> AudioInputHostMsg_CreateStream ------->
 //     <- OnLowLatencyCreated <- AudioInputMsg_NotifyLowLatencyStreamCreated <-
 //       ---> StartOnIOThread ---------> AudioInputHostMsg_PlayStream -------->
 //
 // AudioInputDevice::Capture => low latency audio transport on audio thread =>
 //                               |
 // Stop --> ShutDownOnIOThread ------>  AudioInputHostMsg_CloseStream -> Close
 //
 // This class utilizes three threads during its lifetime, namely:
+//
 // 1. Creating thread.
 //    Must be the main render thread. Start and Stop should be called on
 //    this thread.
 // 2. IO thread.
 //    The thread within which this class receives all the IPC messages and
 //    IPC communications can only happen in this thread.
 // 3. Audio transport thread.
 //    Responsible for calling the CaptrureCallback and feed audio samples from
 //    the audio layer in the browser process using sync sockets and shared
 //    memory.
+//
+// Implementation notes:
+//
+// - Start() is asynchronous/non-blocking.
+// - Stop() is synchronous/blocking.
+// - The user must call Stop() before deleting the class instance.
 
 #ifndef CONTENT_RENDERER_MEDIA_AUDIO_INPUT_DEVICE_H_
 #define CONTENT_RENDERER_MEDIA_AUDIO_INPUT_DEVICE_H_
 #pragma once
 
 #include <vector>
 
 #include "base/basictypes.h"
 #include "base/memory/scoped_ptr.h"
 #include "base/shared_memory.h"
 #include "base/threading/simple_thread.h"
 #include "content/renderer/media/audio_input_message_filter.h"
 
 struct AudioParameters;
 
 // TODO(henrika): This class is based on the AudioDevice class and it has
 // many components in common. Investigate potential for re-factoring.
+// TODO(henrika): Add support for event handling (e.g. OnStateChanged,
+// OnCaptureStopped etc.) and ensure that we can deliver these notifications
+// to any clients using this class.
 class AudioInputDevice
     : public AudioInputMessageFilter::Delegate,
       public base::DelegateSimpleThread::Delegate,
       public base::RefCountedThreadSafe<AudioInputDevice> {
  public:
   class CaptureCallback {
    public:
     virtual void Capture(const std::vector<float*>& audio_data,
                          size_t number_of_frames,
                          size_t audio_delay_milliseconds) = 0;
    protected:
     virtual ~CaptureCallback() {}
   };
 
   // Methods called on main render thread -------------------------------------
   AudioInputDevice(size_t buffer_size,
                    int channels,
                    double sample_rate,
                    CaptureCallback* callback);
   virtual ~AudioInputDevice();
 
-  // Starts audio capturing. Returns |true| on success.
-  bool Start();
+  // Starts audio capturing. This method is asynchronous/non-blocking.
+  // TODO(henrika): add support for notification when recording has started.
+  void Start();
 
-  // Stops audio capturing. Returns |true| on success.
+  // Stops audio capturing. This method is synchronous/blocking.
+  // Returns |true| on success.
+  // TODO(henrika): add support for notification when recording has stopped.
   bool Stop();
 
   // Sets the capture volume scaling, with range [0.0, 1.0] inclusive.
   // Returns |true| on success.
   bool SetVolume(double volume);
 
   // Gets the capture volume scaling, with range [0.0, 1.0] inclusive.
   // Returns |true| on success.
   bool GetVolume(double* volume);
 
   double sample_rate() const { return sample_rate_; }
   size_t buffer_size() const { return buffer_size_; }
 
   // Methods called on IO thread ----------------------------------------------
   // AudioInputMessageFilter::Delegate impl., called by AudioInputMessageFilter
   virtual void OnLowLatencyCreated(base::SharedMemoryHandle handle,
                                    base::SyncSocket::Handle socket_handle,
                                    uint32 length);
   virtual void OnVolume(double volume);
 
  private:
   // Methods called on IO thread ----------------------------------------------
   // The following methods are tasks posted on the IO thread that needs to
   // be executed on that thread. They interact with AudioInputMessageFilter and
   // sends IPC messages on that thread.
   void InitializeOnIOThread(const AudioParameters& params);
   void StartOnIOThread();
-  void ShutDownOnIOThread();
+  void ShutDownOnIOThread(base::WaitableEvent* completion);
   void SetVolumeOnIOThread(double volume);
 
   void Send(IPC::Message* message);
 
   // Method called on the audio thread ----------------------------------------
   // Calls the client's callback for capturing audio.
   void FireCaptureCallback();
 
   // DelegateSimpleThread::Delegate implementation.
   virtual void Run();
@@ skipping 31 matching lines @@
   // Our stream ID on the message filter. Only modified on the IO thread.
   int32 stream_id_;
 
   scoped_ptr<base::SharedMemory> shared_memory_;
   scoped_ptr<base::SyncSocket> socket_;
 
   DISALLOW_IMPLICIT_CONSTRUCTORS(AudioInputDevice);
 };
 
 #endif  // CONTENT_RENDERER_MEDIA_AUDIO_INPUT_DEVICE_H_