Work Queue APIs

Data Structures
struct	k_work
	A structure used to submit work. More...
struct	k_work_delayable
	A structure used to submit work after a delay. More...
struct	k_work_sync
	A structure holding internal state for a pending synchronous operation on a work item or queue. More...
struct	k_work_queue_config
	A structure holding optional configuration items for a work queue. More...
struct	k_work_q
	A structure used to hold work until it can be processed. More...
struct	k_delayed_work

Macros
#define	K_WORK_DELAYABLE_DEFINE(work, work_handler)
	Initialize a statically-defined delayable work item. More...
#define	K_WORK_USER_DEFINE(work, work_handler)    struct k_work_user work = Z_WORK_USER_INITIALIZER(work_handler)
	Initialize a statically-defined user work item. More...
#define	K_WORK_DEFINE(work, work_handler)    struct k_work work = Z_WORK_INITIALIZER(work_handler)
	Initialize a statically-defined work item. More...
#define	K_DELAYED_WORK_DEFINE(work, work_handler)
	Initialize a statically-defined delayed work item. More...

Typedefs
typedef void(*	k_work_handler_t) (struct k_work *work)
	The signature for a work item handler function. More...
typedef void(*	k_work_user_handler_t) (struct k_work_user *work)
	Work item handler function type for user work queues. More...

Enumerations
enum	{ K_WORK_RUNNING = BIT(K_WORK_RUNNING_BIT) , K_WORK_CANCELING = BIT(K_WORK_CANCELING_BIT) , K_WORK_QUEUED = BIT(K_WORK_QUEUED_BIT) , K_WORK_DELAYED = BIT(K_WORK_DELAYED_BIT) }

Functions
void	k_work_init (struct k_work *work, k_work_handler_t handler)
	Initialize a (non-delayable) work structure. More...
int	k_work_busy_get (const struct k_work *work)
	Busy state flags from the work item. More...
static bool	k_work_is_pending (const struct k_work *work)
	Test whether a work item is currently pending. More...
int	k_work_submit_to_queue (struct k_work_q *queue, struct k_work *work)
	Submit a work item to a queue. More...
int	k_work_submit (struct k_work *work)
	Submit a work item to the system queue. More...
bool	k_work_flush (struct k_work *work, struct k_work_sync *sync)
	Wait for last-submitted instance to complete. More...
int	k_work_cancel (struct k_work *work)
	Cancel a work item. More...
bool	k_work_cancel_sync (struct k_work *work, struct k_work_sync *sync)
	Cancel a work item and wait for it to complete. More...
void	k_work_queue_init (struct k_work_q *queue)
	Initialize a work queue structure. More...
void	k_work_queue_start (struct k_work_q *queue, k_thread_stack_t *stack, size_t stack_size, int prio, const struct k_work_queue_config *cfg)
	Initialize a work queue. More...
static k_tid_t	k_work_queue_thread_get (struct k_work_q *queue)
	Access the thread that animates a work queue. More...
int	k_work_queue_drain (struct k_work_q *queue, bool plug)
	Wait until the work queue has drained, optionally plugging it. More...
int	k_work_queue_unplug (struct k_work_q *queue)
	Release a work queue to accept new submissions. More...
void	k_work_init_delayable (struct k_work_delayable *dwork, k_work_handler_t handler)
	Initialize a delayable work structure. More...
static struct k_work_delayable *	k_work_delayable_from_work (struct k_work *work)
	Get the parent delayable work structure from a work pointer. More...
int	k_work_delayable_busy_get (const struct k_work_delayable *dwork)
	Busy state flags from the delayable work item. More...
static bool	k_work_delayable_is_pending (const struct k_work_delayable *dwork)
	Test whether a delayed work item is currently pending. More...
static k_ticks_t	k_work_delayable_expires_get (const struct k_work_delayable *dwork)
	Get the absolute tick count at which a scheduled delayable work will be submitted. More...
static k_ticks_t	k_work_delayable_remaining_get (const struct k_work_delayable *dwork)
	Get the number of ticks until a scheduled delayable work will be submitted. More...
int	k_work_schedule_for_queue (struct k_work_q *queue, struct k_work_delayable *dwork, k_timeout_t delay)
	Submit an idle work item to a queue after a delay. More...
int	k_work_schedule (struct k_work_delayable *dwork, k_timeout_t delay)
	Submit an idle work item to the system work queue after a delay. More...
int	k_work_reschedule_for_queue (struct k_work_q *queue, struct k_work_delayable *dwork, k_timeout_t delay)
	Reschedule a work item to a queue after a delay. More...
