michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: kernel: workqueue: correct documentation of delayed work API

Browse source 
The delayed work API has been changed to allow cancellation in
conditions not previously documented, but this feature can cause both
submission and cancellation to fail in the general case.  Summarize
the conditions and highlight the importance of checking result codes
for these functions.

Also explicitly note that no kernel API can reliably indicate that a
work item has been completed, and that doing so is the responsibility
of the code that provides the work handler.

Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
This commit is contained in:
Peter Bigot 2020-10-02 17:22:00 -05:00 • committed by Carles Cufí
commit cbff3e34d7
2 changed files with 53 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

32
include/kernel.h
View file

@ -3270,9 +3270,9 @@ extern void k_delayed_work_init(struct k_delayed_work *work,
*
* @retval 0 Work item countdown started.
* @retval -EINVAL
* @li if a previously submitted work item had to be cancelled,
* and the cancellation failed; or
* @li Work item is being processed or has completed its work.
* * if a previously submitted work item had to be cancelled and the
* cancellation failed; or
* * Work item is being processed or has completed its work.
* @retval -EADDRINUSE Work item was submitted to a different workqueue.
*/
extern int k_delayed_work_submit_to_queue(struct k_work_q *work_q,
@ -3294,21 +3294,21 @@ extern int k_delayed_work_submit_to_queue(struct k_work_q *work_q,
* @param work Address of delayed work item.
*
* @retval 0
* @li Work item countdown cancelled before the item was submitted to its
* queue; or
* @li Work item was removed from its queue before it was processed.
* * Work item countdown cancelled before the item was submitted to its
* queue; or
* * Work item was removed from its queue before it was processed.
* @retval -EINVAL
* @li Work item has never been submitted; or
* @li Work item has been successfully cancelled; or
* @li Timeout handler is in the process of submitting the work item to its
* queue; or
* @li Work queue thread has removed the work item from the queue but has
* not called its handler.
* * Work item has never been submitted; or
* * Work item has been successfully cancelled; or
* * Timeout handler is in the process of submitting the work item to its
* queue; or
* * Work queue thread has removed the work item from the queue but has not
* called its handler.
* @retval -EALREADY
* @li Work queue thread has removed the work item from the queue and
* cleared its pending flag; or
* @li Work queue thread is invoking the item handler; or
* @li Work item handler has completed.
* * Work queue thread has removed the work item from the queue and cleared
* its pending flag; or
* * Work queue thread is invoking the item handler; or
* * Work item handler has completed.
*/
extern int k_delayed_work_cancel(struct k_delayed_work *work);