Make VideoCaptureController single-threaded and not ref counted.

media/video/capture/video_capture_device.h

 // 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.
 //
 // VideoCaptureDevice is the abstract base class for realizing video capture
 // device support in Chromium. It provides the interface for OS dependent
 // implementations.
 // The class is created and functions are invoked on a thread owned by
 // VideoCaptureManager. Capturing is done on other threads, depending on the OS
 // specific implementation.
@@ skipping 102 matching lines @@
       : public NON_EXPORTED_BASE(std::list<Name>) {
    public:
     // Returns NULL if no entry was found by that ID.
     Name* FindById(const std::string& id);
 
     // Allow generated copy constructor and assignment.
   };
 
   class MEDIA_EXPORT EventHandler {
    public:
+    virtual ~EventHandler() {}

[perkj_chrome, 2013/09/16 08:50:15]

Why make this public? Do you really want to allow the implementor of this class
to be deleted through the EventHandler interface?

[ncarter (slow), 2013/09/16 15:18:17]

Yes, that's the design. With this new change, the EventHandler is a
VideoCaptureController::VideoCaptureDeviceClient, which is a proxy to the
Controller, and owned by the Device. There is a comment in the changelist
description that justifies this decision.

 
     // Reserve an output buffer into which a video frame can be captured
     // directly. If all buffers are currently busy, returns NULL.
     //
     // The returned VideoFrames will always be allocated with a YV12 format. The
     // size will match that specified by an earlier call to OnFrameInfo. It is
     // the VideoCaptureDevice's responsibility to obey whatever stride and
     // memory layout are indicated on the returned VideoFrame object.
     //
     // The output buffer stays reserved for use by the calling
     // VideoCaptureDevice until either the last reference to the VideoFrame is
     // released, or until the buffer is passed back to the EventHandler's
     // OnIncomingCapturedFrame() method.
-    //
-    // Threading note: After VideoCaptureDevice::DeAllocate() occurs, the
-    // VideoCaptureDevice is not permitted to make any additional calls through
-    // its EventHandler. However, any VideoFrames returned from the EventHandler
-    // DO remain valid after DeAllocate(). The VideoCaptureDevice must still
-    // eventually release them, but it may do so later -- e.g., after a queued
-    // capture operation completes.
     virtual scoped_refptr<media::VideoFrame> ReserveOutputBuffer() = 0;
 
     // Captured a new video frame as a raw buffer. The size, color format, and
     // layout are taken from the parameters specified by an earlier call to
     // OnFrameInfo(). |data| must be packed, with no padding between rows and/or
     // color planes.
     //
     // This method will try to reserve an output buffer and copy from |data|
     // into the output buffer. If no output buffer is available, the frame will
     // be silently dropped.
@@ skipping 17 matching lines @@
     // If |frame| was NOT created via ReserveOutputBuffer(), then this method
     // will try to reserve an output buffer and copy from |frame| into the
     // output buffer. If no output buffer is available, the frame will be
     // silently dropped. |frame| must be allocated as RGB32, YV12 or I420, and
     // the size must match that specified by an earlier call to OnFrameInfo().
     virtual void OnIncomingCapturedVideoFrame(
         const scoped_refptr<media::VideoFrame>& frame,
         base::Time timestamp) = 0;
 
     // An error has occurred that cannot be handled and VideoCaptureDevice must
-    // be DeAllocate()-ed.
+    // be StopAndDeAllocate()-ed.
     virtual void OnError() = 0;
 
-    // Called when VideoCaptureDevice::Allocate() has been called to inform of
-    // the resulting frame size.
+    // Called when VideoCaptureDevice::AllocateAndStart() has been called to
+    // inform of the resulting frame size.
     virtual void OnFrameInfo(const VideoCaptureCapability& info) = 0;
 
     // Called when the native resolution of VideoCaptureDevice has been changed
     // and it needs to inform its client of the new frame size.
     virtual void OnFrameInfoChanged(const VideoCaptureCapability& info) {};
-
-   protected:
-    virtual ~EventHandler() {}
   };
   // Creates a VideoCaptureDevice object.
   // Return NULL if the hardware is not available.
   static VideoCaptureDevice* Create(const Name& device_name);