int	k_work_reschedule (struct k_work_delayable *dwork, k_timeout_t delay)
	Reschedule a work item to the system work queue after a delay. More...
bool	k_work_flush_delayable (struct k_work_delayable *dwork, struct k_work_sync *sync)
	Flush delayable work. More...
int	k_work_cancel_delayable (struct k_work_delayable *dwork)
	Cancel delayable work. More...
bool	k_work_cancel_delayable_sync (struct k_work_delayable *dwork, struct k_work_sync *sync)
	Cancel delayable work and wait. More...
static bool	k_work_pending (const struct k_work *work)
static void	k_work_q_start (struct k_work_q *work_q, k_thread_stack_t *stack, size_t stack_size, int prio)
static void	k_delayed_work_init (struct k_delayed_work *work, k_work_handler_t handler)
static int	k_delayed_work_submit_to_queue (struct k_work_q *work_q, struct k_delayed_work *work, k_timeout_t delay)
static int	k_delayed_work_submit (struct k_delayed_work *work, k_timeout_t delay)
static int	k_delayed_work_cancel (struct k_delayed_work *work)
static bool	k_delayed_work_pending (struct k_delayed_work *work)
static int32_t	k_delayed_work_remaining_get (struct k_delayed_work *work)
static k_ticks_t	k_delayed_work_expires_ticks (struct k_delayed_work *work)
static k_ticks_t	k_delayed_work_remaining_ticks (struct k_delayed_work *work)
static void	k_work_user_init (struct k_work_user *work, k_work_user_handler_t handler)
	Initialize a userspace work item. More...
static bool	k_work_user_is_pending (struct k_work_user *work)
	Check if a userspace work item is pending. More...
static int	k_work_user_submit_to_queue (struct k_work_user_q *work_q, struct k_work_user *work)
	Submit a work item to a user mode workqueue. More...
void	k_work_user_queue_start (struct k_work_user_q *work_q, k_thread_stack_t *stack, size_t stack_size, int prio, const char *name)
	Start a workqueue in user mode. More...
void	k_work_poll_init (struct k_work_poll *work, k_work_handler_t handler)
	Initialize a triggered work item. More...
int	k_work_poll_submit_to_queue (struct k_work_q *work_q, struct k_work_poll *work, struct k_poll_event *events, int num_events, k_timeout_t timeout)
	Submit a triggered work item. More...
int	k_work_poll_submit (struct k_work_poll *work, struct k_poll_event *events, int num_events, k_timeout_t timeout)
	Submit a triggered work item to the system workqueue. More...
int	k_work_poll_cancel (struct k_work_poll *work)
	Cancel a triggered work item. More...

Detailed Description

Macro Definition Documentation

K_DELAYED_WORK_DEFINE

#define K_DELAYED_WORK_DEFINE	(		work,
			work_handler
	)

#include <include/kernel.h>

Value:

        __DEPRECATED_MACRO \
        struct k_delayed_work work = Z_DELAYED_WORK_INITIALIZER(work_handler)

Initialize a statically-defined delayed work item.

This macro can be used to initialize a statically-defined workqueue delayed work item, prior to its first use. For example,

static K_DELAYED_WORK_DEFINE(<work>, <work_handler>); 

Parameters

work	Symbol name for delayed work item object
work_handler	Function to invoke each time work item is processed.

K_WORK_DEFINE

#define K_WORK_DEFINE	(		work,
			work_handler
	)		struct k_work work = Z_WORK_INITIALIZER(work_handler)

#include <include/kernel.h>

Initialize a statically-defined work item.

This macro can be used to initialize a statically-defined workqueue work item, prior to its first use. For example,

static K_WORK_DEFINE(<work>, <work_handler>); 

Parameters

work	Symbol name for work item object
work_handler	Function to invoke each time work item is processed.

K_WORK_DELAYABLE_DEFINE

#define K_WORK_DELAYABLE_DEFINE	(		work,
			work_handler
	)

#include <include/kernel.h>

Value:

        struct k_work_delayable work \
          = Z_WORK_DELAYABLE_INITIALIZER(work_handler)

Initialize a statically-defined delayable work item.

This macro can be used to initialize a statically-defined delayable work item, prior to its first use. For example,

static K_WORK_DELAYABLE_DEFINE(<dwork>, <work_handler>); 

Note that if the runtime dependencies support initialization with k_work_init_delayable() using that will eliminate the initialized object in ROM that is produced by this macro and copied in at system startup.

