From 8eeace9f23557fb8bdeb29ce19741539be89cf47 Mon Sep 17 00:00:00 2001 From: Thomas Karpiniec Date: Sun, 16 Aug 2026 21:32:48 +1000 Subject: [PATCH] Document callback delivery thread and timing 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 --- src/lib.rs | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 35e1932..e3bc524 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -448,16 +448,18 @@ pub fn list_interfaces() -> Result, Error> { /// If setting up the watch is successful, this returns a `WatchHandle` which must be kept for /// as long as the provided callback should operate. /// -/// The callback will fire once immediately with an initial interface list, and a diff as if -/// there were originally no interfaces present. +/// The callback is invoked once, synchronously before this function returns, with an initial +/// interface list and a diff as if there were originally no interfaces present. Subsequent +/// callbacks, including any that race with initialisation, are delivered on a platform-defined +/// thread that is not necessarily the thread that called this function, and may arrive before or +/// after this function returns. Do not rely on a particular delivery thread or on the timing of +/// later updates relative to this function returning. /// -/// The initial callback and any catch-up callbacks for notifications racing initialisation are -/// invoked synchronously before this function returns. Callbacks after initialisation execute from -/// platform notification context. If the initial callback panics, watcher construction unwinds and -/// no watcher remains registered. With the default unwinding panic strategy, a later callback panic -/// is contained and permanently disables that callback watcher without affecting other watchers. -/// The panic hook still runs, and the returned handle remains safe to drop. With `panic = "abort"`, -/// any panic still aborts the process. +/// If the initial callback panics, watcher construction unwinds and no watcher remains registered. +/// With the default unwinding panic strategy, a later callback panic is contained and permanently +/// disables that callback watcher without affecting other watchers. The panic hook still runs, and +/// the returned handle remains safe to drop. With `panic = "abort"`, any panic still aborts the +/// process. /// /// This function will return an error if there is a problem configuring the watcher, or if there /// is an error retrieving the initial interface list.