Lines Matching +full:cancel +full:- +full:in +full:- +full:progress
11 work items in a first in, first out manner. Each work item is processed by
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.
23 * A **thread** that processes the work items in the queue. The priority of the
77 the preceding work items in its queue the thread will remove the next work
80 other items in the queue, a queued work item may be processed quickly or it
81 may remain in the queue for an extended period of time.
90 A work item can be in multiple states; for example it can be:
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
116 the work item remains in its current place in the workqueue's queue, and
119 A handler function is permitted to re-submit its work item argument
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.
126 by the workqueue thread. This means a work item must not be re-initialized
144 A delayable work item is initialized and scheduled to a workqueue in a similar
149 queued until it is processed in the standard manner.
152 underlying non-delayable work structure, which is not publicly accessible from
156 .. code-block:: c
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
173 In contrast to :c:func:`k_poll`, the triggered work does not require
184 A triggered work item is initialized and submitted to a workqueue in a similar
189 where it remains queued until it is processed in the standard manner.
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
212 incurs a significant cost in memory footprint. A new workqueue can be
213 justified if it is not possible for its work items to co-exist with
229 :c:macro:`K_THREAD_STACK_DEFINE` to ensure it is properly set up in
234 .. code-block:: c
249 In addition the queue identity and certain behavior related to thread
259 extended past the completion of the drain operation in order to allow the
272 :c:macro:`K_WORK_DEFINE` in which case initialization is performed at
273 compile-time.
284 .. code-block:: c
304 printk("Got error on device %s\n", the_device->name);
335 confirm completion of an ISR-initiated cancellation.
346 data that comes in asynchronously, e.g. characters from a UART associated with
399 application-inspectable components but is needed to provide the
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
418 For simple flags :ref:`atomic_v2` may be sufficient. In other cases spin
419 locks (:c:struct:`k_spinlock`) or thread-aware locks (:c:struct:`k_sem`,
424 make progress in order to get the lock released. Work handlers should try to
425 take the lock with its no-wait path. For example:
427 .. code-block:: c
434 if (k_mutex_lock(&parent->lock, K_NO_WAIT) != 0) {
441 k_mutex_unlock(&parent->lock);
448 delayable work item is preferred, and the work should be (re-)scheduled with a
449 non-zero delay to allow the thread holding the lock to make progress.
456 Work items in isolation are self-locking, so you don't need to hold an
461 delayable work item is being rescheduled in its handler due to inability to
462 take the lock some other self-locking state, such as an atomic flag set by the
463 application/driver when the cancel is initiated, would be required to detect
470 All work API functions return status of the underlying operation, and in many
476 animated by work handler activity to become non-responsive.
480 handler will result in data races that can cause failures.
482 Many race conditions have been present in Zephyr code because the results of
486 operation did not complete as expected is not a problem. In those cases the
489 happens in the unexpected case. For example:
491 .. code-block:: c
493 /* If this fails, the work handler will check pub->active and
496 (void)k_work_cancel_delayable(&pub->timer);
498 However in such a case the following code must still avoid data races, as it
499 cannot guarantee that the work thread is not accessing work-related state.
508 So when new work comes in, just submit it. Don't attempt to "optimize" by
511 checking for a non-zero delay from
513 indication can be obsolete by the time the test is returned, and a "not-busy"
515 (for delayable work) if the deadline has completed but the work is still in
518 A general best practice is to always maintain in shared state some condition
522 are submitted, you may be able to have everything done in the work handler
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