Parameters

work	Symbol name for delayable work item object
work_handler	Function to invoke each time work item is processed.

K_WORK_USER_DEFINE

#define K_WORK_USER_DEFINE	(		work,
			work_handler
	)		struct k_work_user work = Z_WORK_USER_INITIALIZER(work_handler)

#include <include/kernel.h>

Initialize a statically-defined user work item.

This macro can be used to initialize a statically-defined user work item, prior to its first use. For example,

static K_WORK_USER_DEFINE(<work>, <work_handler>); 

Parameters

work	Symbol name for work item object
work_handler	Function to invoke each time work item is processed.

Typedef Documentation

k_work_handler_t

typedef void(* k_work_handler_t) (struct k_work *work)

#include <include/kernel.h>

The signature for a work item handler function.

The function will be invoked by the thread animating a work queue.

Parameters

work	the work item that provided the handler.

k_work_user_handler_t

k_work_user_handler_t

#include <include/kernel.h>

Work item handler function type for user work queues.

A work item's handler function is executed by a user workqueue's thread when the work item is processed by the workqueue.

Parameters

work	Address of the work item.

Returns

N/A

Enumeration Type Documentation

anonymous enum

anonymous enum

#include <include/kernel.h>

Enumerator
K_WORK_RUNNING	Flag indicating a work item that is running under a work queue thread. Accessed via k_work_busy_get(). May co-occur with other flags.
K_WORK_CANCELING	Flag indicating a work item that is being canceled. Accessed via k_work_busy_get(). May co-occur with other flags.
K_WORK_QUEUED	Flag indicating a work item that has been submitted to a queue but has not started running. Accessed via k_work_busy_get(). May co-occur with other flags.
K_WORK_DELAYED	Flag indicating a delayed work item that is scheduled for submission to a queue. Accessed via k_work_busy_get(). May co-occur with other flags.

Function Documentation

k_delayed_work_cancel()

static int k_delayed_work_cancel ( struct k_delayed_work *  work )

inlinestatic

#include <include/kernel.h>

k_delayed_work_expires_ticks()

static k_ticks_t k_delayed_work_expires_ticks ( struct k_delayed_work *  work )

inlinestatic

#include <include/kernel.h>

k_delayed_work_init()

static void k_delayed_work_init ( struct k_delayed_work *  work, k_work_handler_t  handler  )

inlinestatic

#include <include/kernel.h>

k_delayed_work_pending()

static bool k_delayed_work_pending ( struct k_delayed_work *  work )

inlinestatic

#include <include/kernel.h>

k_delayed_work_remaining_get()

static int32_t k_delayed_work_remaining_get ( struct k_delayed_work *  work )

inlinestatic

#include <include/kernel.h>

k_delayed_work_remaining_ticks()

static k_ticks_t k_delayed_work_remaining_ticks ( struct k_delayed_work *  work )

inlinestatic

#include <include/kernel.h>

k_delayed_work_submit()

static int k_delayed_work_submit ( struct k_delayed_work *  work, k_timeout_t  delay  )

inlinestatic

#include <include/kernel.h>

k_delayed_work_submit_to_queue()

static int k_delayed_work_submit_to_queue ( struct k_work_q *  work_q, struct k_delayed_work *  work, k_timeout_t  delay  )

inlinestatic

#include <include/kernel.h>

k_work_busy_get()

int k_work_busy_get

(

const struct k_work *

work

)

#include <include/kernel.h>

Busy state flags from the work item.

A zero return value indicates the work item appears to be idle.

Note

This is a live snapshot of state, which may change before the result is checked. Use locks where appropriate.

Function properties (list may not be complete)

isr-ok

Parameters

work	pointer to the work item.

Returns

a mask of flags K_WORK_DELAYED, K_WORK_QUEUED, K_WORK_RUNNING, and K_WORK_CANCELING.

k_work_cancel()

int k_work_cancel

(

struct k_work *

work

)

#include <include/kernel.h>

Cancel a work item.

This attempts to prevent a pending (non-delayable) work item from being processed by removing it from the work queue. If the item is being processed, the work item will continue to be processed, but resubmissions are rejected until cancellation completes.

If this returns zero cancellation is complete, otherwise something (probably a work queue thread) is still referencing the item.

See also k_work_cancel_sync().

Function properties (list may not be complete)

isr-ok

Parameters

work	pointer to the work item.

Returns

the k_work_busy_get() status indicating the state of the item after all cancellation steps performed by this call are completed.

k_work_cancel_delayable()

