Async polling APIs

An API to wait concurrently for any one of multiple conditions to be fulfilled. More...

Data Structures
struct	k_poll_signal
	Poll signal object. More...
struct	k_poll_event
	Poll Event. More...

Macros
#define	K_POLL_SIGNAL_INITIALIZER(obj)
	Statically initialize a poll signal.
#define	K_POLL_EVENT_INITIALIZER(_event_type, _event_mode, _event_obj)
	Statically initialize a poll event.
#define	K_POLL_EVENT_STATIC_INITIALIZER(_event_type, _event_mode, _event_obj, event_tag)
	Statically initialize a poll event, with a user tag.

Enumerations
enum	k_poll_modes { K_POLL_MODE_NOTIFY_ONLY = 0 , K_POLL_NUM_MODES }
	Modes of operation of a poll event. More...

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.

Poll event types
Values for the k_poll_event.type bitfield.
#define	K_POLL_TYPE_IGNORE   0
	Event is ignored by k_poll().
#define	K_POLL_TYPE_SIGNAL   Z_POLL_TYPE_BIT(_POLL_TYPE_SIGNAL)
	Poll for a raised poll signal.
#define	K_POLL_TYPE_SEM_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_SEM_AVAILABLE)
	Poll for a semaphore becoming available.
#define	K_POLL_TYPE_DATA_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_DATA_AVAILABLE)
	Poll for data becoming available in a queue.
#define	K_POLL_TYPE_FIFO_DATA_AVAILABLE   K_POLL_TYPE_DATA_AVAILABLE
	Poll for data becoming available in a FIFO.
#define	K_POLL_TYPE_LIFO_DATA_AVAILABLE   K_POLL_TYPE_DATA_AVAILABLE
	Poll for data becoming available in a LIFO.
#define	K_POLL_TYPE_MSGQ_DATA_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_MSGQ_DATA_AVAILABLE)
	Poll for data becoming available in a message queue.
#define	K_POLL_TYPE_PIPE_DATA_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_PIPE_DATA_AVAILABLE)
	Poll for data becoming available in a pipe.

Poll event states
Values for the k_poll_event.state bitfield.
#define	K_POLL_STATE_NOT_READY   0
	Condition being polled for has not occurred yet.
#define	K_POLL_STATE_SIGNALED   Z_POLL_STATE_BIT(_POLL_STATE_SIGNALED)
	Poll signal was raised.
#define	K_POLL_STATE_SEM_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_SEM_AVAILABLE)
	Semaphore became available.
#define	K_POLL_STATE_DATA_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_DATA_AVAILABLE)
	Data became available in a queue.
#define	K_POLL_STATE_FIFO_DATA_AVAILABLE   K_POLL_STATE_DATA_AVAILABLE
	Data became available in a FIFO.
#define	K_POLL_STATE_LIFO_DATA_AVAILABLE   K_POLL_STATE_DATA_AVAILABLE
	Data became available in a LIFO.
#define	K_POLL_STATE_MSGQ_DATA_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_MSGQ_DATA_AVAILABLE)
	Data became available in a message queue.
#define	K_POLL_STATE_PIPE_DATA_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_PIPE_DATA_AVAILABLE)
	Data became available in a pipe.
#define	K_POLL_STATE_CANCELLED   Z_POLL_STATE_BIT(_POLL_STATE_CANCELLED)
	Wait on the polled object was cancelled, e.g.

Detailed Description

An API to wait concurrently for any one of multiple conditions to be fulfilled.

Macro Definition Documentation

K_POLL_EVENT_INITIALIZER

#define K_POLL_EVENT_INITIALIZER	(		_event_type,
			_event_mode,
			_event_obj )

#include <kernel.h>

Value:

{ \
.poller = NULL, \
.type = _event_type, \
.state = K_POLL_STATE_NOT_READY, \
.mode = _event_mode, \
.unused = 0, \
{ \
        ._typed_##_event_type = _event_obj, \
}, \
}

Statically initialize a poll event.

Parameters

_event_type	Type of the event; one of the K_POLL_TYPE_xxx values.
_event_mode	Mode of operation; one of the enum k_poll_modes values.
_event_obj	Address of the kernel object or poll signal being polled, matching the event type.

K_POLL_EVENT_STATIC_INITIALIZER

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

#include <kernel.h>

Value:

{ \
.tag = event_tag, \
.type = _event_type, \
.state = K_POLL_STATE_NOT_READY, \
.mode = _event_mode, \
.unused = 0, \
{ \
        ._typed_##_event_type = _event_obj, \
}, \
}

Statically initialize a poll event, with a user tag.

Parameters

_event_type	Type of the event; one of the K_POLL_TYPE_xxx values.
_event_mode	Mode of operation; one of the enum k_poll_modes values.
_event_obj	Address of the kernel object or poll signal being polled, matching the event type.
event_tag	Opaque user-specified tag.

K_POLL_SIGNAL_INITIALIZER

#define K_POLL_SIGNAL_INITIALIZER

