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, \
        .state = K_POLL_STATE_NOT_READY, \
        .mode = _event_mode, \
        .unused = 0, \
        { \
                .obj = _event_obj, \
        }, \
        }

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, \
        .state = K_POLL_STATE_NOT_READY, \
        .mode = _event_mode, \
        .unused = 0, \
        { \
                .obj = _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, \
        }

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

enum 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

events	An array of events to be polled for.
num_events	The number of events in the array.
timeout	Waiting period for an event to be ready, or one of the special values K_NO_WAIT and K_FOREVER.

Return values

0	One or more events are ready.
-EAGAIN	Waiting period timed out.
-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.
-ENOMEM	Thread resource pool insufficient memory (user mode only)
-EINVAL	Bad 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

event	The event to initialize.
type	A 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.
mode	Future. Use K_POLL_MODE_NOTIFY_ONLY.
obj	Kernel 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

sig	A poll signal object
signaled	An integer buffer which will be written nonzero if the object was signaled
result	An 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

sig	A 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

sig	A poll signal.
result	The value to store in the result field of the signal.

Return values

0	The signal was delivered successfully.
-EAGAIN	The 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

sig	A poll signal object