int k_work_cancel_delayable

(

struct k_work_delayable *

dwork

)

#include <include/kernel.h>

Cancel delayable work.

Similar to k_work_cancel() but for delayable work. If the work is scheduled or submitted it is canceled. This function does not wait for the cancellation to complete.

Note

The work may still be running when this returns. Use k_work_flush_delayable() or k_work_cancel_delayable_sync() to ensure it is not running.

Canceling delayable work does not prevent rescheduling it. It does prevent submitting it until the cancellation completes.

Function properties (list may not be complete)

isr-ok

Parameters

dwork

pointer to the delayable work item.

Returns

the k_work_delayable_busy_get() status indicating the state of the item after all cancellation steps performed by this call are completed.

k_work_cancel_delayable_sync()

bool k_work_cancel_delayable_sync	(	struct k_work_delayable *	dwork,
		struct k_work_sync *	sync
	)

#include <include/kernel.h>

Cancel delayable work and wait.

Like k_work_cancel_delayable() but waits until the work becomes idle.

Note

Canceling delayable work does not prevent rescheduling it. It does prevent submitting it until the cancellation completes.

Be careful of caller and work queue thread relative priority. If this function sleeps it will not return until the work queue thread completes the tasks that allow this thread to resume.

Behavior is undefined if this function is invoked on dwork from a work queue running dwork.

Parameters

dwork	pointer to the delayable work item.
sync	pointer to an opaque item containing state related to the pending cancellation. The object must persist until the call returns, and be accessible from both the caller thread and the work queue thread. The object must not be used for any other flush or cancel operation until this one completes. On architectures with CONFIG_KERNEL_COHERENCE the object must be allocated in coherent memory.

Return values

true	if work was not idle (call had to wait for cancellation of a running handler to complete, or scheduled or submitted operations were cancelled);
false	otherwise

k_work_cancel_sync()

bool k_work_cancel_sync	(	struct k_work *	work,
		struct k_work_sync *	sync
	)

#include <include/kernel.h>

Cancel a work item and wait for it to complete.

Same as k_work_cancel() but does not return until cancellation is complete. This can be invoked by a thread after k_work_cancel() to synchronize with a previous cancellation.

On return the work structure will be idle unless something submits it after the cancellation was complete.

Note

Be careful of caller and work queue thread relative priority. If this function sleeps it will not return until the work queue thread completes the tasks that allow this thread to resume.

Behavior is undefined if this function is invoked on work from a work queue running work.

Parameters

work	pointer to the work item.
sync	pointer to an opaque item containing state related to the pending cancellation. The object must persist until the call returns, and be accessible from both the caller thread and the work queue thread. The object must not be used for any other flush or cancel operation until this one completes. On architectures with CONFIG_KERNEL_COHERENCE the object must be allocated in coherent memory.

Return values

true	if work was pending (call had to wait for cancellation of a running handler to complete, or scheduled or submitted operations were cancelled);
false	otherwise

k_work_delayable_busy_get()

int k_work_delayable_busy_get

(

const struct k_work_delayable *

dwork

)

#include <include/kernel.h>

Busy state flags from the delayable work item.

Function properties (list may not be complete)

isr-ok

Note

This is a live snapshot of state, which may change before the result can be inspected. Use locks where appropriate.

Parameters

dwork

pointer to the delayable work item.

Returns

a mask of flags K_WORK_DELAYED, K_WORK_QUEUED, K_WORK_RUNNING, and K_WORK_CANCELING. A zero return value indicates the work item appears to be idle.

k_work_delayable_expires_get()

static k_ticks_t k_work_delayable_expires_get ( const struct k_work_delayable *  dwork )

inlinestatic

#include <include/kernel.h>

Get the absolute tick count at which a scheduled delayable work will be submitted.

Note

This is a live snapshot of state, which may change before the result can be inspected. Use locks where appropriate.

Function properties (list may not be complete)

isr-ok

Parameters

dwork

pointer to the delayable work item.

Returns

the tick count when the timer that will schedule the work item will expire, or the current tick count if the work is not scheduled.

k_work_delayable_from_work()

static struct k_work_delayable * k_work_delayable_from_work ( struct k_work *  work )

inlinestatic

#include <include/kernel.h>

Get the parent delayable work structure from a work pointer.

This function is necessary when a k_work_handler_t function is passed to k_work_schedule_for_queue() and the handler needs to access data from the container of the containing k_work_delayable.

Parameters

work	Address passed to the work handler

Returns

