MediaStream audio object graph untangling and clean-ups.

content/renderer/media/media_stream_audio_track.h

 // Copyright 2015 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 CONTENT_RENDERER_MEDIA_MEDIA_STREAM_AUDIO_TRACK_H_
 #define CONTENT_RENDERER_MEDIA_MEDIA_STREAM_AUDIO_TRACK_H_
 
+#include <vector>
+
+#include "base/callback.h"
 #include "base/macros.h"
 #include "content/renderer/media/media_stream_track.h"
 
 namespace webrtc {
 class AudioTrackInterface;
 }  // namespace webrtc
 
 namespace content {
 
 class MediaStreamAudioSink;
 
+// TODO(miu): In a soon-upcoming set of refactoring changes, this class will
+// take on the functionality of managing sink connections and the audio data
+// flow between source and sinks.  The WebRTC-specific elements will then be
+// moved into a subclass.   http://crbug.com/577874
 class CONTENT_EXPORT MediaStreamAudioTrack : public MediaStreamTrack {
  public:
   explicit MediaStreamAudioTrack(bool is_local_track);
+
+  // Subclasses must ensure the track is stopped before this destructor is
+  // invoked.
   ~MediaStreamAudioTrack() override;
 
-  static MediaStreamAudioTrack* GetTrack(
-      const blink::WebMediaStreamTrack& track);
+  // Returns the MediaStreamAudioTrack instance owned by the given blink |track|
+  // or null.
+  static MediaStreamAudioTrack* From(const blink::WebMediaStreamTrack& track);
+
+  // The first time Stop() is called on this track, each |stop_callback| will be
+  // run.  This is generally used by sources to be notified that the audio data
+  // flow to the track should halt.
+  void AddStopObserver(const base::Closure& stop_callback);
 
   // Add a sink to the track. This function will trigger a OnSetFormat()
   // call on the |sink|.
   // Called on the main render thread.
   virtual void AddSink(MediaStreamAudioSink* sink) = 0;
 
   // Remove a sink from the track.
   // Called on the main render thread.
   virtual void RemoveSink(MediaStreamAudioSink* sink) = 0;
 
   // TODO(tommi, xians): Remove this method.
+  // TODO(miu): See class-level TODO comment.  ;-)
   virtual webrtc::AudioTrackInterface* GetAudioAdapter();
 
   // Returns the output format of the capture source. May return an invalid
   // AudioParameters if the format is not yet available.
   // Called on the main render thread.
   // TODO(tommi): This method appears to only be used by Pepper and in fact
   // does not appear to be necessary there.  We should remove it since it adds
   // to the complexity of all types of audio tracks+source implementations.
   virtual media::AudioParameters GetOutputFormat() const = 0;
 
+  // Subclasses must override this method and must call WillStopTrack() to
+  // ensure the stop callbacks are run.
+  void Stop() override = 0;
+
+ protected:
+  // Runs the stop callbacks.
+  void WillStopTrack();

[o1ka, 2016/03/01 14:18:59]

NotifyStopObservers() maybe?

[miu, 2016/03/02 01:12:50]

Acknowledged.  This got re-worked, as explained in other comments.

+
  private:
+  // These are run after this track has been stopped.  Even if Stop() is called

[o1ka, 2016/03/01 14:18:59]

The comment needs some makeover now, probably something like "Run by
WillStopTrack() once, even if WillStopTrack() is called multiple times.."

[miu, 2016/03/02 01:12:50]

Acknowledged.  This also got re-worked, as explained in other comments.

+  // multiple times, the |stop_callbacks_| are only run the first time.
+  std::vector<base::Closure> stop_callbacks_;
+
   DISALLOW_COPY_AND_ASSIGN(MediaStreamAudioTrack);
 };
 
 }  // namespace content
 
 #endif  // CONTENT_RENDERER_MEDIA_MEDIA_STREAM_AUDIO_TRACK_H_