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

Merge pull request #5038 from liukangcc/annotation 

[update] src/thread.c function description.
This commit is contained in:
guo 2021-09-14 07:25:10 +08:00 committed by GitHub
parent a8fd81f0c0 202b23371d
commit 8e3112003c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 117 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

203
src/thread.c
View File

@ -38,12 +38,11 @@ static void (*rt_thread_resume_hook) (rt_thread_t thread);
static void (*rt_thread_inited_hook) (rt_thread_t thread); static void (*rt_thread_inited_hook) (rt_thread_t thread);
/** /**
* @ingroup Hook * @brief This function sets a hook function when the system suspend a thread.
* This function sets a hook function when the system suspend a thread.
* *
* @param hook the specified hook function * @note The hook function must be simple and never be blocked or suspend.
* *
* @note the hook function must be simple and never be blocked or suspend. * @param hook is the specified hook function.
*/ */
void rt_thread_suspend_sethook(void (*hook)(rt_thread_t thread)) void rt_thread_suspend_sethook(void (*hook)(rt_thread_t thread))
{ {
@ -51,12 +50,11 @@ void rt_thread_suspend_sethook(void (*hook)(rt_thread_t thread))
} }
/** /**
* @ingroup Hook * @brief This function sets a hook function when the system resume a thread.
* This function sets a hook function when the system resume a thread.
* *
* @param hook the specified hook function * @note The hook function must be simple and never be blocked or suspend.
* *
* @note the hook function must be simple and never be blocked or suspend. * @param hook is the specified hook function.
*/ */
void rt_thread_resume_sethook(void (*hook)(rt_thread_t thread)) void rt_thread_resume_sethook(void (*hook)(rt_thread_t thread))
{ {
@ -64,10 +62,9 @@ void rt_thread_resume_sethook(void (*hook)(rt_thread_t thread))
} }
/** /**
* @ingroup Hook * @brief This function sets a hook function when a thread is initialized.
* This function sets a hook function when a thread is initialized.
* *
* @param hook the specified hook function * @param hook is the specified hook function.
*/ */
void rt_thread_inited_sethook(void (*hook)(rt_thread_t thread)) void rt_thread_inited_sethook(void (*hook)(rt_thread_t thread))
{ {
@ -76,7 +73,6 @@ void rt_thread_inited_sethook(void (*hook)(rt_thread_t thread))
#endif /* RT_USING_HOOK */ #endif /* RT_USING_HOOK */
/* must be invoke witch rt_hw_interrupt_disable */
static void _thread_cleanup_execute(rt_thread_t thread) static void _thread_cleanup_execute(rt_thread_t thread)
{ {
register rt_base_t level; register rt_base_t level;
@ -244,19 +240,27 @@ static rt_err_t _thread_init(struct rt_thread *thread,
/**@{*/ /**@{*/
/** /**
* This function will initialize a thread, normally it's used to initialize a * @brief This function will initialize a thread. It's used to initialize a
* static thread object. * static thread object.
* *
* @param thread the static thread object * @param thread is the static thread object.
* @param name the name of thread, which shall be unique
* @param entry the entry function of thread
* @param parameter the parameter of thread enter function
* @param stack_start the start address of thread stack
* @param stack_size the size of thread stack
* @param priority the priority of thread
* @param tick the time slice if there are same priority thread
* *
* @return the operation status, RT_EOK on OK, -RT_ERROR on error * @param name is the name of thread, which shall be unique.
*
* @param entry is the entry function of thread.
*
* @param parameter is the parameter of thread enter function.
*
* @param stack_start is the start address of thread stack.
*
* @param stack_size is the size of thread stack.
*
* @param priority is the priority of thread.
*
* @param tick is the time slice if there are same priority thread.
*
* @return Return the operation status. If the return value is RT_EOK, the function is successfully executed.
* If the return value is any other values, it means this operation failed.
*/ */
rt_err_t rt_thread_init(struct rt_thread *thread, rt_err_t rt_thread_init(struct rt_thread *thread,
const char *name, const char *name,
@ -286,9 +290,9 @@ rt_err_t rt_thread_init(struct rt_thread *thread,
RTM_EXPORT(rt_thread_init); RTM_EXPORT(rt_thread_init);
/** /**
* This function will return self thread object * @brief This function will return self thread object.
* *
* @return the self thread object * @return The self thread object.
*/ */
rt_thread_t rt_thread_self(void) rt_thread_t rt_thread_self(void)
{ {
@ -309,11 +313,12 @@ rt_thread_t rt_thread_self(void)
RTM_EXPORT(rt_thread_self); RTM_EXPORT(rt_thread_self);
/** /**
* This function will start a thread and put it to system ready queue * @brief This function will start a thread and put it to system ready queue.
* *
* @param thread the thread to be started * @param thread is the thread to be started.
* *
* @return the operation status, RT_EOK on OK, -RT_ERROR on error * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed.
* If the return value is any other values, it means this operation failed.
*/ */
rt_err_t rt_thread_startup(rt_thread_t thread) rt_err_t rt_thread_startup(rt_thread_t thread)
{ {
@ -351,12 +356,13 @@ rt_err_t rt_thread_startup(rt_thread_t thread)
RTM_EXPORT(rt_thread_startup); RTM_EXPORT(rt_thread_startup);
/** /**
* This function will detach a thread. The thread object will be removed from * @brief This function will detach a thread. The thread object will be removed from
* thread queue and detached/deleted from system object management. * thread queue and detached/deleted from the system object management.
* *
* @param thread the thread to be deleted * @param thread is the thread to be deleted.
* *
* @return the operation status, RT_EOK on OK, -RT_ERROR on error * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed.
* If the return value is any other values, it means this operation failed.
*/ */
rt_err_t rt_thread_detach(rt_thread_t thread) rt_err_t rt_thread_detach(rt_thread_t thread)
{ {
@ -404,17 +410,23 @@ RTM_EXPORT(rt_thread_detach);
#ifdef RT_USING_HEAP #ifdef RT_USING_HEAP
/** /**
* This function will create a thread object and allocate thread object memory * @brief This function will create a thread object and allocate thread object memory.
* and stack. * and stack.
* *
* @param name the name of thread, which shall be unique * @param name is the name of thread, which shall be unique.
* @param entry the entry function of thread
* @param parameter the parameter of thread enter function
* @param stack_size the size of thread stack
* @param priority the priority of thread
* @param tick the time slice if there are same priority thread
* *
* @return the created thread object * @param entry is the entry function of thread.
*
* @param parameter is the parameter of thread enter function.
*
* @param stack_size is the size of thread stack.
*
* @param priority is the priority of thread.
*
* @param tick is the time slice if there are same priority thread.
*
* @return If the return value is a rt_thread structure pointer, the function is successfully executed.
* If the return value is RT_NULL, it means this operation failed.
*/ */
rt_thread_t rt_thread_create(const char *name, rt_thread_t rt_thread_create(const char *name,
void (*entry)(void *parameter), void (*entry)(void *parameter),
@ -454,12 +466,13 @@ rt_thread_t rt_thread_create(const char *name,
RTM_EXPORT(rt_thread_create); RTM_EXPORT(rt_thread_create);
/** /**
* This function will delete a thread. The thread object will be removed from * @brief This function will delete a thread. The thread object will be removed from
* thread queue and deleted from system object management in the idle thread. * thread queue and deleted from system object management in the idle thread.
* *
* @param thread the thread to be deleted * @param thread is the thread to be deleted.
* *
* @return the operation status, RT_EOK on OK, -RT_ERROR on error * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed.
* If the return value is any other values, it means this operation failed.
*/ */
rt_err_t rt_thread_delete(rt_thread_t thread) rt_err_t rt_thread_delete(rt_thread_t thread)
{ {
@ -502,11 +515,12 @@ RTM_EXPORT(rt_thread_delete);
#endif /* RT_USING_HEAP */ #endif /* RT_USING_HEAP */
/** /**
* This function will let current thread yield processor, and scheduler will * @brief This function will let current thread yield processor, and scheduler will
* choose a highest thread to run. After yield processor, the current thread * choose the highest thread to run. After yield processor, the current thread
* is still in READY state. * is still in READY state.
* *
* @return RT_EOK * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed.
* If the return value is any other values, it means this operation failed.
*/ */
rt_err_t rt_thread_yield(void) rt_err_t rt_thread_yield(void)
{ {
@ -525,11 +539,13 @@ rt_err_t rt_thread_yield(void)
RTM_EXPORT(rt_thread_yield); RTM_EXPORT(rt_thread_yield);
/** /**
* This function will let current thread sleep for some ticks. * @brief This function will let current thread sleep for some ticks. Change current thread state to suspend,
* when the thread timer reaches the tick value, scheduler will awaken this thread.
* *
* @param tick the sleep ticks * @param tick is the sleep ticks.
* *
* @return RT_EOK * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed.
* If the return value is any other values, it means this operation failed.
*/ */
rt_err_t rt_thread_sleep(rt_tick_t tick) rt_err_t rt_thread_sleep(rt_tick_t tick)
{ {
@ -564,11 +580,12 @@ rt_err_t rt_thread_sleep(rt_tick_t tick)
} }
/** /**
* This function will let current thread delay for some ticks. * @brief This function will let current thread delay for some ticks.
* *
* @param tick the delay ticks * @param tick is the delay ticks.
* *
* @return RT_EOK * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed.
* If the return value is any other values, it means this operation failed.
*/ */
rt_err_t rt_thread_delay(rt_tick_t tick) rt_err_t rt_thread_delay(rt_tick_t tick)
{ {
@ -577,12 +594,14 @@ rt_err_t rt_thread_delay(rt_tick_t tick)
RTM_EXPORT(rt_thread_delay); RTM_EXPORT(rt_thread_delay);
/** /**
* This function will let current thread delay until (*tick + inc_tick). * @brief This function will let current thread delay until (*tick + inc_tick).
* *
* @param tick the tick of last wakeup. * @param tick is the tick of last wakeup.
* @param inc_tick the increment tick
* *
* @return RT_EOK * @param inc_tick is the increment tick.
*
* @return Return the operation status. If the return value is RT_EOK, the function is successfully executed.
* If the return value is any other values, it means this operation failed.
*/ */
rt_err_t rt_thread_delay_until(rt_tick_t *tick, rt_tick_t inc_tick) rt_err_t rt_thread_delay_until(rt_tick_t *tick, rt_tick_t inc_tick)
{ {
@ -637,11 +656,12 @@ rt_err_t rt_thread_delay_until(rt_tick_t *tick, rt_tick_t inc_tick)
RTM_EXPORT(rt_thread_delay_until); RTM_EXPORT(rt_thread_delay_until);
/** /**
* This function will let current thread delay for some milliseconds. * @brief This function will let current thread delay for some milliseconds.
* *
* @param ms the delay ms time * @param ms is the delay ms time.
* *
* @return RT_EOK * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed.
* If the return value is any other values, it means this operation failed.
*/ */
rt_err_t rt_thread_mdelay(rt_int32_t ms) rt_err_t rt_thread_mdelay(rt_int32_t ms)
{ {
@ -654,17 +674,24 @@ rt_err_t rt_thread_mdelay(rt_int32_t ms)
RTM_EXPORT(rt_thread_mdelay); RTM_EXPORT(rt_thread_mdelay);
/** /**
* This function will control thread behaviors according to control command. * @brief This function will control thread behaviors according to control command.
* *
* @param thread the specified thread to be controlled * @param thread is the specified thread to be controlled.
* @param cmd the control command, which includes
* RT_THREAD_CTRL_CHANGE_PRIORITY for changing priority level of thread;
* RT_THREAD_CTRL_STARTUP for starting a thread;
* RT_THREAD_CTRL_CLOSE for delete a thread;
* RT_THREAD_CTRL_BIND_CPU for bind the thread to a CPU.
* @param arg the argument of control command
* *
* @return RT_EOK * @param cmd is the control command, which includes.
*
* RT_THREAD_CTRL_CHANGE_PRIORITY for changing priority level of thread.
*
* RT_THREAD_CTRL_STARTUP for starting a thread.
*
* RT_THREAD_CTRL_CLOSE for delete a thread.
*
* RT_THREAD_CTRL_BIND_CPU for bind the thread to a CPU.
*
* @param arg is the argument of control command.
*
* @return Return the operation status. If the return value is RT_EOK, the function is successfully executed.
* If the return value is any other values, it means this operation failed.
*/ */
rt_err_t rt_thread_control(rt_thread_t thread, int cmd, void *arg) rt_err_t rt_thread_control(rt_thread_t thread, int cmd, void *arg)
{ {
@ -770,14 +797,15 @@ rt_err_t rt_thread_control(rt_thread_t thread, int cmd, void *arg)
RTM_EXPORT(rt_thread_control); RTM_EXPORT(rt_thread_control);
/** /**
* This function will suspend the specified thread. * @brief This function will suspend the specified thread and change it to suspend state.
* *
* @param thread the thread to be suspended * @note If suspend self thread, after this function call, the
* rt_schedule() must be invoked.
* *
* @return the operation status, RT_EOK on OK, -RT_ERROR on error * @param thread is the thread to be suspended.
* *
* @note if suspend self thread, after this function call, the * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed.
* rt_schedule() must be invoked. * If the return value is any other values, it means this operation failed.
*/ */
rt_err_t rt_thread_suspend(rt_thread_t thread) rt_err_t rt_thread_suspend(rt_thread_t thread)
{ {
@ -822,11 +850,12 @@ rt_err_t rt_thread_suspend(rt_thread_t thread)
RTM_EXPORT(rt_thread_suspend); RTM_EXPORT(rt_thread_suspend);
/** /**
* This function will resume a thread and put it to system ready queue. * @brief This function will resume a thread and put it to system ready queue.
* *
* @param thread the thread to be resumed * @param thread is the thread to be resumed.
* *
* @return the operation status, RT_EOK on OK, -RT_ERROR on error * @return Return the operation status. If the return value is RT_EOK, the function is successfully executed.
* If the return value is any other values, it means this operation failed.
*/ */
rt_err_t rt_thread_resume(rt_thread_t thread) rt_err_t rt_thread_resume(rt_thread_t thread)
{ {
@ -866,10 +895,10 @@ rt_err_t rt_thread_resume(rt_thread_t thread)
RTM_EXPORT(rt_thread_resume); RTM_EXPORT(rt_thread_resume);
/** /**
* This function is the timeout function for thread, normally which is invoked * @brief This function is the timeout function for thread, normally which is invoked
* when thread is timeout to wait some resource. * when thread is timeout to wait some resource.
* *
* @param parameter the parameter of thread timeout function * @param parameter is the parameter of thread timeout function
*/ */
void rt_thread_timeout(void *parameter) void rt_thread_timeout(void *parameter)
{ {
@ -904,18 +933,20 @@ void rt_thread_timeout(void *parameter)
RTM_EXPORT(rt_thread_timeout); RTM_EXPORT(rt_thread_timeout);
/** /**
* This function will find the specified thread. * @brief This function will find the specified thread.
* *
* @param name the name of thread finding * @note Please don't invoke this function in interrupt status.
* *
* @return the found thread * @param name is the name of thread finding.
* *
* @note please don't invoke this function in interrupt status. * @return If the return value is a rt_thread structure pointer, the function is successfully executed.
* If the return value is RT_NULL, it means this operation failed.
*/ */
rt_thread_t rt_thread_find(char *name) rt_thread_t rt_thread_find(char *name)
{ {
return (rt_thread_t)rt_object_find(name, RT_Object_Class_Thread); return (rt_thread_t)rt_object_find(name, RT_Object_Class_Thread);
} }
RTM_EXPORT(rt_thread_find); RTM_EXPORT(rt_thread_find);
/**@}*/ /**@}*/