Address of the containing k_work_delayable structure.

k_work_delayable_is_pending()

static bool k_work_delayable_is_pending ( const struct k_work_delayable *  dwork )

inlinestatic

#include <include/kernel.h>

Test whether a delayed work item is currently pending.

Wrapper to determine whether a delayed work item is in a non-idle state.

Note

This is a live snapshot of state, which may change before the result can be inspected. Use locks where appropriate.

Function properties (list may not be complete)

isr-ok

Parameters

dwork

pointer to the delayable work item.

Returns

true if and only if k_work_delayable_busy_get() returns a non-zero value.

k_work_delayable_remaining_get()

static k_ticks_t k_work_delayable_remaining_get ( const struct k_work_delayable *  dwork )

inlinestatic

#include <include/kernel.h>

Get the number of ticks until a scheduled delayable work will be submitted.

Note

This is a live snapshot of state, which may change before the result can be inspected. Use locks where appropriate.

Function properties (list may not be complete)

isr-ok

Parameters

dwork

pointer to the delayable work item.

Returns

the number of ticks until the timer that will schedule the work item will expire, or zero if the item is not scheduled.

k_work_flush()

bool k_work_flush	(	struct k_work *	work,
		struct k_work_sync *	sync
	)

#include <include/kernel.h>

Wait for last-submitted instance to complete.

Resubmissions may occur while waiting, including chained submissions (from within the handler).

Note

Be careful of caller and work queue thread relative priority. If this function sleeps it will not return until the work queue thread completes the tasks that allow this thread to resume.

Behavior is undefined if this function is invoked on work from a work queue running work.

Parameters

work	pointer to the work item.
sync	pointer to an opaque item containing state related to the pending cancellation. The object must persist until the call returns, and be accessible from both the caller thread and the work queue thread. The object must not be used for any other flush or cancel operation until this one completes. On architectures with CONFIG_KERNEL_COHERENCE the object must be allocated in coherent memory.

Return values

true	if call had to wait for completion
false	if work was already idle

k_work_flush_delayable()

bool k_work_flush_delayable	(	struct k_work_delayable *	dwork,
		struct k_work_sync *	sync
	)

#include <include/kernel.h>

Flush delayable work.

If the work is scheduled, it is immediately submitted. Then the caller blocks until the work completes, as with k_work_flush().

Note

Be careful of caller and work queue thread relative priority. If this function sleeps it will not return until the work queue thread completes the tasks that allow this thread to resume.

Behavior is undefined if this function is invoked on dwork from a work queue running dwork.

Parameters

dwork	pointer to the delayable work item.
sync	pointer to an opaque item containing state related to the pending cancellation. The object must persist until the call returns, and be accessible from both the caller thread and the work queue thread. The object must not be used for any other flush or cancel operation until this one completes. On architectures with CONFIG_KERNEL_COHERENCE the object must be allocated in coherent memory.

Return values

true	if call had to wait for completion
false	if work was already idle

k_work_init()

void k_work_init	(	struct k_work *	work,
		k_work_handler_t	handler
	)

#include <include/kernel.h>

Initialize a (non-delayable) work structure.

This must be invoked before submitting a work structure for the first time. It need not be invoked again on the same work structure. It can be re-invoked to change the associated handler, but this must be done when the work item is idle.

Function properties (list may not be complete)

isr-ok

Parameters

work	the work structure to be initialized.
handler	the handler to be invoked by the work item.

k_work_init_delayable()

void k_work_init_delayable	(	struct k_work_delayable *	dwork,
		k_work_handler_t	handler
	)

#include <include/kernel.h>

Initialize a delayable work structure.

This must be invoked before scheduling a delayable work structure for the first time. It need not be invoked again on the same work structure. It can be re-invoked to change the associated handler, but this must be done when the work item is idle.

Function properties (list may not be complete)

isr-ok

Parameters

dwork	the delayable work structure to be initialized.
handler	the handler to be invoked by the work item.

k_work_is_pending()

static bool k_work_is_pending ( const struct k_work *  work )

inlinestatic

#include <include/kernel.h>

Test whether a work item is currently pending.

Wrapper to determine whether a work item is in a non-idle dstate.

Note

This is a live snapshot of state, which may change before the result is checked. Use locks where appropriate.

Function properties (list may not be complete)

isr-ok

Parameters

work	pointer to the work item.

Returns

true if and only if k_work_busy_get() returns a non-zero value.

k_work_pending()

static bool k_work_pending ( const struct k_work *  work )

inlinestatic

#include <include/kernel.h>

