pub unsafe extern "C" fn k_poll(
events: *mut k_poll_event,
num_events: i32,
timeout: k_timeout_t,
) -> i32Expand description
@brief Wait for one or many of multiple poll events to occur
This routine allows a thread to wait concurrently for one or many of multiple poll events to have occurred. Such events can be a kernel object being available, like a semaphore, or a poll signal event.
When an event notifies that a kernel object is available, the kernel object is not “given” to the thread calling k_poll(): it merely signals the fact that the object was available when the k_poll() call was in effect. Also, all threads trying to acquire an object the regular way, i.e. by pending on the object, have precedence over the thread polling on the object. This means that the polling thread will never get the poll event on an object until the object becomes available and its pend queue is empty. For this reason, the k_poll() call is more effective when the objects being polled only have one thread, the polling thread, trying to acquire them.
When k_poll() returns 0, the caller should loop on all the events that were passed to k_poll() and check the state field for the values that were expected and take the associated actions.
Before being reused for another call to k_poll(), the user has to reset the state field to K_POLL_STATE_NOT_READY.
When called from user mode, a temporary memory allocation is required from the caller’s resource pool.
@param events An array of events to be polled for. @param num_events The number of events in the array. @param timeout Waiting period for an event to be ready, or one of the special values K_NO_WAIT and K_FOREVER.
@retval 0 One or more events are ready. @retval -EAGAIN Waiting period timed out. @retval -EINTR Polling has been interrupted, e.g. with k_queue_cancel_wait(). All output events are still set and valid, cancelled event(s) will be set to K_POLL_STATE_CANCELLED. In other words, -EINTR status means that at least one of output events is K_POLL_STATE_CANCELLED. @retval -ENOMEM Thread resource pool insufficient memory (user mode only) @retval -EINVAL Bad parameters (user mode only)