Lines Matching full:to
10 A :dfn:`workqueue` is a kernel object that uses a dedicated thread to process
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.
24 thread is configurable, allowing it to be either cooperative or preemptive
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
37 implementation used prior to release 2.6. Among the changes are:
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
49 specifically allowing a previous deadline to remain unchanged when a work
56 delayable work is scheduled, should be avoided to prevent race conditions
74 A work item may be **queued** (:c:enumerator:`K_WORK_QUEUED`) by submitting it to a
76 to the workqueue's queue. Once the workqueue's thread has processed all of
83 A delayable work item may be **scheduled** (:c:enumerator:`K_WORK_DELAYED`) to a
93 * marked canceling (because a thread used :c:func:`k_work_cancel_sync()` to
95 * queued to run again on the same queue;
96 * scheduled to be submitted to a (possibly different) queue
101 A handler function can use any kernel API available to threads. However,
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
109 structure. The handler function can then use the argument value to compute the
111 thereby obtain access to the additional information it needs.
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
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
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
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
153 :c:struct:`k_work_delayable`. To get access to an object that contains the
170 item in response to a **poll event** (see :ref:`polling_v2`), that will
173 In contrast to :c:func:`k_poll`, the triggered work does not require
179 * A pointer to an array of poll events that will trigger work item
180 submissions to the workqueue
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,
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.
205 available to any application or kernel code that requires workqueue support.
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
216 would delay other system workqueue processing to an unacceptable degree.
218 How to Use Workqueues
229 :c:macro:`K_THREAD_STACK_DEFINE` to ensure it is properly set up in
249 In addition the queue identity and certain behavior related to thread
253 The following API can be used to interact with a workqueue:
255 * :c:func:`k_work_queue_drain()` can be used to block the caller until the
259 extended past the completion of the drain operation in order to allow the
260 blocking thread to perform additional work while the queue is "plugged".
263 item will silently fail to be submitted.
264 * :c:func:`k_work_queue_unplug()` removes any previous block on submission to
265 the queue due to a previous drain operation.
275 An initialized work item can be submitted to the system workqueue by
276 calling :c:func:`k_work_submit`, or to a specified workqueue by
280 of error messages to the system workqueue. Note that if the ISR attempts
281 to resubmit the work item while it is still queued, the work item is left
317 The following API can be used to check the status of or synchronize with the
326 * :c:func:`k_work_flush()` may be invoked from threads to block until the work
328 * :c:func:`k_work_cancel()` attempts to prevent the work item from being
329 executed. This may or may not be successful. This is safe to invoke
331 * :c:func:`k_work_cancel_sync()` may be invoked from threads to block until
334 can be used after :c:func:`k_work_cancel()` is invoked (from an ISR)` to
350 schedules work to be executed at a specific time or after a delay. Further
351 attempts to schedule the same item with this API before the delay completes
352 will not change the time at which the item will be submitted to its queue.
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
370 The helper function :c:func:`k_work_delayable_from_work()` can be used to get
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.
374 The following additional API can be used to check the status of or synchronize
377 * :c:func:`k_work_delayable_busy_get()` is the analog to :c:func:`k_work_busy_get()`
379 * :c:func:`k_work_delayable_is_pending()` is the analog to
381 * :c:func:`k_work_flush_delayable()` is the analog to :c:func:`k_work_flush()`
383 * :c:func:`k_work_cancel_delayable()` is the analog to
395 can be invoked from thread context to wait until the requested state has been
399 application-inspectable components but is needed to provide the
401 the code is expected to work on architectures with
412 in the work thread. More often external synchronization is required to avoid
415 be a flag indicating that work needs to be done, or a shared object that is
420 :c:struct:`k_mutex` , ...) may be used to ensure data races don't occur.
423 work thread to sleep will starve other work queue items, which may need to
424 make progress in order to get the lock released. Work handlers should try to
447 causing the application to fail. Where the idiom above is required a
449 non-zero delay to allow the thread holding the lock to make progress.
454 to notify the application that the work could not be performed.
456 Work items in isolation are self-locking, so you don't need to hold an
457 external lock just to submit or schedule them. Even if you use external state
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
461 delayable work item is being rescheduled in its handler due to inability to
463 application/driver when the cancel is initiated, would be required to detect
471 cases it is important to verify that the intended result was obtained.
476 animated by work handler activity to become non-responsive.
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
487 code should clearly document this, by (1) casting the return value to ``void``
488 to indicate that the result is intentionally ignored, and (2) documenting what
504 The workqueue API is designed to be safe when invoked from multiple threads
505 and interrupts. Attempts to externally inspect a work item's state and make
506 decisions based on the result are likely to create new problems.
508 So when new work comes in, just submit it. Don't attempt to "optimize" by
518 A general best practice is to always maintain in shared state some condition
519 that can be checked by the handler to confirm whether there is work to be
521 rather than having to deal with cancellation and cleanup at points where items
522 are submitted, you may be able to have everything done in the work handler
526 check to avoid invoking :c:func:`k_work_flush` or
529 that prevents access to state used for submission).
534 Use the system workqueue to defer complex interrupt-related processing from an
535 ISR to a shared thread. This allows the interrupt-related processing to be
536 done promptly without compromising the system's ability to respond to
537 subsequent interrupts, and does not require the application to define and
538 manage an additional thread to do the processing.