Revert "Implemented injected message loops for PipelineImpl."

media/base/pipeline.h

 // Copyright (c) 2009 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.
 
 // The pipeline is the public API clients use for playing back media.  Clients
 // provide a filter factory containing the filters they want the pipeline to
 // use to render media.
 
 #ifndef MEDIA_BASE_PIPELINE_H_
 #define MEDIA_BASE_PIPELINE_H_
@@ skipping 38 matching lines @@
 // TODO(scherkus): consider returning a PipelineError instead of a bool, or
 // perhaps a client callback interface.
 typedef Callback1<bool>::Type PipelineCallback;
 
 class Pipeline {
  public:
   // Build a pipeline to render the given URL using the given filter factory to
   // construct a filter chain.  Returns true if successful, false otherwise
   // (i.e., pipeline already started).  Note that a return value of true
   // only indicates that the initialization process has started successfully.
-  // Pipeline initialization is an inherently asynchronous process.  Clients can
-  // either poll the IsInitialized() method (discouraged) or use the
-  // |start_callback| as described below.
+  // Pipeline initialization is an inherently asynchronous process.  Clients
+  // should not call SetPlaybackRate(), Seek(), or SetVolume() until
+  // initialization is complete.  Clients can either poll the IsInitialized()
+  // method (which is discouraged) or use the |start_callback| as described
+  // below.
   //
   // This method is asynchronous and can execute a callback when completed.
   // If the caller provides a |start_callback|, it will be called when the
   // pipeline initialization completes.  If successful, the callback's bool
   // parameter will be true.  If the callback is called with false, then the
-  // client can use GetError() to obtain more information about the reason
-  // initialization failed.
+  // client can use the GetError() method to obtain more information about the
+  // reason initialization failed.  The prototype for the client callback is:
+  //    void Client::PipelineInitComplete(bool init_was_successful);
+  //
+  // Note that clients must not call the Stop method from within the
+  // |start_callback|.  Other methods, including SetPlaybackRate(), Seek(), and
+  // SetVolume() may be called.  The client will be called on a thread owned by
+  // the pipeline class, not on the thread that originally called the Start()
+  // method.
   virtual bool Start(FilterFactory* filter_factory,
                      const std::string& url,
                      PipelineCallback* start_callback) = 0;
 
-  // Asynchronously stops the pipeline and resets it to an uninitialized state.
-  // If provided, |stop_callback| will be executed when the pipeline has been
-  // completely torn down and reset to an uninitialized state.  It is acceptable
-  // to call Start() again once the callback has finished executing.
+  // Stops the pipeline and resets to an uninitialized state.  This method
+  // will block the calling thread until the pipeline has been completely
+  // torn down and reset to an uninitialized state.  After calling Stop(), it
+  // is acceptable to call Start() again since Stop() leaves the pipeline
+  // in a state identical to a newly created pipeline.
   //
-  // Stop() must be called before destroying the pipeline.  Clients can
-  // determine whether Stop() must be called by checking IsRunning().
+  // Stop() must be called before destroying the pipeline.
   //
-  // TODO(scherkus): ideally clients would destroy the pipeline after calling
-  // Stop() and create a new pipeline as needed.
-  virtual void Stop(PipelineCallback* stop_callback) = 0;
+  // TODO(scherkus): it shouldn't be acceptable to call Start() again after you
+  // Stop() a pipeline -- it should be destroyed and replaced with a new
+  // instance.
+  virtual void Stop() = 0;
 
   // Attempt to seek to the position specified by time.  |seek_callback| will be
   // executed when the all filters in the pipeline have processed the seek.
   // The callback will return true if the seek was carried out, false otherwise
   // (i.e., streaming media).
   virtual void Seek(base::TimeDelta time, PipelineCallback* seek_callback) = 0;
 
-  // Returns true if the pipeline has been started via Start().  If IsRunning()
-  // returns true, it is expected that Stop() will be called before destroying
-  // the pipeline.
-  virtual bool IsRunning() const = 0;
-
-  // Returns true if the pipeline has been started and fully initialized to a
-  // point where playback controls will be respected.  Note that it is possible
-  // for a pipeline to be started but not initialized (i.e., an error occurred).
+  // Returns the current initialization state of the pipeline.  Note that this
+  // will be set to true prior to a executing |init_complete_callback| if
+  // initialization is successful.
   virtual bool IsInitialized() const = 0;
 
   // If the |major_mime_type| exists in the pipeline and is being rendered, this
   // method will return true.  Types are defined in media/base/media_foramt.h.
   // For example, to determine if a pipeline contains video:
   //   bool has_video = pipeline->IsRendered(mime_type::kMajorTypeVideo);
   virtual bool IsRendered(const std::string& major_mime_type) const = 0;
 
   // Gets the current playback rate of the pipeline.  When the pipeline is
   // started, the playback rate will be 0.0f.  A rate of 1.0f indicates
@@ skipping 46 matching lines @@
   // operating correctly, this will return OK.
   virtual PipelineError GetError() const = 0;
 
  protected:
   virtual ~Pipeline() {}
 };
 
 }  // namespace media
 
 #endif  // MEDIA_BASE_PIPELINE_H_