Cancellation
Functions Index
| static QarResult | qar_cancel_token_cancel (QarCancelToken *token) |
|
Signal cancellation on a token. More... | |
| static QarResult | qar_cancel_token_cancel_after (QarCancelToken *token, uint32_t timeout_ms) |
|
Schedule cancellation after timeout_ms. More... | |
| static QarResult | qar_cancel_token_create (QarCancelToken **out_token) |
|
Create a new cancellation token (non-signaled). More... | |
| static QarResult | qar_cancel_token_create_with_timeout (QarCancelToken **out_token, uint32_t timeout_ms) |
|
Create a token that auto-cancels after timeout_ms. More... | |
| static void | qar_cancel_token_handle_destroy (QarCancelToken *handle) |
|
Destroy a token handle, cancelling what it owns. More... | |
| static bool | qar_cancel_token_is_cancelled (const QarCancelToken *token) |
|
Check if token was canceled. More... | |
| static bool | qar_cancel_token_is_timeout (const QarCancelToken *token) |
|
Check if token reached its timeout. More... | |
Description
Ending a subscription. Every qar_*_subscribe_* function hands its subscription to the cancel token passed to it (where a NULL token is allowed, the subscription is the session's alone). These calls end it: qar_cancel_token_cancel() and qar_cancel_token_handle_destroy() on that token, qar_session_handle_destroy() on its session, qar_library_destroy(). When one of them returns:
- a callback of the subscription that was running on another thread has returned: the call waited for it,
- no callback of the subscription starts afterwards.
So user_state only has to stay valid until that call returns, and may be freed right after it.
From inside the subscription's own callback a call cannot wait for the callback it is made from. qar_cancel_token_cancel() and qar_cancel_token_handle_destroy() are allowed there: they return without waiting for that callback, which then finishes normally, and no further callback of the subscription starts. Keep user_state valid until that callback returns. Do not destroy the session or the library from a callback.
Waiting for a callback means: do not end a subscription while holding a lock its callback takes, and do not end subscription A from a callback of subscription B while a callback of B can be ending A.
A token's timeout (qar_cancel_token_create_with_timeout(), qar_cancel_token_cancel_after()) stops its subscriptions shortly after it expires but does not wait for a running callback. Cancel or destroy the token before freeing user_state.
Functions
qar_cancel_token_cancel()
| inline static |
Signal cancellation on a token.
Ends every subscription started with it: returns once no callback of those subscriptions is running on another thread, and none starts afterwards. Called from inside one of their callbacks it does not wait for that callback; see Ending a subscription.
Definition at line 2222 of file qar_streaming.h.
qar_cancel_token_cancel_after()
| inline static |
Schedule cancellation after timeout_ms.
Definition at line 2225 of file qar_streaming.h.
qar_cancel_token_create()
| inline static |
Create a new cancellation token (non-signaled).
Definition at line 2202 of file qar_streaming.h.
qar_cancel_token_create_with_timeout()
| inline static |
Create a token that auto-cancels after timeout_ms.
Definition at line 2204 of file qar_streaming.h.
qar_cancel_token_handle_destroy()
| inline static |
Destroy a token handle, cancelling what it owns.
Ends every subscription started with it, waiting for a running callback; see Ending a subscription.
Definition at line 2213 of file qar_streaming.h.
qar_cancel_token_is_cancelled()
| inline static |
Check if token was canceled.
Definition at line 2227 of file qar_streaming.h.
qar_cancel_token_is_timeout()
| inline static |
Check if token reached its timeout.
Definition at line 2229 of file qar_streaming.h.
Generated via doxygen2docusaurus 2.2.1 by Doxygen 1.9.8.