libs/rt-thread
libs
/
rt-thread
4
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[workqueue] improve comment

This commit is contained in:
Meco Man 2022-01-16 15:05:50 -05:00 committed by Bernard Xiong
parent 1874bd25aa
commit 3a789b3317
1 changed files with 44 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
components/drivers/src/workqueue.c
View File

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2006-2021, RT-Thread Development Team * Copyright (c) 2006-2022, RT-Thread Development Team
* *
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
@ -213,11 +213,13 @@ static void _delayed_work_timeout_handler(void *parameter)
/** /**
* @brief Create a work queue with a thread inside. * @brief Create a work queue with a thread inside.
* *
* @param name The name of the work queue thread. * @param name is a name of the work queue thread.
* @param stack_size The stack size of the work queue thread.
* @param priority The priority of the work queue thread.
* *
* @return Return A pointer to the workqueue object. It will return RT_NULL if failed. * @param stack_size is stack size of the work queue thread.
*
* @param priority is a priority of the work queue thread.
*
* @return Return a pointer to the workqueue object. It will return RT_NULL if failed.
*/ */
struct rt_workqueue *rt_workqueue_create(const char *name, rt_uint16_t stack_size, rt_uint8_t priority) struct rt_workqueue *rt_workqueue_create(const char *name, rt_uint16_t stack_size, rt_uint8_t priority)
{ {
@ -249,9 +251,9 @@ struct rt_workqueue *rt_workqueue_create(const char *name, rt_uint16_t stack_siz
/** /**
* @brief Destroy a work queue. * @brief Destroy a work queue.
* *
* @param queue A pointer to the workqueue object. * @param queue is a pointer to the workqueue object.
* *
* @return RT_EOK Success. * @return RT_EOK Success.
*/ */
rt_err_t rt_workqueue_destroy(struct rt_workqueue *queue) rt_err_t rt_workqueue_destroy(struct rt_workqueue *queue)
{ {
@ -268,11 +270,12 @@ rt_err_t rt_workqueue_destroy(struct rt_workqueue *queue)
/** /**
* @brief Submit a work item to the work queue without delay. * @brief Submit a work item to the work queue without delay.
* *
* @param queue A pointer to the workqueue object. * @param queue is a pointer to the workqueue object.
* @param work A pointer to the work item object. *
* @param work is a pointer to the work item object.
* *
* @return RT_EOK Success. * @return RT_EOK Success.
* @return -RT_EBUSY This work item is executing. * -RT_EBUSY This work item is executing.
*/ */
rt_err_t rt_workqueue_dowork(struct rt_workqueue *queue, struct rt_work *work) rt_err_t rt_workqueue_dowork(struct rt_workqueue *queue, struct rt_work *work)
{ {
@ -285,14 +288,17 @@ rt_err_t rt_workqueue_dowork(struct rt_workqueue *queue, struct rt_work *work)
/** /**
* @brief Submit a work item to the work queue with a delay. * @brief Submit a work item to the work queue with a delay.
* *
* @param queue A pointer to the workqueue object. * @param queue is a pointer to the workqueue object.
* @param work A pointer to the work item object. *
* @param time The delay time (unit: OS ticks) for the work item to be submitted to the work queue. * @param work is a pointer to the work item object.
* The max timeout tick should be no more than (RT_TICK_MAX/2 - 1) *
* @param time is the delay time (unit: OS ticks) for the work item to be submitted to the work queue.
*
* NOTE: The max timeout tick should be no more than (RT_TICK_MAX/2 - 1)
* *
* @return RT_EOK Success. * @return RT_EOK Success.
* @return -RT_EBUSY This work item is executing. * -RT_EBUSY This work item is executing.
* @return -RT_ERROR The time parameter is invalid. * -RT_ERROR The time parameter is invalid.
*/ */
rt_err_t rt_workqueue_submit_work(struct rt_workqueue *queue, struct rt_work *work, rt_tick_t time) rt_err_t rt_workqueue_submit_work(struct rt_workqueue *queue, struct rt_work *work, rt_tick_t time)
{ {
@ -305,14 +311,16 @@ rt_err_t rt_workqueue_submit_work(struct rt_workqueue *queue, struct rt_work *wo
/** /**
* @brief Submit a work item to the work queue without delay. This work item will be executed after the current work item. * @brief Submit a work item to the work queue without delay. This work item will be executed after the current work item.
* *
* @param queue A pointer to the workqueue object. * @param queue is a pointer to the workqueue object.
* @param work A pointer to the work item object. *
* @param work is a pointer to the work item object.
* *
* @return RT_EOK Success. * @return RT_EOK Success.
*/ */
rt_err_t rt_workqueue_urgent_work(struct rt_workqueue *queue, struct rt_work *work) rt_err_t rt_workqueue_urgent_work(struct rt_workqueue *queue, struct rt_work *work)
{ {
rt_base_t level; rt_base_t level;
RT_ASSERT(queue != RT_NULL); RT_ASSERT(queue != RT_NULL);
RT_ASSERT(work != RT_NULL); RT_ASSERT(work != RT_NULL);
@ -340,24 +348,27 @@ rt_err_t rt_workqueue_urgent_work(struct rt_workqueue *queue, struct rt_work *wo
/** /**
* @brief Cancel a work item in the work queue. * @brief Cancel a work item in the work queue.
* *
* @param queue A pointer to the workqueue object. * @param queue is a pointer to the workqueue object.
* @param work A pointer to the work item object. *
* @param work is a pointer to the work item object.
* *
* @return RT_EOK Success. * @return RT_EOK Success.
* @return -RT_EBUSY This work item is executing. * -RT_EBUSY This work item is executing.
*/ */
rt_err_t rt_workqueue_cancel_work(struct rt_workqueue *queue, struct rt_work *work) rt_err_t rt_workqueue_cancel_work(struct rt_workqueue *queue, struct rt_work *work)
{ {
RT_ASSERT(work != RT_NULL); RT_ASSERT(work != RT_NULL);
RT_ASSERT(queue != RT_NULL); RT_ASSERT(queue != RT_NULL);
return _workqueue_cancel_work(queue, work); return _workqueue_cancel_work(queue, work);
} }
/** /**
* @brief Cancel a work item in the work queue. If the work item is executing, this function will block until it is done. * @brief Cancel a work item in the work queue. If the work item is executing, this function will block until it is done.
* *
* @param queue A pointer to the workqueue object. * @param queue is a pointer to the workqueue object.
* @param work A pointer to the work item object. *
* @param work is a pointer to the work item object.
* *
* @return RT_EOK Success. * @return RT_EOK Success.
*/ */
@ -382,7 +393,7 @@ rt_err_t rt_workqueue_cancel_work_sync(struct rt_workqueue *queue, struct rt_wor
/** /**
* @brief This function will cancel all work items in work queue. * @brief This function will cancel all work items in work queue.
* *
* @param queue A pointer to the workqueue object. * @param queue is a pointer to the workqueue object.
* *
* @return RT_EOK Success. * @return RT_EOK Success.
*/ */
@ -416,12 +427,15 @@ static struct rt_workqueue *sys_workq;
/** /**
* @brief Submit a work item to the system work queue with a delay. * @brief Submit a work item to the system work queue with a delay.
* *
* @param work A pointer to the work item object. * @param work is a pointer to the work item object.
* @param time The delay time (unit: OS ticks) for the work item to be submitted to the work queue. *
* @param time is the delay time (unit: OS ticks) for the work item to be submitted to the work queue.
*
* NOTE: The max timeout tick should be no more than (RT_TICK_MAX/2 - 1)
* *
* @return RT_EOK Success. * @return RT_EOK Success.
* @return -RT_EBUSY This work item is executing. * -RT_EBUSY This work item is executing.
* @return -RT_ERROR The time parameter is invalid. * -RT_ERROR The time parameter is invalid.
*/ */
rt_err_t rt_work_submit(struct rt_work *work, rt_tick_t time) rt_err_t rt_work_submit(struct rt_work *work, rt_tick_t time)
{ {
@ -431,10 +445,10 @@ rt_err_t rt_work_submit(struct rt_work *work, rt_tick_t time)
/** /**
* @brief Cancel a work item in the system work queue. * @brief Cancel a work item in the system work queue.
* *
* @param work A pointer to the work item object. * @param work is a pointer to the work item object.
* *
* @return RT_EOK Success. * @return RT_EOK Success.
* @return -RT_EBUSY This work item is executing. * -RT_EBUSY This work item is executing.
*/ */
rt_err_t rt_work_cancel(struct rt_work *work) rt_err_t rt_work_cancel(struct rt_work *work)
{ {