Merge pull request #4942 from Jackistang/master
[add] add commets for ringbuffer and workqueue.
This commit is contained in:
commit
a98860d146
|
@ -5,6 +5,7 @@
|
|||
*
|
||||
* Change Logs:
|
||||
* Date Author Notes
|
||||
* 2021-08-14 Jackistang add comments for function interface.
|
||||
*/
|
||||
#ifndef RINGBUFFER_H__
|
||||
#define RINGBUFFER_H__
|
||||
|
@ -80,6 +81,13 @@ struct rt_ringbuffer* rt_ringbuffer_create(rt_uint16_t length);
|
|||
void rt_ringbuffer_destroy(struct rt_ringbuffer *rb);
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @brief Get the buffer size of the ring buffer object.
|
||||
*
|
||||
* @param rb A pointer to the ring buffer object.
|
||||
*
|
||||
* @return Buffer size.
|
||||
*/
|
||||
rt_inline rt_uint16_t rt_ringbuffer_get_size(struct rt_ringbuffer *rb)
|
||||
{
|
||||
RT_ASSERT(rb != RT_NULL);
|
||||
|
|
|
@ -6,6 +6,7 @@
|
|||
* Change Logs:
|
||||
* Date Author Notes
|
||||
* 2021-08-01 Meco Man remove rt_delayed_work_init() and rt_delayed_work structure
|
||||
* 2021-08-14 Jackistang add comments for rt_work_init()
|
||||
*/
|
||||
#ifndef WORKQUEUE_H__
|
||||
#define WORKQUEUE_H__
|
||||
|
@ -67,6 +68,13 @@ rt_err_t rt_work_submit(struct rt_work *work, rt_tick_t time);
|
|||
rt_err_t rt_work_cancel(struct rt_work *work);
|
||||
#endif /* RT_USING_SYSTEM_WORKQUEUE */
|
||||
|
||||
/**
|
||||
* @brief Initialize a work item, binding with a callback function.
|
||||
*
|
||||
* @param work A pointer to the work item object.
|
||||
* @param work_func A callback function that will be called when this work item is executed.
|
||||
* @param work_data A user data passed to the callback function as the second parameter.
|
||||
*/
|
||||
rt_inline void rt_work_init(struct rt_work *work, void (*work_func)(struct rt_work *work, void *work_data),
|
||||
void *work_data)
|
||||
{
|
||||
|
|
|
@ -9,6 +9,7 @@
|
|||
* 2013-05-08 Grissiom reimplement
|
||||
* 2016-08-18 heyuanjie add interface
|
||||
* 2021-07-20 arminker fix write_index bug in function rt_ringbuffer_put_force
|
||||
* 2021-08-14 Jackistang add comments for function interface.
|
||||
*/
|
||||
|
||||
#include <rtthread.h>
|
||||
|
@ -27,6 +28,13 @@ rt_inline enum rt_ringbuffer_state rt_ringbuffer_status(struct rt_ringbuffer *rb
|
|||
return RT_RINGBUFFER_HALFFULL;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Initialize the ring buffer object.
|
||||
*
|
||||
* @param rb A pointer to the ring buffer object.
|
||||
* @param pool A pointer to the buffer.
|
||||
* @param size The size of the buffer in bytes.
|
||||
*/
|
||||
void rt_ringbuffer_init(struct rt_ringbuffer *rb,
|
||||
rt_uint8_t *pool,
|
||||
rt_int16_t size)
|
||||
|
@ -45,7 +53,13 @@ void rt_ringbuffer_init(struct rt_ringbuffer *rb,
|
|||
RTM_EXPORT(rt_ringbuffer_init);
|
||||
|
||||
/**
|
||||
* put a block of data into ring buffer
|
||||
* @brief Put a block of data into the ring buffer. If the capacity of ring buffer is insufficient, it will discard out-of-range data.
|
||||
*
|
||||
* @param rb A pointer to the ring buffer object.
|
||||
* @param ptr A pointer to the data buffer.
|
||||
* @param length The size of data in bytes.
|
||||
*
|
||||
* @return Return the data size we put into the ring buffer.
|
||||
*/
|
||||
rt_size_t rt_ringbuffer_put(struct rt_ringbuffer *rb,
|
||||
const rt_uint8_t *ptr,
|
||||
|
@ -92,9 +106,13 @@ rt_size_t rt_ringbuffer_put(struct rt_ringbuffer *rb,
|
|||
RTM_EXPORT(rt_ringbuffer_put);
|
||||
|
||||
/**
|
||||
* put a block of data into ring buffer
|
||||
* @brief Put a block of data into the ring buffer. If the capacity of ring buffer is insufficient, it will overwrite the existing data in the ring buffer.
|
||||
*
|
||||
* When the buffer is full, it will discard the old data.
|
||||
* @param rb A pointer to the ring buffer object.
|
||||
* @param ptr A pointer to the data buffer.
|
||||
* @param length The size of data in bytes.
|
||||
*
|
||||
* @return Return the data size we put into the ring buffer.
|
||||
*/
|
||||
rt_size_t rt_ringbuffer_put_force(struct rt_ringbuffer *rb,
|
||||
const rt_uint8_t *ptr,
|
||||
|
@ -149,7 +167,13 @@ rt_size_t rt_ringbuffer_put_force(struct rt_ringbuffer *rb,
|
|||
RTM_EXPORT(rt_ringbuffer_put_force);
|
||||
|
||||
/**
|
||||
* get data from ring buffer
|
||||
* @brief Get data from the ring buffer.
|
||||
*
|
||||
* @param rb A pointer to the ring buffer.
|
||||
* @param ptr A pointer to the data buffer.
|
||||
* @param length The size of the data we want to read from the ring buffer.
|
||||
*
|
||||
* @return Return the data size we read from the ring buffer.
|
||||
*/
|
||||
rt_size_t rt_ringbuffer_get(struct rt_ringbuffer *rb,
|
||||
rt_uint8_t *ptr,
|
||||
|
@ -196,7 +220,14 @@ rt_size_t rt_ringbuffer_get(struct rt_ringbuffer *rb,
|
|||
RTM_EXPORT(rt_ringbuffer_get);
|
||||
|
||||
/**
|
||||
* peak data from ring buffer
|
||||
* @brief Get the first readable byte of the ring buffer.
|
||||
*
|
||||
* @param rb A pointer to the ringbuffer.
|
||||
* @param ptr When this function return, *ptr is a pointer to the first readable byte of the ring buffer.
|
||||
*
|
||||
* @note It is recommended to read only one byte, otherwise it may cause buffer overflow.
|
||||
*
|
||||
* @return Return the size of the ring buffer.
|
||||
*/
|
||||
rt_size_t rt_ringbuffer_peak(struct rt_ringbuffer *rb, rt_uint8_t **ptr)
|
||||
{
|
||||
|
@ -230,7 +261,12 @@ rt_size_t rt_ringbuffer_peak(struct rt_ringbuffer *rb, rt_uint8_t **ptr)
|
|||
RTM_EXPORT(rt_ringbuffer_peak);
|
||||
|
||||
/**
|
||||
* put a character into ring buffer
|
||||
* @brief Put a byte into the ring buffer. If ring buffer is full, this operation will fail.
|
||||
*
|
||||
* @param rb A pointer to the ring buffer object.
|
||||
* @param ch A byte put into the ring buffer.
|
||||
*
|
||||
* @return Return the data size we put into the ring buffer. The ring buffer is full if returns 0. Otherwise, it will return 1.
|
||||
*/
|
||||
rt_size_t rt_ringbuffer_putchar(struct rt_ringbuffer *rb, const rt_uint8_t ch)
|
||||
{
|
||||
|
@ -258,9 +294,12 @@ rt_size_t rt_ringbuffer_putchar(struct rt_ringbuffer *rb, const rt_uint8_t ch)
|
|||
RTM_EXPORT(rt_ringbuffer_putchar);
|
||||
|
||||
/**
|
||||
* put a character into ring buffer
|
||||
* @brief Put a byte into the ring buffer. If ring buffer is full, it will discard an old data and put into a new data.
|
||||
*
|
||||
* When the buffer is full, it will discard one old data.
|
||||
* @param rb A pointer to the ring buffer object.
|
||||
* @param ch A byte put into the ring buffer.
|
||||
*
|
||||
* @return Return the data size we put into the ring buffer. Always return 1.
|
||||
*/
|
||||
rt_size_t rt_ringbuffer_putchar_force(struct rt_ringbuffer *rb, const rt_uint8_t ch)
|
||||
{
|
||||
|
@ -295,7 +334,13 @@ rt_size_t rt_ringbuffer_putchar_force(struct rt_ringbuffer *rb, const rt_uint8_t
|
|||
RTM_EXPORT(rt_ringbuffer_putchar_force);
|
||||
|
||||
/**
|
||||
* get a character from a ringbuffer
|
||||
* @brief Get a byte from the ring buffer.
|
||||
*
|
||||
* @param rb The pointer to the ring buffer object.
|
||||
* @param ch A pointer to the buffer, used to store one byte.
|
||||
*
|
||||
* @return 0 The ring buffer is empty.
|
||||
* @return 1 Success
|
||||
*/
|
||||
rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch)
|
||||
{
|
||||
|
@ -305,7 +350,7 @@ rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch)
|
|||
if (!rt_ringbuffer_data_len(rb))
|
||||
return 0;
|
||||
|
||||
/* put character */
|
||||
/* put byte */
|
||||
*ch = rb->buffer_ptr[rb->read_index];
|
||||
|
||||
if (rb->read_index == rb->buffer_size-1)
|
||||
|
@ -323,7 +368,11 @@ rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch)
|
|||
RTM_EXPORT(rt_ringbuffer_getchar);
|
||||
|
||||
/**
|
||||
* get the size of data in rb
|
||||
* @brief Get the size of data in the ring buffer in bytes.
|
||||
*
|
||||
* @param rb The pointer to the ring buffer object.
|
||||
*
|
||||
* @return Return the size of data in the ring buffer in bytes.
|
||||
*/
|
||||
rt_size_t rt_ringbuffer_data_len(struct rt_ringbuffer *rb)
|
||||
{
|
||||
|
@ -348,7 +397,9 @@ rt_size_t rt_ringbuffer_data_len(struct rt_ringbuffer *rb)
|
|||
RTM_EXPORT(rt_ringbuffer_data_len);
|
||||
|
||||
/**
|
||||
* empty the rb
|
||||
* @brief Reset the ring buffer object, and clear all contents in the buffer.
|
||||
*
|
||||
* @param rb A pointer to the ring buffer object.
|
||||
*/
|
||||
void rt_ringbuffer_reset(struct rt_ringbuffer *rb)
|
||||
{
|
||||
|
@ -363,7 +414,14 @@ RTM_EXPORT(rt_ringbuffer_reset);
|
|||
|
||||
#ifdef RT_USING_HEAP
|
||||
|
||||
struct rt_ringbuffer* rt_ringbuffer_create(rt_uint16_t size)
|
||||
/**
|
||||
* @brief Create a ring buffer object with a given size.
|
||||
*
|
||||
* @param size The size of the buffer in bytes.
|
||||
*
|
||||
* @return Return a pointer to ring buffer object. When the return value is RT_NULL, it means this creation failed.
|
||||
*/
|
||||
struct rt_ringbuffer *rt_ringbuffer_create(rt_uint16_t size)
|
||||
{
|
||||
struct rt_ringbuffer *rb;
|
||||
rt_uint8_t *pool;
|
||||
|
@ -390,6 +448,11 @@ exit:
|
|||
}
|
||||
RTM_EXPORT(rt_ringbuffer_create);
|
||||
|
||||
/**
|
||||
* @brief Destroy the ring buffer object, which is created by rt_ringbuffer_create() .
|
||||
*
|
||||
* @param rb A pointer to the ring buffer object.
|
||||
*/
|
||||
void rt_ringbuffer_destroy(struct rt_ringbuffer *rb)
|
||||
{
|
||||
RT_ASSERT(rb != RT_NULL);
|
||||
|
|
|
@ -7,6 +7,7 @@
|
|||
* Date Author Notes
|
||||
* 2017-02-27 Bernard fix the re-work issue.
|
||||
* 2021-08-01 Meco Man remove rt_delayed_work_init()
|
||||
* 2021-08-14 Jackistang add comments for function interface.
|
||||
*/
|
||||
|
||||
#include <rthw.h>
|
||||
|
@ -209,6 +210,15 @@ static void _delayed_work_timeout_handler(void *parameter)
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Create a work queue with a thread inside.
|
||||
*
|
||||
* @param name The 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.
|
||||
*/
|
||||
struct rt_workqueue *rt_workqueue_create(const char *name, rt_uint16_t stack_size, rt_uint8_t priority)
|
||||
{
|
||||
struct rt_workqueue *queue = RT_NULL;
|
||||
|
@ -236,6 +246,13 @@ struct rt_workqueue *rt_workqueue_create(const char *name, rt_uint16_t stack_siz
|
|||
return queue;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Destroy a work queue.
|
||||
*
|
||||
* @param queue A pointer to the workqueue object.
|
||||
*
|
||||
* @return RT_EOK Success.
|
||||
*/
|
||||
rt_err_t rt_workqueue_destroy(struct rt_workqueue *queue)
|
||||
{
|
||||
RT_ASSERT(queue != RT_NULL);
|
||||
|
@ -248,6 +265,15 @@ rt_err_t rt_workqueue_destroy(struct rt_workqueue *queue)
|
|||
return RT_EOK;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Submit a work item to the work queue without delay.
|
||||
*
|
||||
* @param queue A pointer to the workqueue object.
|
||||
* @param work A pointer to the work item object.
|
||||
*
|
||||
* @return RT_EOK Success.
|
||||
* @return -RT_EBUSY This work item is executing.
|
||||
*/
|
||||
rt_err_t rt_workqueue_dowork(struct rt_workqueue *queue, struct rt_work *work)
|
||||
{
|
||||
RT_ASSERT(queue != RT_NULL);
|
||||
|
@ -256,6 +282,17 @@ rt_err_t rt_workqueue_dowork(struct rt_workqueue *queue, struct rt_work *work)
|
|||
return _workqueue_submit_work(queue, work, 0);
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Submit a work item to the work queue with a delay.
|
||||
*
|
||||
* @param queue 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.
|
||||
*
|
||||
* @return RT_EOK Success.
|
||||
* @return -RT_EBUSY This work item is executing.
|
||||
* @return -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_ASSERT(queue != RT_NULL);
|
||||
|
@ -264,6 +301,14 @@ rt_err_t rt_workqueue_submit_work(struct rt_workqueue *queue, struct rt_work *wo
|
|||
return _workqueue_submit_work(queue, work, time);
|
||||
}
|
||||
|
||||
/**
|
||||
* @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 work A pointer to the work item object.
|
||||
*
|
||||
* @return RT_EOK Success.
|
||||
*/
|
||||
rt_err_t rt_workqueue_critical_work(struct rt_workqueue *queue, struct rt_work *work)
|
||||
{
|
||||
rt_base_t level;
|
||||
|
@ -291,6 +336,15 @@ rt_err_t rt_workqueue_critical_work(struct rt_workqueue *queue, struct rt_work *
|
|||
return RT_EOK;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Cancel a work item in the work queue.
|
||||
*
|
||||
* @param queue A pointer to the workqueue object.
|
||||
* @param work A pointer to the work item object.
|
||||
*
|
||||
* @return RT_EOK Success.
|
||||
* @return -RT_EBUSY This work item is executing.
|
||||
*/
|
||||
rt_err_t rt_workqueue_cancel_work(struct rt_workqueue *queue, struct rt_work *work)
|
||||
{
|
||||
RT_ASSERT(work != RT_NULL);
|
||||
|
@ -298,6 +352,14 @@ rt_err_t rt_workqueue_cancel_work(struct rt_workqueue *queue, struct rt_work *wo
|
|||
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.
|
||||
*
|
||||
* @param queue A pointer to the workqueue object.
|
||||
* @param work A pointer to the work item object.
|
||||
*
|
||||
* @return RT_EOK Success.
|
||||
*/
|
||||
rt_err_t rt_workqueue_cancel_work_sync(struct rt_workqueue *queue, struct rt_work *work)
|
||||
{
|
||||
RT_ASSERT(queue != RT_NULL);
|
||||
|
@ -316,6 +378,13 @@ rt_err_t rt_workqueue_cancel_work_sync(struct rt_workqueue *queue, struct rt_wor
|
|||
return RT_EOK;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief This function will cancel all work items in work queue.
|
||||
*
|
||||
* @param queue A pointer to the workqueue object.
|
||||
*
|
||||
* @return RT_EOK Success.
|
||||
*/
|
||||
rt_err_t rt_workqueue_cancel_all_work(struct rt_workqueue *queue)
|
||||
{
|
||||
struct rt_work *work;
|
||||
|
@ -343,11 +412,29 @@ rt_err_t rt_workqueue_cancel_all_work(struct rt_workqueue *queue)
|
|||
#ifdef RT_USING_SYSTEM_WORKQUEUE
|
||||
static struct rt_workqueue *sys_workq;
|
||||
|
||||
/**
|
||||
* @brief Submit a work item to the system work queue with a delay.
|
||||
*
|
||||
* @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.
|
||||
*
|
||||
* @return RT_EOK Success.
|
||||
* @return -RT_EBUSY This work item is executing.
|
||||
* @return -RT_ERROR The time parameter is invalid.
|
||||
*/
|
||||
rt_err_t rt_work_submit(struct rt_work *work, rt_tick_t time)
|
||||
{
|
||||
return rt_workqueue_submit_work(sys_workq, work, time);
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Cancel a work item in the system work queue.
|
||||
*
|
||||
* @param work A pointer to the work item object.
|
||||
*
|
||||
* @return RT_EOK Success.
|
||||
* @return -RT_EBUSY This work item is executing.
|
||||
*/
|
||||
rt_err_t rt_work_cancel(struct rt_work *work)
|
||||
{
|
||||
return rt_workqueue_cancel_work(sys_workq, work);
|
||||
|
|
Loading…
Reference in New Issue