Document Callback Threading Behavior

[LinuxMainframe]

Low: Document Callback Threading Behavior

Priority: LOW

Type: Documentation

Location

Various callback invocations throughout libwsv5.c

Issue

The threading behavior of callbacks is not clearly documented. Specifically:

1. Which thread calls the callback?

   • Event callbacks are called from background event_thread
   • State callbacks are called from whichever thread changes state
   • Log callbacks can be called from any thread

2. Can callbacks call back into the library?

   • Yes, but not clearly documented
   • Mutexes are released before callbacks (good design)
   • But users don't know this is safe

3. Should callbacks block?

   • No, but not documented
   • Blocking callback would stall event processing

Impact

• Users don't know if callbacks are thread-safe
• Users might avoid calling library functions from callbacks unnecessarily
• Users might cause deadlocks by blocking in callbacks