-  virtual ~VideoCaptureDevice() {}
+  virtual ~VideoCaptureDevice();
 
   // Gets the names of all video capture devices connected to this computer.
   static void GetDeviceNames(Names* device_names);
 
   // Prepare the camera for use. After this function has been called no other
   // applications can use the camera. On completion EventHandler::OnFrameInfo()
   // is called informing of the resulting resolution and frame rate.
+  // StopAndDeAllocate() must be called before the object is deleted.
+  virtual void AllocateAndStart(
+      const VideoCaptureCapability& capture_format,
+      scoped_ptr<EventHandler> client) = 0;
+
+  // Deallocates the camera, possibly asynchronously.
+  //
+  // This call requires the device to do the following things, eventually: put
+  // camera hardware into a state where other applications could use it, free
+  // the memory associated with capture, and delete the |client| pointer passed
+  // into AllocateAndStart.
+  //
+  // If deallocation is done asynchronously, then the device implementation must
+  // ensure that a subsequent AllocateAndStart() operation targeting the same ID
+  // would be sequenced through the same task runner, so that deallocation
+  // happens first.
+  virtual void StopAndDeAllocate() = 0;
+};
+
+// VideoCaptureDevice1 is a bridge to an older API against which
+// VideoCaptureDevices were implemented. Differences between VideoCaptureDevice
+// (new style) and VideoCaptureDevice1 (old style) are as follows:
+//
+// [1] The Stop+DeAllocate calls are merged in the new style.
+// [2] The Allocate+Start calls are merged in the new style.
+// [3] New style devices own their EventHandler* pointers, allowing handlers to
+//     remain valid even after the device is stopped. Whereas old style devices
+//     may not dereference their handlers after DeAllocate().
+// [4] device_name() is eliminated from the new-style interface.
+//
+// TODO(nick): Remove this bridge class. It exists to enable incremental
+// migration to an alternative VideoCaptureDevice API.
+class MEDIA_EXPORT VideoCaptureDevice1 : public VideoCaptureDevice {
+ public:
+  VideoCaptureDevice1();
+  virtual ~VideoCaptureDevice1();
+
+  // VideoCaptureDevice implementation.
+  virtual void AllocateAndStart(
+      const VideoCaptureCapability& capture_format,
+      scoped_ptr<EventHandler> client) OVERRIDE;
+  virtual void StopAndDeAllocate() OVERRIDE;
+
+  // Prepare the camera for use. After this function has been called no other
+  // applications can use the camera. On completion EventHandler::OnFrameInfo()
+  // is called informing of the resulting resolution and frame rate.
   // DeAllocate() must be called before this function can be called again and
   // before the object is deleted.
   virtual void Allocate(const VideoCaptureCapability& capture_format,
-                        EventHandler* observer) = 0;
+                        EventHandler* client) = 0;
 
   // Start capturing video frames. Allocate must be called before this function.
   virtual void Start() = 0;
 
   // Stop capturing video frames.
   virtual void Stop() = 0;
 
   // Deallocates the camera. This means other applications can use it. After
   // this function has been called the capture device is reset to the state it
   // was when created. After DeAllocate() is called, the VideoCaptureDevice is
   // not permitted to make any additional calls to its EventHandler.
   virtual void DeAllocate() = 0;
 
   // Get the name of the capture device.
   virtual const Name& device_name() = 0;
+
+ private:
+  // The device client which proxies device events to the controller.
+  scoped_ptr<EventHandler> client_;
 };
 
 }  // namespace media
 
 #endif  // MEDIA_VIDEO_CAPTURE_VIDEO_CAPTURE_DEVICE_H_