Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Async polling APIs

Data Structures

struct  k_poll_signal
 
struct  k_poll_event
 Poll Event. More...
 

Macros

#define K_POLL_TYPE_IGNORE   0
 
#define K_POLL_TYPE_SIGNAL   Z_POLL_TYPE_BIT(_POLL_TYPE_SIGNAL)
 
#define K_POLL_TYPE_SEM_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_SEM_AVAILABLE)
 
#define K_POLL_TYPE_DATA_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_DATA_AVAILABLE)
 
#define K_POLL_TYPE_FIFO_DATA_AVAILABLE   K_POLL_TYPE_DATA_AVAILABLE
 
#define K_POLL_TYPE_MSGQ_DATA_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_MSGQ_DATA_AVAILABLE)
 
#define K_POLL_TYPE_PIPE_DATA_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_PIPE_DATA_AVAILABLE)
 
#define K_POLL_STATE_NOT_READY   0
 
#define K_POLL_STATE_SIGNALED   Z_POLL_STATE_BIT(_POLL_STATE_SIGNALED)
 
#define K_POLL_STATE_SEM_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_SEM_AVAILABLE)
 
#define K_POLL_STATE_DATA_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_DATA_AVAILABLE)
 
#define K_POLL_STATE_FIFO_DATA_AVAILABLE   K_POLL_STATE_DATA_AVAILABLE
 
#define K_POLL_STATE_MSGQ_DATA_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_MSGQ_DATA_AVAILABLE)
 
#define K_POLL_STATE_PIPE_DATA_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_PIPE_DATA_AVAILABLE)
 
#define K_POLL_STATE_CANCELLED   Z_POLL_STATE_BIT(_POLL_STATE_CANCELLED)
 
#define K_POLL_SIGNAL_INITIALIZER(obj)
 
#define K_POLL_EVENT_INITIALIZER(_event_type, _event_mode, _event_obj)
 
#define K_POLL_EVENT_STATIC_INITIALIZER(_event_type, _event_mode, _event_obj, event_tag)
 

Enumerations

enum  k_poll_modes { K_POLL_MODE_NOTIFY_ONLY = 0 , K_POLL_NUM_MODES }
 

Functions

void k_poll_event_init (struct k_poll_event *event, uint32_t type, int mode, void *obj)
 Initialize one struct k_poll_event instance.
 
int k_poll (struct k_poll_event *events, int num_events, k_timeout_t timeout)
 Wait for one or many of multiple poll events to occur.
 
void k_poll_signal_init (struct k_poll_signal *sig)
 Initialize a poll signal object.
 
void k_poll_signal_reset (struct k_poll_signal *sig)
 Reset a poll signal object's state to unsignaled.
 
void k_poll_signal_check (struct k_poll_signal *sig, unsigned int *signaled, int *result)
 Fetch the signaled state and result value of a poll signal.
 
int k_poll_signal_raise (struct k_poll_signal *sig, int result)
 Signal a poll signal object.
 

Detailed Description

Macro Definition Documentation

◆ K_POLL_EVENT_INITIALIZER

#define K_POLL_EVENT_INITIALIZER (   _event_type,
  _event_mode,
  _event_obj 
)

#include <zephyr/kernel.h>

Value:
{ \
.poller = NULL, \
.type = _event_type, \
.mode = _event_mode, \
.unused = 0, \
{ \
.typed_##_event_type = _event_obj, \
}, \
}
#define K_POLL_STATE_NOT_READY
Definition: kernel.h:5681

◆ K_POLL_EVENT_STATIC_INITIALIZER

#define K_POLL_EVENT_STATIC_INITIALIZER (   _event_type,
  _event_mode,
  _event_obj,
  event_tag 
)

#include <zephyr/kernel.h>

Value:
{ \
.tag = event_tag, \
.type = _event_type, \
.mode = _event_mode, \
.unused = 0, \
{ \
.typed_##_event_type = _event_obj, \
}, \
}

◆ K_POLL_SIGNAL_INITIALIZER

#define K_POLL_SIGNAL_INITIALIZER (   obj)

#include <zephyr/kernel.h>

Value:
{ \
.poll_events = SYS_DLIST_STATIC_INIT(&obj.poll_events), \
.signaled = 0, \
.result = 0, \
}
#define SYS_DLIST_STATIC_INIT(ptr_to_list)
Static initializer for a doubly-linked list.
Definition: dlist.h:211

◆ K_POLL_STATE_CANCELLED

#define K_POLL_STATE_CANCELLED   Z_POLL_STATE_BIT(_POLL_STATE_CANCELLED)

#include <zephyr/kernel.h>

◆ K_POLL_STATE_DATA_AVAILABLE

#define K_POLL_STATE_DATA_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_DATA_AVAILABLE)

#include <zephyr/kernel.h>

◆ K_POLL_STATE_FIFO_DATA_AVAILABLE

#define K_POLL_STATE_FIFO_DATA_AVAILABLE   K_POLL_STATE_DATA_AVAILABLE

#include <zephyr/kernel.h>

◆ K_POLL_STATE_MSGQ_DATA_AVAILABLE

#define K_POLL_STATE_MSGQ_DATA_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_MSGQ_DATA_AVAILABLE)

#include <zephyr/kernel.h>

◆ K_POLL_STATE_NOT_READY

#define K_POLL_STATE_NOT_READY   0

#include <zephyr/kernel.h>