k_work_poll_cancel()

int k_work_poll_cancel

(

struct k_work_poll *

work

)

#include <include/kernel.h>

Cancel a triggered work item.

This routine cancels the submission of triggered work item work. A triggered work item can only be canceled if no event triggered work submission.

Function properties (list may not be complete)

isr-ok

Parameters

work	Address of delayed work item.

Return values

0	Work item canceled.
-EINVAL	Work item is being processed or has completed its work.

k_work_poll_init()

void k_work_poll_init	(	struct k_work_poll *	work,
		k_work_handler_t	handler
	)

#include <include/kernel.h>

Initialize a triggered work item.

This routine initializes a workqueue triggered work item, prior to its first use.

Parameters

work	Address of triggered work item.
handler	Function to invoke each time work item is processed.

Returns

N/A

k_work_poll_submit()

int k_work_poll_submit	(	struct k_work_poll *	work,
		struct k_poll_event *	events,
		int	num_events,
		k_timeout_t	timeout
	)

#include <include/kernel.h>

Submit a triggered work item to the system workqueue.

This routine schedules work item work to be processed by system workqueue when one of the given events is signaled. The routine initiates internal poller for the work item and then returns to the caller. Only when one of the watched events happen the work item is actually submitted to the workqueue and becomes pending.

Submitting a previously submitted triggered work item that is still waiting for the event cancels the existing submission and reschedules it the using the new event list. Note that this behavior is inherently subject to race conditions with the pre-existing triggered work item and work queue, so care must be taken to synchronize such resubmissions externally.

Function properties (list may not be complete)

isr-ok

Warning

Provided array of events as well as a triggered work item must not be modified until the item has been processed by the workqueue.

Parameters

work	Address of delayed work item.
events	An array of events which trigger the work.
num_events	The number of events in the array.
timeout	Timeout after which the work will be scheduled for execution even if not triggered.

Return values

0	Work item started watching for events.
-EINVAL	Work item is being processed or has completed its work.
-EADDRINUSE	Work item is pending on a different workqueue.

k_work_poll_submit_to_queue()

int k_work_poll_submit_to_queue	(	struct k_work_q *	work_q,
		struct k_work_poll *	work,
		struct k_poll_event *	events,
		int	num_events,
		k_timeout_t	timeout
	)

#include <include/kernel.h>

Submit a triggered work item.

This routine schedules work item work to be processed by workqueue work_q when one of the given events is signaled. The routine initiates internal poller for the work item and then returns to the caller. Only when one of the watched events happen the work item is actually submitted to the workqueue and becomes pending.

Submitting a previously submitted triggered work item that is still waiting for the event cancels the existing submission and reschedules it the using the new event list. Note that this behavior is inherently subject to race conditions with the pre-existing triggered work item and work queue, so care must be taken to synchronize such resubmissions externally.

Function properties (list may not be complete)

isr-ok

Warning

Provided array of events as well as a triggered work item must be placed in persistent memory (valid until work handler execution or work cancellation) and cannot be modified after submission.

Parameters

work_q	Address of workqueue.
work	Address of delayed work item.
events	An array of events which trigger the work.
num_events	The number of events in the array.
timeout	Timeout after which the work will be scheduled for execution even if not triggered.

Return values

0	Work item started watching for events.
-EINVAL	Work item is being processed or has completed its work.
-EADDRINUSE	Work item is pending on a different workqueue.

k_work_q_start()

static void k_work_q_start ( struct k_work_q *  work_q, k_thread_stack_t *  stack, size_t  stack_size, int  prio  )

inlinestatic

#include <include/kernel.h>

k_work_queue_drain()

int k_work_queue_drain	(	struct k_work_q *	queue,
		bool	plug
	)

#include <include/kernel.h>

Wait until the work queue has drained, optionally plugging it.

This blocks submission to the work queue except when coming from queue thread, and blocks the caller until no more work items are available in the queue.

If plug is true then submission will continue to be blocked after the drain operation completes until k_work_queue_unplug() is invoked.

Note that work items that are delayed are not yet associated with their work queue. They must be cancelled externally if a goal is to ensure the work queue remains empty. The plug feature can be used to prevent delayed items from being submitted after the drain completes.

Parameters

queue	pointer to the queue structure.
plug	if true the work queue will continue to block new submissions after all items have drained.

Return values

1	if call had to wait for the drain to complete
0	if call did not have to wait
negative	if wait was interrupted or failed

k_work_queue_init()

void k_work_queue_init

(

struct k_work_q *

queue

)

