pub struct Signal { /* private fields */ }Expand description
A Rust wrapper for k_poll_signal.
A signal in Zephyr is an event mechanism that can be used to trigger actions in event queues to run. The work somewhat like a kind of half boolean semaphore. The signaling is robust in the direction of the event happening, as in a blocked task will definitely wake when the signal happens. However, the clearing of the signal is racy. Generally, there are two ways to do this:
- A work action can clear the signal as soon as it wakes up, before it starts processing any data the signal was meant to indicate. If the race happens, the processing will handle the extra data.
- A work action can clear the signal after it does it’s processing. This is useful for things like periodic timers, where if it is still processing when an additional timer tick comes in, that timer tick will be ignored. This is useful for periodic events where it is better to just skip a tick rather than for them to “stack up” and get behind.
Notably, as long as the reset method is only ever called by the worker that is waiting upon
it, there shouldn’t ever be a race in the wait_async itself.
Signals can pass a c_int from the signalling task to the task that is waiting for the signal.
It is not specified in the Zephyr documentation what value will be passed if raise is called
multiple times before a task waits upon a signal. The current implementation will return the
most recent raised result value.
For most other use cases, channels or semaphores are likely to be better solutions.
Implementations§
Source§impl Signal
impl Signal
Sourcepub fn reset(&self)
pub fn reset(&self)
Reset the Signal
This resets the signal state to unsignaled.
Please see the Signal documentation on how to handle the races that this implies.
Sourcepub fn check(&self) -> Option<c_int>
pub fn check(&self) -> Option<c_int>
Check the status of a signal.
This reads the status of the signal. If the state is “signalled”, this will return
Some(result) where the result is the result value given to raise.
Sourcepub fn raise(&self, result: c_int) -> Result<()>
pub fn raise(&self, result: c_int) -> Result<()>
Signal a signal object.
This will signal to any worker that is waiting on this object that the event has happened.
The result will be returned from the worker’s wait call.
As per the Zephyr docs, this could return an EAGAIN error if the polling thread is in the process of expiring. The implication is that the signal will not be raised in this case. …
Sourcepub fn wait_async<'a>(
&'a self,
timeout: impl Into<Timeout>,
) -> impl Future<Output = Result<c_int>> + 'a
pub fn wait_async<'a>( &'a self, timeout: impl Into<Timeout>, ) -> impl Future<Output = Result<c_int>> + 'a
Asynchronously wait for a signal to be signaled.
If the signal has not been raised, will wait until it has been. If the signal has been raised, the Future will immediately return that value without waiting.
Note: there is no sync wait, as Zephyr does not provide a convenient mechanmism for
this. It could be implemented with k_poll if needed.