Merge pull request #131 from larsewi/document-lch-log-init

Document lch_log_init thread-safety and re-entrance contract

Author: larsewi

include/leech2.h

@@ -48,11 +48,22 @@ typedef void (*lch_log_callback_t)(lch_log_level_t level, const char *msg,
  * Initialize logging with a callback.
  *
  * Installs a custom logger that delivers all log messages through @p callback.
- * Must be called before lch_init() for the callback to receive messages.
- * May be called again to replace the callback.
+ * Must be called before lch_init() for the callback to receive messages from
+ * initialization.
+ *
+ * May be called again to atomically replace @p callback and @p usr_data. After
+ * a replacement, the previous callback is no longer invoked; the library does
+ * not free the previous @p usr_data, so the caller is responsible for its
+ * lifetime.
+ *
+ * Safe to call concurrently from multiple threads. Once installed, @p callback
+ * itself may be invoked from any thread, possibly in parallel, so both
+ * @p callback and @p usr_data must be thread-safe.
  *
  * @param callback  Function to receive log messages (must not be NULL).
- * @param usr_data  Opaque pointer forwarded to every callback invocation.
+ * @param usr_data  Opaque pointer forwarded to every callback invocation. Must
+ *                  remain valid until the callback is replaced by a later
+ *                  lch_log_init() call or the process exits.
  * @return LCH_SUCCESS on success, LCH_FAILURE on error.
  */
 extern int lch_log_init(lch_log_callback_t callback, void *usr_data);

man/libleech2.3.in

@@ -47,16 +47,33 @@ Install a custom logger that delivers all log messages through
 .IR callback .
 Must be called before
 .BR lch_init ()
-for the callback to receive messages from initialization. May be called again to
-replace the callback. Returns
+for the callback to receive messages from initialization. May be called again
+to atomically replace
+.I callback
+and
+.IR usr_data ;
+after a replacement the previous callback is no longer invoked, and the library
+does not free the previous
+.IR usr_data ,
+so the caller owns its lifetime. Safe to call concurrently from multiple
+threads. Once installed,
+.I callback
+itself may be invoked from any thread, possibly in parallel, so both
+.I callback
+and
+.I usr_data
+must be thread-safe.
+.I callback
+must not be NULL.
+.I usr_data
+is an opaque pointer forwarded to every callback invocation and must remain
+valid until the callback is replaced by a later
+.BR lch_log_init ()
+call or the process exits. Returns
 .B LCH_SUCCESS
 on success and
 .B LCH_FAILURE
 on error.
-.I callback
-must not be NULL.
-.I usr_data
-is an opaque pointer forwarded to every callback invocation.
 .SS Lifecycle
 .TP
 .BI "lch_config_t *lch_init(const char *" work_dir )

src/lib.rs

@@ -36,10 +36,21 @@ fn ffi_guard<T>(name: &str, default: T, body: impl FnOnce() -> T) -> T {
     }
 }
 
+/// Install or replace the log callback.
+///
+/// The first call installs the global logger; subsequent calls atomically swap
+/// the callback and `user_data`. After a swap, the old callback is no longer
+/// invoked, but the library does not free or otherwise touch the previous
+/// `user_data` — the caller owns its lifetime and must release it if needed.
+///
+/// Safe to call concurrently from multiple threads. Once installed, the
+/// callback itself may be invoked from any thread (including in parallel),
+/// so both `callback` and `user_data` must be thread-safe.
+///
 /// # Safety
 /// `callback` must be a valid function pointer; passing NULL returns `LCH_FAILURE`.
-/// `user_data` must be valid for the lifetime of the callback and safe to
-/// access from any thread.
+/// `user_data` must remain valid until either the callback is replaced by a
+/// later `lch_log_init` call or the process exits.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn lch_log_init(
     callback: Option<unsafe extern "C" fn(i32, *const c_char, *mut c_void)>,