Lines Matching full:a
10 A :dfn:`workqueue` is a kernel object that uses a dedicated thread to process
11 work items in a first in, first out manner. Each work item is processed by
12 calling the function specified by the work item. A workqueue is typically
13 used by an ISR or a high-priority thread to offload non-urgent processing
14 to a lower-priority thread so it does not impact time-sensitive processing.
19 A workqueue has the following key properties:
21 * A **queue** of work items that have been added, but not yet processed.
23 * A **thread** that processes the work items in the queue. The priority of the
28 between each submitted work item, to prevent a cooperative workqueue from
31 A workqueue must be initialized before it can be used. This sets its queue to
46 * The ability to wait until a work item has completed or a queue has been
48 * Finer control of behavior when scheduling a delayable work item,
49 specifically allowing a previous deadline to remain unchanged when a work
66 A work item is assigned a **handler function**, which is the function
68 function accepts a single argument, which is the address of the work item
71 A work item must be initialized before it can be used. This records the work
74 A work item may be **queued** (:c:enumerator:`K_WORK_QUEUED`) by submitting it to a
75 workqueue by an ISR or a thread. Submitting a work item appends the work item
80 other items in the queue, a queued work item may be processed quickly or it
83 A delayable work item may be **scheduled** (:c:enumerator:`K_WORK_DELAYED`) to a
86 A work item will be **running** (:c:enumerator:`K_WORK_RUNNING`) when it is running
87 on a work queue, and may also be **canceling** (:c:enumerator:`K_WORK_CANCELING`)
88 if it started running before a thread has requested that it be cancelled.
90 A work item can be in multiple states; for example it can be:
92 * running on a queue;
93 * marked canceling (because a thread used :c:func:`k_work_cancel_sync()` to
96 * scheduled to be submitted to a (possibly different) queue
98 *all simultaneously*. A work item that is in any of these states is **pending**
101 A handler function can use any kernel API available to threads. However,
102 operations that are potentially blocking (e.g. taking a semaphore) must be
106 The single argument that is passed to a handler function can be ignored if it
108 the work it is to perform, the work item can be embedded in a larger data
113 A work item is typically initialized once and then submitted to a specific
114 workqueue whenever work needs to be performed. If an ISR or a thread attempts
115 to submit a work item that is already queued the work item is not affected;
119 A handler function is permitted to re-submit its work item argument
125 A pending work item *must not* be altered until the item has been processed
126 by the workqueue thread. This means a work item must not be re-initialized
136 An ISR or a thread may need to schedule a work item that is to be processed
137 only after a specified period of time, rather than immediately. This can be
138 done by **scheduling** a **delayable work item** to be submitted to a
139 workqueue at a future time.
141 A delayable work item contains a standard work item but adds fields that
144 A delayable work item is initialized and scheduled to a workqueue in a similar
145 manner to a standard work item, although different kernel APIs are used. When
146 the schedule request is made the kernel initiates a timeout mechanism that is
151 Note that work handler used for delayable still receives a pointer to the
169 The :c:func:`k_work_poll_submit` interface schedules a triggered work
170 item in response to a **poll event** (see :ref:`polling_v2`), that will
171 call a user-defined function when a monitored resource becomes available
172 or poll signal is raised, or a timeout occurs.
174 a dedicated thread waiting or actively polling for a poll event.
176 A triggered work item is a standard work item that has the following
179 * A pointer to an array of poll events that will trigger work item
182 * A size of the array containing poll events.
184 A triggered work item is initialized and submitted to a workqueue in a similar
185 manner to a standard work item, although dedicated kernel APIs are used.
186 When a submit request is made, the kernel begins observing kernel objects
193 have to be valid and cannot be modified for a complete triggered work
196 An ISR or a thread may **cancel** a triggered work item it has submitted
197 as long as it is still waiting for a poll event. In such case, the kernel
204 The kernel defines a workqueue known as the *system workqueue*, which is
212 incurs a significant cost in memory footprint. A new workqueue can be
221 Defining and Controlling a Workqueue
224 A workqueue is defined using a variable of type :c:struct:`k_work_q`.
232 The following code defines and initializes a workqueue:
253 The following API can be used to interact with a workqueue:
257 thread are accepted while a queue is draining, but work items from any other
261 Note that draining a queue has no effect on scheduling or processing
265 the queue due to a previous drain operation.
267 Submitting a Work Item
270 A work item is defined using a variable of type :c:struct:`k_work`. It must
276 calling :c:func:`k_work_submit`, or to a specified workqueue by
307 /* initialize name info for a device */
320 * :c:func:`k_work_busy_get()` returns a snapshot of flags indicating work item
321 state. A zero value indicates the work is not scheduled, submitted, being
324 * :c:func:`k_work_is_pending()` is a helper that indicates ``true`` if and only
337 Scheduling a Delayable Work Item
340 A delayable work item is defined using a variable of type
344 For delayed work there are two common use cases, depending on whether a
345 deadline should be extended if a new event occurs. An example is collecting
346 data that comes in asynchronously, e.g. characters from a UART associated with
347 a keyboard. There are two APIs that submit work after a delay:
350 schedules work to be executed at a specific time or after a delay. Further
353 Use this if the policy is to keep collecting data until a specified delay
358 if the policy is to keep collecting data until a specified delay since the
363 was immediately submitted directly to the target queue, without waiting for a
364 minimal timeout (unless :c:func:`k_work_schedule()` is used and a previous
371 a pointer to the containing :c:struct:`k_work_delayable` from a pointer to
372 :c:struct:`k_work` that is passed to a work handler function.
398 These APIs must be provided with a :c:struct:`k_work_sync` object that has no
400 synchronization objects. These objects should not be allocated on a stack if
410 Sometimes the data a work item must process is naturally thread-safe, for
411 example when it's put into a :c:struct:`k_queue` by some thread and processed
415 be a flag indicating that work needs to be done, or a shared object that is
445 Be aware that if the lock is held by a thread with a lower priority than the
447 causing the application to fail. Where the idiom above is required a
448 delayable work item is preferred, and the work should be (re-)scheduled with a
458 protected by such a lock to prevent further resubmission, it's safe to do the
460 and check that state to determine whether it should do anything. Where a
473 * Submitting a work item (:c:func:`k_work_submit_to_queue`) can fail if the
475 happens the work will not be executed, which could cause a subsystem that is
479 being run by a handler. Proceeding to manipulate state shared with the work
485 There may be good reason to believe that a return value indicating that the
486 operation did not complete as expected is not a problem. In those cases the
498 However in such a case the following code must still avoid data races, as it
505 and interrupts. Attempts to externally inspect a work item's state and make
511 checking for a non-zero delay from
512 :c:func:`k_work_delayable_remaining_get()`. Those checks are fragile: a "busy"
513 indication can be obsolete by the time the test is returned, and a "not-busy"
518 A general best practice is to always maintain in shared state some condition
525 A rare case where you could safely use :c:func:`k_work_is_pending` is as a
528 submit the work while you're checking (generally because you're holding a lock
535 ISR to a shared thread. This allows the interrupt-related processing to be