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() {}
 
     // 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 20 matching lines @@
     // 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.
     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.
+  //
+  // Upon this call, the |client| pointer passed into AllocateAndStart() remains
+  // valid but enters a lame state where it is detached from any consumer, and

[Ami GONE FROM CHROMIUM, 2013/09/14 00:32:24]

I don't understand how this can be useful.  Two paragraphs up you promise
eventual deletion, which presumably may happen inline during
StopAndDeAllocate(), or it may not.
But here you promise *client "remains valid".  Until when?  How can a caller
know how much time *client has remaining to live?

[ncarter (slow), 2013/09/14 01:29:31]

It remains valid in that it's not illegal for stuff you've queued up to interact
with it. But those interactions won't do anything. The VCD owns the pointer, so
it can delete it when it wants. What I'm trying to say is -- "it's like a
weakptr". The current language seems clear to me. It's owned by the device, but
it's detached from the downstream pipe.

I just deleted this paragraph since it seems to be causing more confusion than
elucidation. My goal was to communicate to implementors, "you don't need to be
paranoid about not making calls into the EventHandler if you've already queued
some up somewhere."

+  // frames are silently dropped.
+  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_