BusStream: Missing details about internal sync handler usage in docs

https://docs.rs/gstreamer/latest/gstreamer/bus/struct.BusStream.html looks to be rather empty in terms of documentation and I used it based on example code.

Turns out that:

1. It uses gst::Bus::set_sync_handler internally, so it can't be combined in user code together with one when wanting to process some bus message types synchronously, as gstreamer supports only one being installed, so whichever is made first (user code set_sync_handler call vs BusStream creation via .stream() ) doesn't function.
2. It is async, while making use of the GstBus sync handler. While on hindsight it being async obvious, it might be worth a note.
3. As a non-doc note, I wonder if it actually could be implemented through gstreamer message bus async handler methods - if it's async anyways due to async/await usage, maybe it should not tie up the sync handler slot and thus actually allow using together with some messages getting handled via applications own sync handler callback, which then gets to decide if the "async" handler (BusStream) gets to see this via appropriate GstBusSyncReply return from it.

So it'd be nice to have some documentation for BusStream, and some of these aspects in particular.

cc @slomo as he asked me to file this to look at it :)

As a non-doc note, I wonder if it actually could be implemented through gstreamer message bus async handler methods - if it's async anyways due to async/await usage, maybe it should not tie up the sync handler slot and thus actually allow using together with some messages getting handled via applications own sync handler callback, which then gets to decide if the "async" handler (BusStream) gets to see this via appropriate GstBusSyncReply return from it.

The async message delivery methods that are built-in are:

• Bus watch: requires a GLib main loop
• pollfd: requires fd integration with a specific async runtime for waking up

That's why this currently uses the sync bus handler. Do you see a way how that can be made to work?

My idea to make this less confusing would be to allow setting a sync bus handler in addition to using the stream. This could be done by storing the channel and the sync bus handler callback together in a refcounted struct in the bus' qdata, for example.

Can't we use a sync signal for the BusStream so the user could override the sync_handler?

Also as it is now, it is still possible to enable_sync_message and connect to the signal (but the signal doesn't return anything so you can't stop propagation from there).

Signals have a lot of overhead, which seems like a bad idea especially for a sync bus handler

Right, I wonder if that could end up being a bottleneck in practice. Anyway maybe allowing to add_sync_handler at the C level would make sense.

With multiple sync handlers you need to worry about order like with signals, so would have to be something like prepend/append probably. But doing that would probably be a good idea and also doesn't complicate the implementation a lot.

For older GStreamer versions, the bindings could implement something around qdata