(

obj

)

#include <kernel.h>

Value:

{ \
.poll_events = SYS_DLIST_STATIC_INIT(&obj.poll_events), \
.signaled = 0, \
.result = 0, \
}

Statically initialize a poll signal.

Parameters

obj	Name of the struct k_poll_signal instance being initialized.

K_POLL_STATE_CANCELLED

#define K_POLL_STATE_CANCELLED   Z_POLL_STATE_BIT(_POLL_STATE_CANCELLED)

#include <kernel.h>

Wait on the polled object was cancelled, e.g.

by k_queue_cancel_wait().

K_POLL_STATE_DATA_AVAILABLE

#define K_POLL_STATE_DATA_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_DATA_AVAILABLE)

#include <kernel.h>

Data became available in a queue.

K_POLL_STATE_FIFO_DATA_AVAILABLE

#define K_POLL_STATE_FIFO_DATA_AVAILABLE   K_POLL_STATE_DATA_AVAILABLE

#include <kernel.h>

Data became available in a FIFO.

K_POLL_STATE_LIFO_DATA_AVAILABLE

#define K_POLL_STATE_LIFO_DATA_AVAILABLE   K_POLL_STATE_DATA_AVAILABLE

#include <kernel.h>

Data became available in a LIFO.

K_POLL_STATE_MSGQ_DATA_AVAILABLE

#define K_POLL_STATE_MSGQ_DATA_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_MSGQ_DATA_AVAILABLE)

#include <kernel.h>

Data became available in a message queue.

K_POLL_STATE_NOT_READY

#define K_POLL_STATE_NOT_READY   0

#include <kernel.h>

Condition being polled for has not occurred yet.

K_POLL_STATE_PIPE_DATA_AVAILABLE

#define K_POLL_STATE_PIPE_DATA_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_PIPE_DATA_AVAILABLE)

#include <kernel.h>

Data became available in a pipe.

K_POLL_STATE_SEM_AVAILABLE

#define K_POLL_STATE_SEM_AVAILABLE   Z_POLL_STATE_BIT(_POLL_STATE_SEM_AVAILABLE)

#include <kernel.h>

Semaphore became available.

K_POLL_STATE_SIGNALED

#define K_POLL_STATE_SIGNALED   Z_POLL_STATE_BIT(_POLL_STATE_SIGNALED)

#include <kernel.h>

Poll signal was raised.

K_POLL_TYPE_DATA_AVAILABLE

#define K_POLL_TYPE_DATA_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_DATA_AVAILABLE)

#include <kernel.h>

Poll for data becoming available in a queue.

K_POLL_TYPE_FIFO_DATA_AVAILABLE

#define K_POLL_TYPE_FIFO_DATA_AVAILABLE   K_POLL_TYPE_DATA_AVAILABLE

#include <kernel.h>

Poll for data becoming available in a FIFO.

K_POLL_TYPE_IGNORE

#define K_POLL_TYPE_IGNORE   0

#include <kernel.h>

Event is ignored by k_poll().

K_POLL_TYPE_LIFO_DATA_AVAILABLE

#define K_POLL_TYPE_LIFO_DATA_AVAILABLE   K_POLL_TYPE_DATA_AVAILABLE

#include <kernel.h>

Poll for data becoming available in a LIFO.

K_POLL_TYPE_MSGQ_DATA_AVAILABLE

#define K_POLL_TYPE_MSGQ_DATA_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_MSGQ_DATA_AVAILABLE)

#include <kernel.h>

Poll for data becoming available in a message queue.

K_POLL_TYPE_PIPE_DATA_AVAILABLE

#define K_POLL_TYPE_PIPE_DATA_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_PIPE_DATA_AVAILABLE)

#include <kernel.h>

Poll for data becoming available in a pipe.

K_POLL_TYPE_SEM_AVAILABLE

#define K_POLL_TYPE_SEM_AVAILABLE   Z_POLL_TYPE_BIT(_POLL_TYPE_SEM_AVAILABLE)

#include <kernel.h>

Poll for a semaphore becoming available.

K_POLL_TYPE_SIGNAL

#define K_POLL_TYPE_SIGNAL   Z_POLL_TYPE_BIT(_POLL_TYPE_SIGNAL)

#include <kernel.h>

Poll for a raised poll signal.

Enumeration Type Documentation

k_poll_modes

enum k_poll_modes

#include <kernel.h>

Modes of operation of a poll event.

Enumerator
K_POLL_MODE_NOTIFY_ONLY	Polling thread is notified of object availability, but does not take ownership of the object.
K_POLL_NUM_MODES	Number of poll modes.

Function Documentation

k_poll()

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

#include <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 <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 <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 <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 <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 when the polling thread's timeout is already expiring and the poll is therefore not notified directly. 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.

k_poll_signal_reset()

void k_poll_signal_reset

(

struct k_poll_signal *

sig

)

#include <kernel.h>

Reset a poll signal object's state to unsignaled.

Parameters

sig	A poll signal object