◆ K_POLL_STATE_PIPE_DATA_AVAILABLE

#define K_POLL_STATE_PIPE_DATA_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_PIPE_DATA_AVAILABLE)

#include <zephyr/kernel.h>

◆ K_POLL_STATE_SEM_AVAILABLE

#define K_POLL_STATE_SEM_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_SEM_AVAILABLE)

#include <zephyr/kernel.h>

◆ K_POLL_STATE_SIGNALED

#define K_POLL_STATE_SIGNALED   Z_POLL_STATE_BIT(_POLL_STATE_SIGNALED)

#include <zephyr/kernel.h>

◆ K_POLL_TYPE_DATA_AVAILABLE

#define K_POLL_TYPE_DATA_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_DATA_AVAILABLE)

#include <zephyr/kernel.h>

◆ K_POLL_TYPE_FIFO_DATA_AVAILABLE

#define K_POLL_TYPE_FIFO_DATA_AVAILABLE   K_POLL_TYPE_DATA_AVAILABLE

#include <zephyr/kernel.h>

◆ K_POLL_TYPE_IGNORE

#define K_POLL_TYPE_IGNORE   0

#include <zephyr/kernel.h>

◆ K_POLL_TYPE_MSGQ_DATA_AVAILABLE

#define K_POLL_TYPE_MSGQ_DATA_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_MSGQ_DATA_AVAILABLE)

#include <zephyr/kernel.h>

◆ K_POLL_TYPE_PIPE_DATA_AVAILABLE

#define K_POLL_TYPE_PIPE_DATA_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_PIPE_DATA_AVAILABLE)

#include <zephyr/kernel.h>

◆ K_POLL_TYPE_SEM_AVAILABLE

#define K_POLL_TYPE_SEM_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_SEM_AVAILABLE)

#include <zephyr/kernel.h>

◆ K_POLL_TYPE_SIGNAL

#define K_POLL_TYPE_SIGNAL   Z_POLL_TYPE_BIT(_POLL_TYPE_SIGNAL)

#include <zephyr/kernel.h>

Enumeration Type Documentation

◆ k_poll_modes

#include <zephyr/kernel.h>

Enumerator
K_POLL_MODE_NOTIFY_ONLY 
K_POLL_NUM_MODES 

Function Documentation

◆ k_poll()

int k_poll ( struct k_poll_event events,
int  num_events,
k_timeout_t  timeout 
)

#include <zephyr/kernel.h>

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.

Parameters
eventsAn array of events to be polled for.
num_eventsThe number of events in the array.
timeoutWaiting period for an event to be ready, or one of the special values K_NO_WAIT and K_FOREVER.
Return values
0One or more events are ready.
-EAGAINWaiting period timed out.
-EINTRPolling 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.
-ENOMEMThread resource pool insufficient memory (user mode only)
-EINVALBad parameters (user mode only)

◆ k_poll_event_init()

void k_poll_event_init ( struct k_poll_event event,
uint32_t  type,
int  mode,
void *  obj 
)

#include <zephyr/kernel.h>

Initialize one struct k_poll_event instance.

After this routine is called on a poll event, the event it ready to be placed in an event array to be passed to k_poll().

Parameters
eventThe event to initialize.
typeA bitfield of the types of event, from the K_POLL_TYPE_xxx values. Only values that apply to the same object being polled can be used together. Choosing K_POLL_TYPE_IGNORE disables the event.
modeFuture. Use K_POLL_MODE_NOTIFY_ONLY.
objKernel object or poll signal.

◆ k_poll_signal_check()

void k_poll_signal_check ( struct k_poll_signal sig,
unsigned int *  signaled,
int *  result 
)

#include <zephyr/kernel.h>

Fetch the signaled state and result value of a poll signal.

Parameters
sigA poll signal object
signaledAn integer buffer which will be written nonzero if the object was signaled
resultAn integer destination buffer which will be written with the result value if the object was signaled, or an undefined value if it was not.

◆ k_poll_signal_init()

void k_poll_signal_init ( struct k_poll_signal sig)

#include <zephyr/kernel.h>

Initialize a poll signal object.

Ready a poll signal object to be signaled via k_poll_signal_raise().

Parameters
sigA poll signal.

◆ k_poll_signal_raise()

int k_poll_signal_raise ( struct k_poll_signal sig,
int  result 
)

#include <zephyr/kernel.h>

Signal a poll signal object.

This routine makes ready a poll signal, which is basically a poll event of type K_POLL_TYPE_SIGNAL. If a thread was polling on that event, it will be made ready to run. A result value can be specified.

The poll signal contains a 'signaled' field that, when set by k_poll_signal_raise(), stays set until the user sets it back to 0 with k_poll_signal_reset(). It thus has to be reset by the user before being passed again to k_poll() or k_poll() will consider it being signaled, and will return immediately.

Note
The result is stored and the 'signaled' field is set even if this function returns an error indicating that an expiring poll was not notified. The next k_poll() will detect the missed raise.
Parameters
sigA poll signal.
resultThe value to store in the result field of the signal.
Return values
0The signal was delivered successfully.
-EAGAINThe polling thread's timeout is in the process of expiring.

◆ k_poll_signal_reset()

void k_poll_signal_reset ( struct k_poll_signal sig)

#include <zephyr/kernel.h>

Reset a poll signal object's state to unsignaled.

Parameters
sigA poll signal object