ext/params: clarify flush() dispatch expectations when active - #493
ext/params: clarify flush() dispatch expectations when active#493Yashika0724 wants to merge 2 commits into
Conversation
When a plugin is active but not processing (e.g. transport stopped), flush() must still be called from the audio-thread, not the main-thread. Dispatching flush() from the main-thread in that state violates the "must not be called concurrently to process()" invariant if transport restarts before the flush completes. Also corrects the rationale in request_flush(): the audio-thread prohibition is about re-entrancy, not solely about an ongoing process(). Signed-off-by: Yashika0724 <ssyashika1311@gmail.com>
|
|
|
Hi @abique, If you think the current wording is already clear enough, I’m happy to adjust or drop the change. |
|
Usually an audio engine is still running, although transport is stopped. The term would be "processing is stopped" which process is not being called anymore for some time. |
|
Thanks for the clarification, that makes sense. I’ll update the wording to refer to “processing is stopped” instead of “transport is stopped” to better match the intended terminology. |
Signed-off-by: Yashika0724 <ssyashika1311@gmail.com>
|
Thanks! |
| // - clap_plugin.process() | ||
| // - clap_plugin_params.flush() | ||
| // | ||
| // This function is always safe to use and should not be called from an [audio-thread] as the |
There was a problem hiding this comment.
For me the previous paragraph said everything and shortly.
We could replace the should not by must not.
|
@Yashika0724 thank you again :-) @defiantnerd @baconpaul what do you think of this PR? You know that I prefer shorter documentation where you have the strict minimum info and you can deduce everything else. But overtime, we moved to a more detailed style of documentation and I'm probably not the right person to comment on that PR, so let me know what you think please :-) |
|
So the audio thread is a single thread so I don’t understand the comment that process can’t be concurrent with flush when active since they are both audio thread and there’s only one audio thread. So I don’t think the first clause is that useful the second clause really says “active but not currently processing is still active and when active this is documented as audio thread”. I think that’s a fine clarification as a “for avoidance of doubt” type thing. I would say “for avoidance of doubt an active plugin must still use the audio thread for this even if not processing. This is only available as a main thread function for plugins which are not activated by the host”. |
1e83856 to
275a785
Compare
e71b4fa to
195b42a
Compare
5 participants
This updates the documentation around
flush()andrequest_flush()inext/params.hto clarify the intended threading expectations when a plugin is active but the audio engine is temporarily idle (for example, when the transport is stopped).The existing comments already state that
flush()must not run concurrently withprocess(). This change makes that requirement more explicit in the “active but not processing” case to avoid ambiguity about which thread should dispatchflush().No functional changes are introduced. There are no ABI, struct layout, or behavioral modifications — this is purely a documentation clarification.