Lines Matching refs:work
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
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
33 when no work items are available.
39 * Precise tracking of the status of cancelled work items, so that the
43 * Direct submission of delayable work items to the queue with
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
51 * Safe handling of work item resubmission when the item is being processed
56 delayable work is scheduled, should be avoided to prevent race conditions
63 Any number of **work items** can be defined. Each work item is referenced
66 A work item is assigned a **handler function**, which is the function
67 executed by the workqueue's thread when the work item is processed. This
68 function accepts a single argument, which is the address of the work item
69 itself. The work item also maintains information about its status.
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
77 the preceding work items in its queue the thread will remove the next work
78 item from the queue and invoke the work item's handler function. Depending on
79 the scheduling priority of the workqueue's thread, and the work required by
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`)
90 A work item can be in multiple states; for example it can be:
94 wait until the work item completed);
98 *all simultaneously*. A work item that is in any of these states is **pending**
103 used with care, since the workqueue cannot process subsequent work items in
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;
116 the work item remains in its current place in the workqueue's queue, and
117 the work is only performed once.
119 A handler function is permitted to re-submit its work item argument
120 to the workqueue, since the work item is no longer queued at that time.
121 This allows the handler to execute work in stages, without unduly delaying
122 the processing of other work items in the workqueue's queue.
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
127 while it is busy. Furthermore, any additional information the work item's
128 handler function needs to perform its work must not be altered until
136 An ISR or a thread may need to schedule a work item that is to be processed
138 done by **scheduling** a **delayable work item** to be submitted to a
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
148 kernel submits the work item to the specified workqueue, where it remains
151 Note that work handler used for delayable still receives a pointer to the
152 underlying non-delayable work structure, which is not publicly accessible from
154 delayable work object use this idiom:
158 static void work_handler(struct k_work *work)
160 struct k_work_delayable *dwork = k_work_delayable_from_work(work);
169 The :c:func:`k_work_poll_submit` interface schedules a triggered work
173 In contrast to :c:func:`k_poll`, the triggered work does not require
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
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.
188 object's changes state, the work item is submitted to the specified workqueue,
192 The triggered work item as well as the referenced array of poll events
193 have to be valid and cannot be modified for a complete triggered work
194 item lifecycle, from submission to work item execution or cancellation.
196 An ISR or a thread may **cancel** a triggered work item it has submitted
198 stops waiting for attached poll events and the specified work is not executed.
211 to submit new work items to the system workqueue, since each new workqueue
213 justified if it is not possible for its work items to co-exist with
214 existing system workqueue work items without an unacceptable impact;
215 for example, if the new work items perform blocking operations that
256 work queue has no items left. Work items resubmitted from the workqueue
257 thread are accepted while a queue is draining, but work items from any other
258 thread or ISR are rejected. The restriction on submitting more work can be
260 blocking thread to perform additional work while the queue is "plugged".
270 A work item is defined using a variable of type :c:struct:`k_work`. It must
275 An initialized work item can be submitted to the system workqueue by
281 to resubmit the work item while it is still queued, the work item is left
287 struct k_work work;
295 k_work_submit(&my_device.work);
303 CONTAINER_OF(item, struct device_info, work);
310 /* initialize work item for printing device's error messages */
311 k_work_init(&my_device.work, print_error);
318 work item:
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
325 if the work is scheduled, queued, or running.
326 * :c:func:`k_work_flush()` may be invoked from threads to block until the work
327 item has completed. It returns immediately if the work is not pending.
328 * :c:func:`k_work_cancel()` attempts to prevent the work item from being
332 the work completes; it will return immediately if the cancellation was
333 successful or not necessary (the work wasn't submitted or running). This
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
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
356 unconditionally sets the deadline for the work, replacing any previous
361 If the work item is not scheduled both APIs behave the same. If
372 :c:struct:`k_work` that is passed to a work handler function.
375 with the work item:
378 for delayable work.
380 :c:func:`k_work_is_pending()` for delayable work.
382 for delayable work.
384 :c:func:`k_work_cancel()` for delayable work; similarly with
390 While the state of both regular and delayable work items can be determined
393 with work items after they've been submitted. :c:func:`k_work_flush()`,
401 the code is expected to work on architectures with
410 Sometimes the data a work item must process is naturally thread-safe, for
412 in the work thread. More often external synchronization is required to avoid
413 data races: cases where the work thread might inspect or manipulate shared
415 be a flag indicating that work needs to be done, or a shared object that is
416 filled by an ISR or thread and read by the work handler.
423 work thread to sleep will starve other work queue items, which may need to
429 static void work_handler(struct work *work)
431 struct work_context *parent = CONTAINER_OF(work, struct work_context,
435 /* NB: Submit will fail if the work item is being cancelled. */
436 (void)k_work_submit(work);
446 work queue the resubmission may starve the thread that would release the lock,
448 delayable work item is preferred, and the work should be (re-)scheduled with a
451 Note that submitting from the work handler can fail if the work item had been
454 to notify the application that the work could not be performed.
461 delayable work item is being rescheduled in its handler due to inability to
464 the cancellation and avoid the cancelled work item being submitted again after
470 All work API functions return status of the underlying operation, and in many
473 * Submitting a work item (:c:func:`k_work_submit_to_queue`) can fail if the
474 work is being cancelled or the queue is not accepting new items. If this
475 happens the work will not be executed, which could cause a subsystem that is
476 animated by work handler activity to become non-responsive.
478 :c:func:`k_work_cancel_delayable`) can complete while the work item is still
479 being run by a handler. Proceeding to manipulate state shared with the work
493 /* If this fails, the work handler will check pub->active and
499 cannot guarantee that the work thread is not accessing work-related state.
505 and interrupts. Attempts to externally inspect a work item's state and make
508 So when new work comes in, just submit it. Don't attempt to "optimize" by
509 checking whether the work item is already submitted by inspecting snapshot
514 indication can also be wrong if work is submitted from multiple contexts, or
515 (for delayable work) if the deadline has completed but the work is still in
519 that can be checked by the handler to confirm whether there is work to be
520 done. This way you can use the work handler as the standard cleanup path:
522 are submitted, you may be able to have everything done in the work handler
528 submit the work while you're checking (generally because you're holding a lock