Zephyr API Documentation  2.7.0-rc2
A Scalable Open Source RTOS
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_delayablek_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)
static void work_handler(struct k_work *w)
Definition: main.c:42
static struct k_work work[2]
Definition: main.c:16
Definition: kernel.h:3844

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,

#define K_DELAYED_WORK_DEFINE(work, work_handler)
Initialize a statically-defined delayed work item.
Definition: kernel.h:4170
Parameters
workSymbol name for delayed work item object
work_handlerFunction 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,

#define K_WORK_DEFINE(work, work_handler)
Initialize a statically-defined work item.
Definition: kernel.h:4156
Parameters
workSymbol name for work item object
work_handlerFunction 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:
= Z_WORK_DELAYABLE_INITIALIZER(work_handler)
A structure used to submit work after a delay.
Definition: kernel.h:3651

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,

#define K_WORK_DELAYABLE_DEFINE(work, work_handler)
Initialize a statically-defined delayable work item.
Definition: kernel.h:3685
static struct k_work_delayable dwork
Definition: main.c:47

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
workSymbol name for delayable work item object
work_handlerFunction 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,

#define K_WORK_USER_DEFINE(work, work_handler)
Initialize a statically-defined user work item.
Definition: kernel.h:4013
Parameters
workSymbol name for work item object
work_handlerFunction 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
workthe 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
workAddress 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
workpointer 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
workpointer 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
dworkpointer 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
dworkpointer to the delayable work item.
syncpointer 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
trueif work was not idle (call had to wait for cancellation of a running handler to complete, or scheduled or submitted operations were cancelled);
falseotherwise

◆ 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
workpointer to the work item.
syncpointer 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
trueif work was pending (call had to wait for cancellation of a running handler to complete, or scheduled or submitted operations were cancelled);
falseotherwise

◆ 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
dworkpointer 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
dworkpointer 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
workAddress 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
dworkpointer 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
dworkpointer 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
workpointer to the work item.
syncpointer 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
trueif call had to wait for completion
falseif 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
dworkpointer to the delayable work item.
syncpointer 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
trueif call had to wait for completion
falseif 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
workthe work structure to be initialized.
handlerthe 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
dworkthe delayable work structure to be initialized.
handlerthe 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
workpointer 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
workAddress of delayed work item.
Return values
0Work item canceled.
-EINVALWork 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
workAddress of triggered work item.
handlerFunction 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
workAddress of delayed work item.
eventsAn array of events which trigger the work.
num_eventsThe number of events in the array.
timeoutTimeout after which the work will be scheduled for execution even if not triggered.
Return values
0Work item started watching for events.
-EINVALWork item is being processed or has completed its work.
-EADDRINUSEWork 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_qAddress of workqueue.
workAddress of delayed work item.
eventsAn array of events which trigger the work.
num_eventsThe number of events in the array.
timeoutTimeout after which the work will be scheduled for execution even if not triggered.
Return values
0Work item started watching for events.
-EINVALWork item is being processed or has completed its work.
-EADDRINUSEWork 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
queuepointer to the queue structure.
plugif true the work queue will continue to block new submissions after all items have drained.
Return values
1if call had to wait for the drain to complete
0if call did not have to wait
negativeif 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
queuethe 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
queuepointer to the queue structure. It must be initialized in zeroed/bss memory or with k_work_queue_init before use.
stackpointer to the work thread stack area.
stack_sizesize of the the work thread stack area, in bytes.
prioinitial thread priority
cfgoptional 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
queuepointer 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
queuepointer to the queue structure.
Return values
0if successfully unplugged
-EALREADYif 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
dworkpointer to the delayable work item.
delaythe 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
queuethe queue on which the work item should be submitted after the delay.
dworkpointer to the delayable work item.
delaythe 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
0if delay is K_NO_WAIT and work was already on a queue
1if
  • 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
2if delay is K_NO_WAIT and work was running and has been queued to the queue that was running it
-EBUSYif delay is K_NO_WAIT and k_work_submit_to_queue() fails with this code.
-EINVALif delay is K_NO_WAIT and k_work_submit_to_queue() fails with this code.
-ENODEVif 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
dworkpointer to the delayable work item.
delaythe 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
queuethe queue on which the work item should be submitted after the delay.
dworkpointer to the delayable work item.
delaythe 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
0if work was already scheduled or submitted.
1if work has been scheduled.
-EBUSYif delay is K_NO_WAIT and k_work_submit_to_queue() fails with this code.
-EINVALif delay is K_NO_WAIT and k_work_submit_to_queue() fails with this code.
-ENODEVif 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
workpointer 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
queuepointer 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
workpointer to the work item.
Return values
0if work was already submitted to a queue
1if work was not submitted and has been queued to queue
2if 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.
-EINVALif queue is null and the work item has never been run.
-ENODEVif 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
workAddress of work item.
handlerFunction 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
workAddress 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_qAddress of workqueue.
stackPointer to work queue thread's stack space, as defined by K_THREAD_STACK_DEFINE()
stack_sizeSize 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().
prioPriority of the work queue's thread.
nameoptional 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_qAddress of workqueue.
workAddress of work item.
Return values
-EBUSYif the work item was already in some workqueue
-ENOMEMif no memory for thread resource pool allocation
0Success