[vlc-devel] [PATCH] aout: modify module API: make modules non-blocking

[Thomas Guillem]

I propose this new API. It is still WIP, I need to modify the core and modules
to make sure it is possible.
---
 include/vlc_aout.h | 48 +++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 41 insertions(+), 7 deletions(-)

diff --git a/include/vlc_aout.h b/include/vlc_aout.h
index a4ae6bc498..a42121ad65 100644
--- a/include/vlc_aout.h
+++ b/include/vlc_aout.h
@@ -112,6 +112,8 @@
 #include <vlc_block.h>
 
 struct vlc_audio_output_events {
+    void (*more_data_report)(audio_output_t *);
+    void (*drain_report)(audio_output_t *);
     void (*timing_report)(audio_output_t *, vlc_tick_t system_now, vlc_tick_t pts);
     void (*volume_report)(audio_output_t *, float);
     void (*mute_report)(audio_output_t *, bool);
@@ -134,6 +136,9 @@ struct vlc_audio_output_events {
  * The audio output is always created in stopped state and is always destroyed
  * in that state also. It is moved from stopped to playing state by start(),
  * and from playing or paused states back to stopped state by stop().
+ *
+ * \note every callback implementations must be NON-BLOCKING
+ * TODO: Make all aout modules non-blocking for 4.0
  **/
 struct audio_output
 {
@@ -186,12 +191,18 @@ struct audio_output
       * \note This callback cannot be called in stopped state.
       */
 
-    void (*play)(audio_output_t *, block_t *block, vlc_tick_t date);
+    block_t *(*play)(audio_output_t *, block_t *block, vlc_tick_t date);
     /**< Queues a block of samples for playback (mandatory, cannot be NULL).
+      *
+      * As the play implementation must be non-blocking, the implementation is
+      * allowed to return prematurely if the audio buffer is full. In that
+      * case, the implementation must call aout_MoreDataReport() when data can
+      * be written again.
       *
       * \param block block of audio samples
       * \param date intended system time to render the first sample
-      *
+      * \return the same block with modified offset in case of incomplete
+      * playback (cf. description)
       * \note This callback cannot be called in stopped state.
       */
 
@@ -212,15 +223,18 @@ struct audio_output
       * \note This callback cannot be called in stopped state.
       */
 
-    void (*flush)( audio_output_t *, bool wait);
+    void (*flush)( audio_output_t *);
     /**< Flushes or drains the playback buffers (mandatory, cannot be NULL).
-      *
-      * \param wait true to wait for playback of pending buffers (drain),
-      *             false to discard pending buffers (flush)
       *
       * \note This callback cannot be called in stopped state.
       */
 
+    bool (*drain)(audio_output_t *);
+    /**< Drain pending buffers asynchronously
+      *
+      * \return true if drained, false if the end of the drain will be reported
+      * asynchronously via aout_DrainReport() */
+
     int (*volume_set)(audio_output_t *, float volume);
     /**< Changes playback volume (optional, may be NULL).
       *
@@ -376,6 +390,26 @@ VLC_API char *aout_DeviceGet (audio_output_t *);
 VLC_API int aout_DeviceSet (audio_output_t *, const char *);
 VLC_API int aout_DevicesList (audio_output_t *, char ***, char ***);
 
+/**
+ * Report that the stream need more data
+ *
+ * \note Must be called only after an incomplete aout->play.
+ */
+static inline void aout_MoreDataReport(audio_output_t *aout)
+{
+   aout->events->more_data_report(aout);
+}
+
+/**
+ * Report that the drain is finished
+ *
+ * \note must be called only after aout->drain returning false.
+ */
+static inline void aout_DrainReport(audio_output_t *aout)
+{
+    aout->events->drain_report(aout);
+}
+
 /**
  * Report change of configured audio volume to the core and UI.
  */
@@ -456,7 +490,7 @@ static inline void aout_PauseDefault(audio_output_t *aout, bool paused,
                                      vlc_tick_t date)
 {
     if (paused && aout->flush != NULL)
-        aout->flush(aout, false);
+        aout->flush(aout);
     (void) date;
 }
 
-- 
2.20.1