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
@@ skipping 47 matching lines @@
     // be DeAllocate()-ed.
     virtual void OnError() = 0;
 
     // Called when VideoCaptureDevice::Allocate() 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> observer) = 0;
+
+  // Deallocates the camera. This means other applications can use it, and that
+  // the camera could be re-acquired by another VideoCaptureDevice instance if
+  // one were to be created immediately after this call. After this call the
+  // device should free the |observer| passed into AllocateAndStart as soon as
+  // possible, but may do so asynchronously.
+  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
+//     remain valid even after the device is stopped. Whereas old style devices

[Ami GONE FROM CHROMIUM, 2013/09/13 21:17:59]

s/remain/to remain/

[ncarter (slow), 2013/09/14 00:07:24]

Done.

+//     may not dereference their handlers after DeAllocate().

[Ami GONE FROM CHROMIUM, 2013/09/13 21:17:59]

I don't follow.  AFAICT from the commentary above (and the use of
scoped_ptr<EventHandler> in AllocateAndStart()), handlers must be assumed to be
deleted once SADA() returns (b/c they may be deleted asynchronously, but the
caller can't know when).  What am I missing?

[ncarter (slow), 2013/09/14 00:07:24]

I think I figured out what was missing. I made the comment on new interface more
explicit about the required behavior if delete is async.

+// [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;
+
+  // Gets the names of all video capture devices

[Ami GONE FROM CHROMIUM, 2013/09/13 21:17:59]

stray?

[ncarter (slow), 2013/09/14 00:07:24]

Done.

+  // 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_;

[Ami GONE FROM CHROMIUM, 2013/09/13 21:17:59]

This thing is known as a "Handler" (by the type), a "client" (by the variable
name), and as an "observer" (by the parameter name to AllocateAndStart()).  IMO
"client" is the best name, but hopefully whatever you like best can be a single
thing, some day.

[ncarter (slow), 2013/09/14 00:07:24]

"Client" is right term and it might have been a mistake for me to not go ahead
and rename the EventHandler interface already. I removed "observer" from this
context, that was an oversight.

 };
 
 }  // namespace media
 
 #endif  // MEDIA_VIDEO_CAPTURE_VIDEO_CAPTURE_DEVICE_H_