From 00255a0561eb192aa98b93c50f248eb9af1ae04f Mon Sep 17 00:00:00 2001 From: Matthias Geier Date: Tue, 25 May 2021 23:29:31 +0200 Subject: [PATCH] DOC: add information about fields of "action" and "stats" --- doc/api.rst | 21 +++++++++++++++++++++ src/rtmixer.py | 3 +++ 2 files changed, 24 insertions(+) diff --git a/doc/api.rst b/doc/api.rst index 41808ed..87a1b63 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -32,7 +32,28 @@ Common parameters that are shared by most commands: All commands return a corresponding "action", which can be compared against the active `actions`, and can be used as input for `cancel()` and `wait()`. +The fields of action objects are defined in C but can be accessed with +Python (e.g. ``my_action.stats.min_blocksize``) +*after* the command is finished: +.. literalinclude:: ../src/rtmixer.h + :language: c + :start-at: struct action + :end-at: flexible array member + :append: }; + +The ``stats`` field contains some statistics collected during playback/recording +(again, *after* the command is finished): + +.. literalinclude:: ../src/rtmixer.h + :language: c + :start-at: struct stats + :end-at: } + +These statistics are also collected for the whole runtime of a stream, +where they are available as `stats` attribute (but only if the stream is +*inactive*). The statistics of an *active* stream can be obtained +(and at the same time reset) with `fetch_and_reset_stats()`. .. autoclass:: Mixer :members: play_buffer, play_ringbuffer, actions, cancel, wait, stats, diff --git a/src/rtmixer.py b/src/rtmixer.py index 28481bb..2dfa306 100644 --- a/src/rtmixer.py +++ b/src/rtmixer.py @@ -82,6 +82,9 @@ def cancel(self, action, time=0, allow_belated=True): def fetch_and_reset_stats(self, time=0, allow_belated=True): """Fetch and reset over-/underflow statistics of the stream. + The statistics will be available in the ``stats`` field of the + returned action. + """ action = _ffi.new('struct action*', dict( type=FETCH_AND_RESET_STATS,