Skip to content

Document callback delivery thread and timing - #39

Merged
thombles merged 1 commit into
mainfrom
callback-init-docs
Aug 16, 2026
Merged

thombles merged 1 commit into
mainfrom
callback-init-docs

Conversation

@thombles

Copy link
Copy Markdown
Owner

Fixes #32.

The public docs for watch_interfaces_with_callback promised that the initial callback and any catch-up callbacks racing initialisation complete synchronously before the function returns. That ordering is only enforced on Android; on Unix and Windows racing notifications are dispatched on a worker thread or the OS notification thread with no ordering relative to the constructor returning.

This revises the docs to promise only what holds on every platform: the initial callback is invoked synchronously before return. Subsequent callbacks are documented as running on a platform-defined thread (not necessarily the caller's) and as possibly arriving before or after return.

The previous doc promised that the initial callback and any catch-up
callbacks racing initialisation complete synchronously before
watch_interfaces_with_callback returns. That is only guaranteed on
Android; Unix and Windows deliver racing notifications on a worker or
OS thread with no ordering relative to the constructor returning.

Revise the docs to promise only the initial callback's synchronous
pre-return delivery, and to state that subsequent callbacks run on a
platform-defined thread and may arrive before or after return.

Fixes #32
@thombles
thombles merged commit 566b741 into main Aug 16, 2026
5 of 6 checks passed
@thombles
thombles deleted the callback-init-docs branch August 16, 2026 11:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Callback initialization timing contract is not guaranteed on Unix and Windows

1 participant