Move audio frame memory handling inside AudioMixer.

webrtc/api/audio/audio_mixer.h

 /*
  *  Copyright (c) 2011 The WebRTC project authors. All Rights Reserved.
  *
  *  Use of this source code is governed by a BSD-style license
  *  that can be found in the LICENSE file in the root of the source
  *  tree. An additional intellectual property rights grant can be found
  *  in the file PATENTS.  All contributing project authors may
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
@@ skipping 14 matching lines @@
    public:
     enum class AudioFrameInfo {
       kNormal,  // The samples in audio_frame are valid and should be used.
       kMuted,   // The samples in audio_frame should not be used, but
                 // should be implicitly interpreted as zero. Other
                 // fields in audio_frame may be read and should
                 // contain meaningful values.
       kError,   // The audio_frame will not be used.
     };
 
-    struct AudioFrameWithInfo {
-      AudioFrame* audio_frame;
-      AudioFrameInfo audio_frame_info;
-    };
-
-    // The implementation of GetAudioFrameWithInfo should update
-    // audio_frame with new audio every time it's called. Implementing
-    // classes are allowed to return the same AudioFrame pointer on
-    // different calls. The pointer must stay valid until the next
-    // mixing call or until this audio source is disconnected from the
-    // mixer. The mixer may modify the contents of the passed
-    // AudioFrame pointer at any time until the next call to
-    // GetAudioFrameWithInfo, or until the source is removed from the
-    // mixer.
-    virtual AudioFrameWithInfo GetAudioFrameWithInfo(int sample_rate_hz) = 0;
+    // The AudioFrame pointer should be treated as only valid for the
+    // duration of this call. The passed AudioFrame is strictly an
+    // output parameter and its fields can have any values when being
+    // passed to GetAudioFrameWithInfo. Implementing classes may
+    // return sound with either one or two interleaved
+    // channels. Implementing classes are responsible for filling all
+    // fields of the provided AudioFrame with meaningful values.
+    virtual AudioFrameInfo GetAudioFrameWithInfo(int sample_rate_hz,
+                                                 AudioFrame* audio_frame) = 0;
 
     // A way for a mixer implementation to distinguish participants.
     virtual int Ssrc() = 0;
 
    protected:
     virtual ~Source() {}

[aleloi, 2016/10/14 15:34:44]

[Unrelated to this CL]: I think the reasoning behind not declaring the
AudioMixer destructor protected applies for Source as well: it's a pure
interface, so implementors should choose whether to allow destroying a Source by
a base pointer or not. WDYT?

[kwiberg-webrtc, 2016/10/14 19:59:32]

Implementations can't make that choice. If you have a base pointer and try
calling methods on it (and the destructor is just another method for the
purposes of this discussion), the compiler uses the base class's access
specifiers to determine whether to allow the call. (It has to be that way,
because the access specifiers are checked at compile time, and we don't know
which subclass it is until run time.)

And leaving the destructor publicly accessible is dangerous for a refcounted
object, for the obvious reason. So making it protected is the right thing to do,
for all classes that inherit from rtc::RefCountInterface.

[aleloi, 2016/10/17 11:06:39]

Thanks for the explanation! Previously I ran in the problem of deleting an
AudioMixer twice: an instance was created in the tests without being put in a
scoped_ptr. Then a mixer method was called with rtc::Bind. Bind updated the
reference counters and caused the object to be destroyed after the call ended.
The mixer was destroyed a second time at end of scope.

I didn't realize that it could have been avoided by making the dtor protected.

An AudioMixer::Source is not ref-counted though, so I think there is no reason
to keep the destructor protected.

[kwiberg-webrtc, 2016/10/17 12:08:32]

Oh, right. It's the AudioMixer destructor that should be protected.

   };
 
   // Since the mixer is reference counted, the destructor may be
   // called from any thread.
   ~AudioMixer() override {}
 
   // Returns true if adding/removing was successful. A source is never
   // added twice and removal is never attempted if a source has not
   // been successfully added to the mixer. Addition and removal can
   // happen on different threads.
   virtual bool AddSource(Source* audio_source) = 0;
   virtual bool RemoveSource(Source* audio_source) = 0;
 
   // Performs mixing by asking registered audio sources for audio. The
   // mixed result is placed in the provided AudioFrame. Will only be
   // called from a single thread. The rate and channels arguments
   // specify the rate and number of channels of the mix result.
   virtual void Mix(int sample_rate_hz,
                    size_t number_of_channels,
                    AudioFrame* audio_frame_for_mixing) = 0;
 };
 }  // namespace webrtc
 
 #endif  // WEBRTC_API_AUDIO_AUDIO_MIXER_H_