clarification on behavior of functions

[BillyDM]

I'm creating Rust bindings for RtAudio using the C header in https://github.com/thestk/rtaudio/blob/master/rtaudio_c.h.

I have a few questions about the behavior of certain functions. The docs don't make it very clear.

1. When calling the function rtaudio_open_stream(), is it guaranteed that the rtaudio_cb_t callback will not be called until after the rtaudio_start_stream() method is called?

2. When calling the function rtaudio_stop_stream(), does it block the calling thread until the stream is successfully stopped?

3. Likewise, does rtaudio_close_stream() and rtaudio_abort_stream() block the calling thread until the stream is successfully dropped?

4. When the rtaudio_error_cb_t callback passed to the rtaudio_open_stream() function is called, does it mean that the stream was stopped and/or closed because of an error? If so, do all the error types mean that the stream was closed, or do only certain error types mean that the stream was closed?

[BillyDM]

5. Also, is rtaudio_stop_stream() guaranteed to stop the stream and rtaudio_close_stream() guaranteed to close the stream? Or is it when those functions return an error, it means that they failed to do that operation?

[BillyDM]

I found the answer to question 1 in the docs. https://www.music.mcgill.ca/~gary/rtaudio/playback.html

[garyscavone]

First of all, I'm not sure which version of RtAudio you are asking questions about. My answers here pertain to RtAudio.cpp version 6.0.0, beta 1 ... I assume the behaviour implemented in the C API (which I did not create) is similar:

2. The documentation for RtAudio::stopStream() says "Stop a stream, allowing any samples remaining in the output queue to be played." That means that that function blocks (does not return) until samples in the cue are played out (if an output stream). The user provided RtAudioCallback function thus may be called a few times before stopStream() returns.

3. RtAudio:closeStream() will close the stream immediately, release relevant memory and return. RtAudio::abortStream() will stop the stream immediately and return (though the stream remains open in that case).

4. Error handling changed in version 6.0.0, beta 1, with C++ exceptions being discontinued. An error callback can report a warning, in which case the stream remains in the state it was in previously. Non-recoverable errors can be returned from only a few functions, such as openStream, startStream, stopStream, and abortStream.

[BillyDM]

Ok, thanks for the clarification!

A follow-up question about error handling: Does the error callback get used at all while the stream is running? Like if the user unplugs a device while the stream is running, does the error callback get called? And if it does, does it mean that the stream is in an invalid state and should be closed, or will the stream keep running regardless?

[garyscavone]

The desired behaviour if a device in use is unplugged is to close the stream and report the problem via the error callback with the RTAUDIO_DEVICE_DISCONNECT type. However, not all APIs have listeners to detect and deal with such disconnections.

[BillyDM]

Ok cool. I figured that's how it works but I wanted to make sure. Thanks again!