#include <include/kernel.h>

Initialize a work queue structure.

This must be invoked before starting a work queue structure for the first time. It need not be invoked again on the same work queue structure.

Function properties (list may not be complete)

isr-ok

Parameters

queue

the queue structure to be initialized.

k_work_queue_start()

void k_work_queue_start	(	struct k_work_q *	queue,
		k_thread_stack_t *	stack,
		size_t	stack_size,
		int	prio,
		const struct k_work_queue_config *	cfg
	)

#include <include/kernel.h>

Initialize a work queue.

This configures the work queue thread and starts it running. The function should not be re-invoked on a queue.

Parameters

queue	pointer to the queue structure. It must be initialized in zeroed/bss memory or with k_work_queue_init before use.
stack	pointer to the work thread stack area.
stack_size	size of the the work thread stack area, in bytes.
prio	initial thread priority
cfg	optional additional configuration parameters. Pass NULL if not required, to use the defaults documented in k_work_queue_config.

k_work_queue_thread_get()

static k_tid_t k_work_queue_thread_get ( struct k_work_q *  queue )

inlinestatic

#include <include/kernel.h>

Access the thread that animates a work queue.

This is necessary to grant a work queue thread access to things the work items it will process are expected to use.

Parameters

queue

pointer to the queue structure.

Returns

the thread associated with the work queue.

k_work_queue_unplug()

int k_work_queue_unplug

(

struct k_work_q *

queue

)

#include <include/kernel.h>

Release a work queue to accept new submissions.

This releases the block on new submissions placed when k_work_queue_drain() is invoked with the plug option enabled. If this is invoked before the drain completes new items may be submitted as soon as the drain completes.

Function properties (list may not be complete)

isr-ok

Parameters

queue

pointer to the queue structure.

Return values

0	if successfully unplugged
-EALREADY	if the work queue was not plugged.

k_work_reschedule()

int k_work_reschedule	(	struct k_work_delayable *	dwork,
		k_timeout_t	delay
	)

#include <include/kernel.h>

Reschedule a work item to the system work queue after a delay.

This is a thin wrapper around k_work_reschedule_for_queue(), with all the API characteristcs of that function.

Parameters

dwork	pointer to the delayable work item.
delay	the time to wait before submitting the work item.

Returns

as with k_work_reschedule_for_queue().

k_work_reschedule_for_queue()

int k_work_reschedule_for_queue	(	struct k_work_q *	queue,
		struct k_work_delayable *	dwork,
		k_timeout_t	delay
	)

#include <include/kernel.h>

Reschedule a work item to a queue after a delay.

Unlike k_work_schedule_for_queue() this function can change the deadline of a scheduled work item, and will schedule a work item that isn't idle (e.g. is submitted or running). This function does not affect ("unsubmit") a work item that has been submitted to a queue.

Function properties (list may not be complete)

isr-ok

Parameters

queue	the queue on which the work item should be submitted after the delay.
dwork	pointer to the delayable work item.
delay	the time to wait before submitting the work item. If K_NO_WAIT this is equivalent to k_work_submit_to_queue() after canceling any previous scheduled submission.

Note

If delay is K_NO_WAIT ("no delay") the return values are as with k_work_submit_to_queue().

Return values

0	if delay is K_NO_WAIT and work was already on a queue
1	if delay is K_NO_WAIT and work was not submitted but has now been queued to queue; or delay not K_NO_WAIT and work has been scheduled
2	if delay is K_NO_WAIT and work was running and has been queued to the queue that was running it
-EBUSY	if delay is K_NO_WAIT and k_work_submit_to_queue() fails with this code.
-EINVAL	if delay is K_NO_WAIT and k_work_submit_to_queue() fails with this code.
-ENODEV	if delay is K_NO_WAIT and k_work_submit_to_queue() fails with this code.

k_work_schedule()

int k_work_schedule	(	struct k_work_delayable *	dwork,
		k_timeout_t	delay
	)

#include <include/kernel.h>

Submit an idle work item to the system work queue after a delay.

This is a thin wrapper around k_work_schedule_for_queue(), with all the API characteristcs of that function.

Parameters

dwork	pointer to the delayable work item.
delay	the time to wait before submitting the work item. If K_NO_WAIT this is equivalent to k_work_submit_to_queue().

Returns

as with k_work_schedule_for_queue().

k_work_schedule_for_queue()

int k_work_schedule_for_queue	(	struct k_work_q *	queue,
		struct k_work_delayable *	dwork,
		k_timeout_t	delay
	)

