Clean up Pipeline terminal state logic by merging kError into kStopped state.

media/base/pipeline.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.
 
 #ifndef MEDIA_BASE_PIPELINE_H_
 #define MEDIA_BASE_PIPELINE_H_
 
 #include <string>
 
 #include "base/gtest_prod_util.h"
@@ skipping 74 matching lines @@
 //                                         [ Any State Other Than InitXXX ]
 
 //
 // Initialization is a series of state transitions from "Created" through each
 // filter initialization state.  When all filter initialization states have
 // completed, we are implicitly in a "Paused" state.  At that point we simulate
 // a Seek() to the beginning of the media to give filters a chance to preroll.
 // From then on the normal Seek() transitions are carried out and we start
 // 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.
+// Any runtime error will cause the pipeline to end up in the stopped state.
 class MEDIA_EXPORT Pipeline
     : public base::RefCountedThreadSafe<Pipeline>,
       public DemuxerHost {
  public:
   // Constructs a media pipeline that will execute on |message_loop|.
   Pipeline(MessageLoop* message_loop, MediaLog* media_log);
 
   // Build a pipeline to using the given filter collection to construct a filter
   // chain.
   //
-  // Pipeline initialization is an inherently asynchronous process.  Clients can
-  // either poll the IsInitialized() method (discouraged) or optionally pass in
-  // |start_cb|, which will be executed when initialization completes.
-  //
   // The following permanent callbacks will be executed as follows:
   //   |start_cb_| will be executed when Start is done (successfully or not).
   //   |ended_cb| will be executed whenever the media reaches the end.
   //   |error_cb_| will be executed whenever an error occurs but hasn't
   //               been reported already through another callback.
   //
   // These callbacks are only executed after Start() has been called and until
   // Stop() has completed.
   //
   // It is an error to call this method after the pipeline has already started.
-  //
-  // TODO(scherkus): remove IsInitialized() and force clients to use callbacks.
   void Start(scoped_ptr<FilterCollection> filter_collection,
              const PipelineStatusCB& ended_cb,
              const PipelineStatusCB& error_cb,
              const PipelineStatusCB& start_cb);
 
-  // Asynchronously stops the pipeline and resets it to an uninitialized state.
+  // Asynchronously stops the pipeline, executing |stop_cb| when completed.
   //
-  // If provided, |stop_cb| 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.
-  //
-  // Stop() must be called before destroying the pipeline.  Clients can
-  // determine whether Stop() must be called by checking IsRunning().
-  //
-  // It is an error to call this method if the pipeline has not started.
-  //
-  // TODO(scherkus): ideally clients would destroy the pipeline after calling
-  // Stop() and create a new pipeline as needed.
+  // Clients can delete the pipeline after |stop_cb| runs.
   void Stop(const base::Closure& stop_cb);
 
   // Attempt to seek to the position specified by time.  |seek_cb| will be
   // executed when the all filters in the pipeline have processed the seek.
   //
   // Clients are expected to call GetMediaTime() to check whether the seek
   // succeeded.
   //
   // It is an error to call this method if the pipeline has not started.
   void Seek(base::TimeDelta time, const PipelineStatusCB& seek_cb);
 
   // 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.
   bool IsRunning() const;
 
-  // 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).
-  bool IsInitialized() const;
-
   // Returns true if the media has audio.
   bool HasAudio() const;
 
   // Returns true if the media has video.
   bool HasVideo() const;
 
   // 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
   // that the pipeline is rendering the media at the standard rate.  Valid
   // values for playback rate are >= 0.0f.
@@ skipping 65 matching lines @@
     kInitAudioRenderer,
     kInitVideoDecoder,
     kInitVideoRenderer,
     kPausing,
     kSeeking,
     kFlushing,
     kStarting,
     kStarted,
     kStopping,
     kStopped,
-    kError,
   };
 
   // Updates |state_|. All state transitions should use this call.
   void SetState(State next_state);
 
   // Simple method used to make sure the pipeline is running normally.
   bool IsPipelineOk();
 
   // Helper method to tell whether we are stopped or in error.
   bool IsPipelineStopped();
@@ skipping 75 matching lines @@
   // 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.  One stage communicates its status to the next through
   // |last_stage_status|.
   void InitializeTask(PipelineStatus last_stage_status);
 
   // Stops and destroys all filters, placing the pipeline in the kStopped state.
   void StopTask(const base::Closure& stop_cb);
 
   // Carries out stopping and destroying all filters, placing the pipeline in
-  // the kError state.
+  // the kStopped state.
   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, const PipelineStatusCB& seek_cb);
@@ skipping 81 matching lines @@
 
   // Lock used to serialize access for the following data members.
   mutable base::Lock lock_;
 
   // Whether or not the pipeline is running.
   bool running_;
 
   // Whether or not the pipeline is in transition for a seek operation.
   bool seek_pending_;
 
-  // Whether or not the pipeline is pending a stop operation.
-  bool stop_pending_;

[scherkus (not reviewing), 2012/08/08 02:20:56]

this is equivalent to inspecting stop_cb_

-
   // Whether or not the pipeline is perform a stop operation.
   bool tearing_down_;
 
-  // Whether or not an error triggered the teardown.
-  bool error_caused_teardown_;

[scherkus (not reviewing), 2012/08/08 02:20:56]

this is equivalent to (status_ != PIPELINE_OK)

-
   // Whether or not a playback rate change should be done once seeking is done.
   bool playback_rate_change_pending_;
 
   // Amount of available buffered data.  Set by filters.
   Ranges<int64> buffered_byte_ranges_;
   Ranges<base::TimeDelta> buffered_time_ranges_;
 
   // True when AddBufferedByteRange() has been called more recently than
   // DidLoadingProgress().
   mutable bool did_loading_progress_;
@@ skipping 90 matching lines @@
   base::Time creation_time_;
 
   scoped_ptr<SerialRunner> pending_callbacks_;
 
   DISALLOW_COPY_AND_ASSIGN(Pipeline);
 };
 
 }  // namespace media
 
 #endif  // MEDIA_BASE_PIPELINE_H_