PipelineError is dead. Long live PipelineStatus!

media/base/pipeline_impl.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.
 
-// Implementation of Pipeline.
+// Implementation of Pipeline & PipelineStatusNotification (an async-to-sync
+// callback adapter).
 
 #ifndef MEDIA_BASE_PIPELINE_IMPL_H_
 #define MEDIA_BASE_PIPELINE_IMPL_H_
 
 #include <set>
 #include <string>
 #include <vector>
 
 #include "base/gtest_prod_util.h"
 #include "base/message_loop.h"
 #include "base/ref_counted.h"
 #include "base/scoped_ptr.h"
+#include "base/synchronization/condition_variable.h"
+#include "base/synchronization/lock.h"
 #include "base/threading/thread.h"
 #include "base/time.h"
 #include "media/base/clock.h"
 #include "media/base/composite_filter.h"
 #include "media/base/filter_host.h"
 #include "media/base/pipeline.h"
 
 namespace media {
 
+// Adapter for using asynchronous Pipeline methods in code that wants to run
+// synchronously.  To use, construct an instance of this class and pass the
+// |Callback()| to the Pipeline method requiring a callback.  Then Wait() for
+// the callback to get fired and call status() to see what the callback's
+// argument was.

[acolwell GONE FROM CHROMIUM, 2011/03/15 23:43:55]

Please add a comment about Callback() being a one-shot.

[Ami GONE FROM CHROMIUM, 2011/03/16 00:01:02]

Done.

+class PipelineStatusNotification {
+ public:
+  PipelineStatusNotification();
+  ~PipelineStatusNotification();
+
+  // See class-level comment for usage.
+  media::PipelineStatusCallback* Callback();
+  void Notify(media::PipelineStatus status);
+  void Wait();
+  media::PipelineStatus status();
+
+ private:
+  base::Lock lock_;
+  base::ConditionVariable cv_;
+  media::PipelineStatus status_;
+  bool notified_;
+  scoped_ptr<media::PipelineStatusCallback> callback_;

[acolwell GONE FROM CHROMIUM, 2011/03/15 23:43:55]

DISALLOW_COPY_AND_ASSIGN

[Ami GONE FROM CHROMIUM, 2011/03/16 00:01:02]

Done.

+};
 
 // PipelineImpl runs the media pipeline.  Filters are created and called on the
 // message loop injected into this object. PipelineImpl works like a state
 // machine to perform asynchronous initialization, pausing, seeking and playing.
 //
 // Here's a state diagram that describes the lifetime of this object.
 //
 //   [ *Created ]                                    [ Stopped ]
 //         | Start()                                      ^
 //         V                       SetError()             |
@@ skipping 23 matching lines @@
 // playing the media.
 //
 // If any error ever happens, this object will transition to the "Error" state
 // from any state. If Stop() is ever called, this object will transition to
 // "Stopped" state.
 class PipelineImpl : public Pipeline, public FilterHost {
  public:
   explicit PipelineImpl(MessageLoop* message_loop);
 
   // Pipeline implementation.
-  virtual void Init(PipelineCallback* ended_callback,
-                    PipelineCallback* error_callback,
-                    PipelineCallback* network_callback);
+  virtual void Init(PipelineStatusCallback* ended_callback,
+                    PipelineStatusCallback* error_callback,
+                    PipelineStatusCallback* network_callback);
   virtual bool Start(FilterCollection* filter_collection,
                      const std::string& uri,
-                     PipelineCallback* start_callback);
-  virtual void Stop(PipelineCallback* stop_callback);
-  virtual void Seek(base::TimeDelta time, PipelineCallback* seek_callback);
+                     PipelineStatusCallback* start_callback);
+  virtual void Stop(PipelineStatusCallback* stop_callback);
+  virtual void Seek(base::TimeDelta time,
+                    PipelineStatusCallback* seek_callback);
   virtual bool IsRunning() const;
   virtual bool IsInitialized() const;
   virtual bool IsNetworkActive() const;
   virtual bool HasAudio() const;
   virtual bool HasVideo() const;
   virtual float GetPlaybackRate() const;
   virtual void SetPlaybackRate(float playback_rate);
   virtual float GetVolume() const;
   virtual void SetVolume(float volume);
   virtual base::TimeDelta GetCurrentTime() const;
   virtual base::TimeDelta GetBufferedTime();
   virtual base::TimeDelta GetMediaDuration() const;
   virtual int64 GetBufferedBytes() const;
   virtual int64 GetTotalBytes() const;
   virtual void GetVideoSize(size_t* width_out, size_t* height_out) const;
   virtual bool IsStreaming() const;
   virtual bool IsLoaded() const;
-  virtual PipelineError GetError() const;
   virtual PipelineStatistics GetStatistics() const;
 
   void SetClockForTesting(Clock* clock);
 
  private:
   // Pipeline states, as described above.
   enum State {
     kCreated,
     kInitDemuxer,
     kInitAudioDecoder,
@@ skipping 42 matching lines @@
   void FinishInitialization();
 
   // Returns true if the given state is one that transitions to a new state
   // after iterating through each filter.
   static bool TransientState(State state);
 
   // Given the current state, returns the next state.
   State FindNextState(State current);
 
   // FilterHost implementation.
-  virtual void SetError(PipelineError error);
+  virtual void SetError(PipelineStatus error);
   virtual base::TimeDelta GetTime() const;
   virtual base::TimeDelta GetDuration() const;
   virtual void SetTime(base::TimeDelta time);
   virtual void SetDuration(base::TimeDelta duration);
   virtual void SetBufferedTime(base::TimeDelta buffered_time);
   virtual void SetTotalBytes(int64 total_bytes);
   virtual void SetBufferedBytes(int64 buffered_bytes);
   virtual void SetVideoSize(size_t width, size_t height);
   virtual void SetStreaming(bool streamed);
   virtual void SetLoaded(bool loaded);
@@ skipping 14 matching lines @@
   void OnTeardownStateTransition();
 
   // Callback executed by filters to update statistics.
   void OnUpdateStatistics(const PipelineStatistics& stats);
 
   // The following "task" methods correspond to the public methods, but these
   // methods are run as the result of posting a task to the PipelineInternal's
   // message loop.
   void StartTask(FilterCollection* filter_collection,
                  const std::string& url,
-                 PipelineCallback* start_callback);
+                 PipelineStatusCallback* start_callback);
 
   // InitializeTask() performs initialization in multiple passes. It is executed
   // as a result of calling Start() or InitializationComplete() that advances
   // initialization to the next state. It works as a hub of state transition for
   // initialization.
   void InitializeTask();
 
   // Stops and destroys all filters, placing the pipeline in the kStopped state.
-  void StopTask(PipelineCallback* stop_callback);
+  void StopTask(PipelineStatusCallback* stop_callback);
 
   // Carries out stopping and destroying all filters, placing the pipeline in
   // the kError state.
-  void ErrorChangedTask(PipelineError error);
+  void ErrorChangedTask(PipelineStatus error);
 
   // Carries out notifying filters that the playback rate has changed.
   void PlaybackRateChangedTask(float playback_rate);
 
   // Carries out notifying filters that the volume has changed.
   void VolumeChangedTask(float volume);
 
   // Carries out notifying filters that we are seeking to a new timestamp.
-  void SeekTask(base::TimeDelta time, PipelineCallback* seek_callback);
+  void SeekTask(base::TimeDelta time, PipelineStatusCallback* seek_callback);
 
   // Carries out handling a notification from a filter that it has ended.
   void NotifyEndedTask();
 
   // Carries out handling a notification of network event.
   void NotifyNetworkEventTask();
 
   // Carries out disabling the audio renderer.
   void DisableAudioRendererTask();
 
@@ skipping 12 matching lines @@
   // Internal methods used in the implementation of the pipeline thread.  All
   // of these methods are only called on the pipeline thread.
 
   // PrepareFilter() creates the filter's thread and injects a FilterHost and
   // MessageLoop.
   bool PrepareFilter(scoped_refptr<Filter> filter);
 
   // The following initialize methods are used to select a specific type of
   // Filter object from FilterCollection and initialize it asynchronously.
   void InitializeDemuxer();
-  void OnDemuxerBuilt(PipelineError error, Demuxer* demuxer);
+  void OnDemuxerBuilt(PipelineStatus status, Demuxer* demuxer);
 
   // Returns true if the asynchronous action of creating decoder has started.
   // Returns false if this method did nothing because the corresponding
   // audio/video stream does not exist.
   bool InitializeAudioDecoder(const scoped_refptr<Demuxer>& demuxer);
   bool InitializeVideoDecoder(const scoped_refptr<Demuxer>& demuxer);
 
   // Initializes a renderer and connects it with decoder. Returns true if the
   // asynchronous action of creating renderer has started. Returns
   // false if this method did nothing because the corresponding audio/video
@@ skipping 85 matching lines @@
 
   // If this value is set to true, then |clock_| is paused and we are waiting
   // for an update of the clock greater than or equal to the elapsed time to
   // start the clock.
   bool waiting_for_clock_update_;
 
   // Status of the pipeline.  Initialized to PIPELINE_OK which indicates that
   // the pipeline is operating correctly. Any other value indicates that the
   // pipeline is stopped or is stopping.  Clients can call the Stop() method to
   // reset the pipeline state, and restore this to PIPELINE_OK.
-  PipelineError error_;
+  PipelineStatus status_;
 
   // Whether the media contains rendered audio and video streams.
   bool has_audio_;
   bool has_video_;
 
   // The following data members are only accessed by tasks posted to
   // |message_loop_|.
 
   // Member that tracks the current state.
   State state_;
@@ skipping 14 matching lines @@
   // TODO(vrk): This is a hack.
   base::TimeDelta max_buffered_time_;
 
   // Filter collection as passed in by Start().
   scoped_ptr<FilterCollection> filter_collection_;
 
   // URL for the data source as passed in by Start().
   std::string url_;
 
   // Callbacks for various pipeline operations.
-  scoped_ptr<PipelineCallback> seek_callback_;
-  scoped_ptr<PipelineCallback> stop_callback_;
-  scoped_ptr<PipelineCallback> ended_callback_;
-  scoped_ptr<PipelineCallback> error_callback_;
-  scoped_ptr<PipelineCallback> network_callback_;
+  scoped_ptr<PipelineStatusCallback> seek_callback_;
+  scoped_ptr<PipelineStatusCallback> stop_callback_;
+  scoped_ptr<PipelineStatusCallback> ended_callback_;
+  scoped_ptr<PipelineStatusCallback> error_callback_;
+  scoped_ptr<PipelineStatusCallback> network_callback_;
 
   // Reference to the filter(s) that constitute the pipeline.
   scoped_refptr<Filter> pipeline_filter_;
 
   // Renderer references used for setting the volume and determining
   // when playback has finished.
   scoped_refptr<AudioRenderer> audio_renderer_;
   scoped_refptr<VideoRenderer> video_renderer_;
 
   // Helper class that stores filter references during pipeline
   // initialization.
   class PipelineInitState;
   scoped_ptr<PipelineInitState> pipeline_init_state_;
 
   // Statistics.
   PipelineStatistics statistics_;
 
   FRIEND_TEST_ALL_PREFIXES(PipelineImplTest, GetBufferedTime);
 
   DISALLOW_COPY_AND_ASSIGN(PipelineImpl);
 };
 
 }  // namespace media
 
 #endif  // MEDIA_BASE_PIPELINE_IMPL_H_