#include <include/kernel.h>

Submit an idle work item to a queue after a delay.

Unlike k_work_reschedule_for_queue() this is a no-op if the work item is already scheduled or submitted, even if delay is K_NO_WAIT.

Function properties (list may not be complete)

isr-ok

Parameters

queue	the queue on which the work item should be submitted after the delay.
dwork	pointer to the delayable work item.
delay	the time to wait before submitting the work item. If K_NO_WAIT and the work is not pending this is equivalent to k_work_submit_to_queue().

Return values

0	if work was already scheduled or submitted.
1	if work has been scheduled.
-EBUSY	if delay is K_NO_WAIT and k_work_submit_to_queue() fails with this code.
-EINVAL	if delay is K_NO_WAIT and k_work_submit_to_queue() fails with this code.
-ENODEV	if delay is K_NO_WAIT and k_work_submit_to_queue() fails with this code.

k_work_submit()

int k_work_submit

(

struct k_work *

work

)

#include <include/kernel.h>

Submit a work item to the system queue.

Function properties (list may not be complete)

isr-ok

Parameters

work	pointer to the work item.

Returns

as with k_work_submit_to_queue().

k_work_submit_to_queue()

int k_work_submit_to_queue	(	struct k_work_q *	queue,
		struct k_work *	work
	)

#include <include/kernel.h>

Submit a work item to a queue.

Parameters

queue

pointer to the work queue on which the item should run. If NULL the queue from the most recent submission will be used.

Function properties (list may not be complete)

isr-ok

Parameters

work	pointer to the work item.

Return values

0	if work was already submitted to a queue
1	if work was not submitted and has been queued to queue
2	if work was running and has been queued to the queue that was running it
-EBUSY	if work submission was rejected because the work item is cancelling; or queue is draining; or queue is plugged.
-EINVAL	if queue is null and the work item has never been run.
-ENODEV	if queue has not been started.

k_work_user_init()

static void k_work_user_init ( struct k_work_user *  work, k_work_user_handler_t  handler  )

inlinestatic

#include <include/kernel.h>

Initialize a userspace work item.

This routine initializes a user workqueue work item, prior to its first use.

Parameters

work	Address of work item.
handler	Function to invoke each time work item is processed.

Returns

N/A

k_work_user_is_pending()

static bool k_work_user_is_pending ( struct k_work_user *  work )

inlinestatic

#include <include/kernel.h>

Check if a userspace work item is pending.

This routine indicates if user work item work is pending in a workqueue's queue.

Note

Checking if the work is pending gives no guarantee that the work will still be pending when this information is used. It is up to the caller to make sure that this information is used in a safe manner.

Function properties (list may not be complete)

isr-ok

Parameters

work	Address of work item.

Returns

true if work item is pending, or false if it is not pending.

k_work_user_queue_start()

void k_work_user_queue_start	(	struct k_work_user_q *	work_q,
		k_thread_stack_t *	stack,
		size_t	stack_size,
		int	prio,
		const char *	name
	)

#include <include/kernel.h>

Start a workqueue in user mode.

This works identically to k_work_queue_start() except it is callable from user mode, and the worker thread created will run in user mode. The caller must have permissions granted on both the work_q parameter's thread and queue objects, and the same restrictions on priority apply as k_thread_create().

Parameters

work_q	Address of workqueue.
stack	Pointer to work queue thread's stack space, as defined by K_THREAD_STACK_DEFINE()
stack_size	Size of the work queue thread's stack (in bytes), which should either be the same constant passed to K_THREAD_STACK_DEFINE() or the value of K_THREAD_STACK_SIZEOF().
prio	Priority of the work queue's thread.
name	optional thread name. If not null a copy is made into the thread's name buffer.

Returns

N/A

k_work_user_submit_to_queue()

static int k_work_user_submit_to_queue ( struct k_work_user_q *  work_q, struct k_work_user *  work  )

inlinestatic

#include <include/kernel.h>

Submit a work item to a user mode workqueue.

Submits a work item to a workqueue that runs in user mode. A temporary memory allocation is made from the caller's resource pool which is freed once the worker thread consumes the k_work item. The workqueue thread must have memory access to the k_work item being submitted. The caller must have permission granted on the work_q parameter's queue object.

Function properties (list may not be complete)

isr-ok

Parameters

work_q	Address of workqueue.
work	Address of work item.

Return values

-EBUSY	if the work item was already in some workqueue
-ENOMEM	if no memory for thread resource pool allocation
0	Success