AecDump interface

webrtc/modules/audio_processing/include/audio_processing.h

 /*
  *  Copyright (c) 2012 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 11 matching lines @@
 #include "webrtc/base/arraysize.h"
 #include "webrtc/base/platform_file.h"
 #include "webrtc/modules/audio_processing/beamformer/array_util.h"
 #include "webrtc/modules/audio_processing/include/config.h"
 #include "webrtc/typedefs.h"
 
 namespace webrtc {
 
 struct AecCore;
 
+class AecDump;
 class AudioFrame;
 
 class NonlinearBeamformer;
 
 class StreamConfig;
 class ProcessingConfig;
 
 class EchoCancellation;
 class EchoControlMobile;
 class GainControl;
@@ skipping 398 matching lines @@
   virtual void set_stream_key_pressed(bool key_pressed) = 0;
 
   // Sets a delay |offset| in ms to add to the values passed in through
   // set_stream_delay_ms(). May be positive or negative.
   //
   // Note that this could cause an otherwise valid value passed to
   // set_stream_delay_ms() to return an error.
   virtual void set_delay_offset_ms(int offset) = 0;
   virtual int delay_offset_ms() const = 0;
 
+  // Attaches provided webrtc::AecDump for recording debugging
+  // information. Log file and maximum file size logic is supposed to
+  // be handled by implementing instance of AecDump. Calling this
+  // method when another AecDump is attached resets the active AecDump
+  // with a new one. This causes the d-tor of the earlier AecDump to
+  // be called. The d-tor call may block until all pending logging

[peah-webrtc, 2017/05/15 05:32:51]

The blocking part is not good at all. If a new aecdump is created when there is
another existing aecdump, this may render the aecdump unusable (as it will cause
glitches).

Will the d-tor really block? What is causing the need of the d-tor blocking?

[aleloi, 2017/05/15 13:20:52]

After offline discussions d-tor still blocks, but not while holding both the
render and capture locks. If StopDebugDump or DetachAecDump is called from
something which is not the real-time audio thread, audio processing should
continue without glitches.

Short version of why the d-tor blocks:

When an AecDumpImpl object is destoryed, worker threads must not try to access
pointers to it. The WriteToFile tasks have access to 'int64_t
num_bytes_left_for_log_' and, 'FileWrapper* debug_file_', which are owned by
AecDumpImpl. A task queue has no 'flushing' functionality.

We could possibly add a way to notify pending tasks that their AecDumpImpl
pointers are stale and that the task should not be executed. That would imply 
* rewriting a number of AecDump tests, because the current ones rely on every
task being executed
* adding extra locks and complicating the memory pattern.

Another comment: a blocking d-tor is the pattern used in most other places with
a task queue/working thread in WebRTC: AudioSendStream, RTC event log,
VideoSendStream, voice engine channel.

+  // tasks are completed.
+  virtual void AttachAecDump(std::unique_ptr<AecDump> aec_dump) = 0;
+
+  // If no AecDump is attached, this has no effect. If an AecDump is
+  // attached, it's destructor is called. The d-tor may block until
+  // all pending logging tasks are completed.
+  virtual void DetachAecDump() = 0;
+
   // Starts recording debugging information to a file specified by |filename|,
   // a NULL-terminated string. If there is an ongoing recording, the old file
   // will be closed, and recording will continue in the newly specified file.
   // An already existing file will be overwritten without warning. A maximum
   // file size (in bytes) for the log can be specified. The logging is stopped
   // once the limit has been reached. If max_log_size_bytes is set to a value
   // <= 0, no limit will be used.
   static const size_t kMaxFilenameSize = 1024;
   virtual int StartDebugRecording(const char filename[kMaxFilenameSize],
                                   int64_t max_log_size_bytes) = 0;
@@ skipping 614 matching lines @@
   // This does not impact the size of frames passed to |ProcessStream()|.
   virtual int set_frame_size_ms(int size) = 0;
   virtual int frame_size_ms() const = 0;
 
  protected:
   virtual ~VoiceDetection() {}
 };
 }  // namespace webrtc
 
 #endif  // WEBRTC_MODULES_AUDIO_PROCESSING_INCLUDE_AUDIO_PROCESSING_H_