diff --git a/doc/reference/kernel/other/polling.rst b/doc/reference/kernel/other/polling.rst index b114933300a..afce6d8f9c7 100644 --- a/doc/reference/kernel/other/polling.rst +++ b/doc/reference/kernel/other/polling.rst @@ -255,6 +255,18 @@ If the signal is to be polled in a loop, *both* its event state and its } } +Note that poll signals are not internally synchronized. A k_poll call +that is passed a signal will return after any code in the system calls +:c:func:`k_poll_signal_raise()`. But if the signal is being +externally managed and reset via :c:func:`k_poll_signal_init()`, it is +possible that by the time the application checks, the event state may +no longer be equal to :c:macro:`K_POLL_STATE_SIGNALED`, and a (naive) +application will miss events. Best practice is always to reset the +signal only from within the thread invoking the k_poll() loop, or else +to use some other event type which tracks event counts: semaphores and +FIFOs more more error-proof in thise sense because they can't "miss" +events, architecturally. + Suggested Uses **************