mirror of
https://github.com/RT-Thread/rt-thread.git
synced 2025-01-18 11:43:34 +08:00
[update] thread.c api annotation.
This commit is contained in:
liukangcc
parent
48c7a455e6
commit
202b23371d
138
src/thread.c
138
src/thread.c
@ -40,9 +40,9 @@ static void (*rt_thread_inited_hook) (rt_thread_t thread);
|
||||
/**
|
||||
* @brief This function sets a hook function when the system suspend a thread.
|
||||
*
|
||||
* @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 the specified hook function.
|
||||
* @param hook is the specified hook function.
|
||||
*/
|
||||
void rt_thread_suspend_sethook(void (*hook)(rt_thread_t thread))
|
||||
{
|
||||
@ -52,9 +52,9 @@ void rt_thread_suspend_sethook(void (*hook)(rt_thread_t thread))
|
||||
/**
|
||||
* @brief This function sets a hook function when the system resume a thread.
|
||||
*
|
||||
* @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 the specified hook function.
|
||||
* @param hook is the specified hook function.
|
||||
*/
|
||||
void rt_thread_resume_sethook(void (*hook)(rt_thread_t thread))
|
||||
{
|
||||
@ -64,7 +64,7 @@ void rt_thread_resume_sethook(void (*hook)(rt_thread_t thread))
|
||||
/**
|
||||
* @brief 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))
|
||||
{
|
||||
@ -240,27 +240,27 @@ static rt_err_t _thread_init(struct rt_thread *thread,
|
||||
/**@{*/
|
||||
|
||||
/**
|
||||
* @brief 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.
|
||||
*
|
||||
* @param thread the static thread object.
|
||||
* @param thread is the static thread object.
|
||||
*
|
||||
* @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 entry is the entry function of thread.
|
||||
*
|
||||
* @param parameter the parameter of thread enter function.
|
||||
* @param parameter is the parameter of thread enter function.
|
||||
*
|
||||
* @param stack_start the start address of thread stack.
|
||||
* @param stack_start is the start address of thread stack.
|
||||
*
|
||||
* @param stack_size the size of thread stack.
|
||||
* @param stack_size is the size of thread stack.
|
||||
*
|
||||
* @param priority the priority of thread.
|
||||
* @param priority is the priority of thread.
|
||||
*
|
||||
* @param tick the time slice if there are same priority thread.
|
||||
* @param tick is the time slice if there are same priority thread.
|
||||
*
|
||||
* @return Return the operation status. When the return value is RT_EOK, the function is successfully executed.
|
||||
* When the return value is any other values, it means this operation failed.
|
||||
* @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,
|
||||
const char *name,
|
||||
@ -292,7 +292,7 @@ RTM_EXPORT(rt_thread_init);
|
||||
/**
|
||||
* @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)
|
||||
{
|
||||
@ -315,10 +315,10 @@ RTM_EXPORT(rt_thread_self);
|
||||
/**
|
||||
* @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 Return the operation status. When the return value is RT_EOK, the function is successfully executed.
|
||||
* When the return value is any other values, it means this operation failed.
|
||||
* @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)
|
||||
{
|
||||
@ -357,12 +357,12 @@ RTM_EXPORT(rt_thread_startup);
|
||||
|
||||
/**
|
||||
* @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 Return the operation status. When the return value is RT_EOK, the function is successfully executed.
|
||||
* When the return value is any other values, it means this operation failed.
|
||||
* @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)
|
||||
{
|
||||
@ -413,19 +413,20 @@ RTM_EXPORT(rt_thread_detach);
|
||||
* @brief This function will create a thread object and allocate thread object memory.
|
||||
* 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 entry is the entry function of thread.
|
||||
*
|
||||
* @param parameter the parameter of thread enter function.
|
||||
* @param parameter is the parameter of thread enter function.
|
||||
*
|
||||
* @param stack_size the size of thread stack.
|
||||
* @param stack_size is the size of thread stack.
|
||||
*
|
||||
* @param priority the priority of thread.
|
||||
* @param priority is the priority of thread.
|
||||
*
|
||||
* @param tick the time slice if there are same priority thread.
|
||||
* @param tick is the time slice if there are same priority thread.
|
||||
*
|
||||
* @return the created thread object.
|
||||
* @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,
|
||||
void (*entry)(void *parameter),
|
||||
@ -468,10 +469,10 @@ RTM_EXPORT(rt_thread_create);
|
||||
* @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.
|
||||
*
|
||||
* @param thread the thread to be deleted.
|
||||
* @param thread is the thread to be deleted.
|
||||
*
|
||||
* @return Return the operation status. When the return value is RT_EOK, the function is successfully executed.
|
||||
* When the return value is any other values, it means this operation failed.
|
||||
* @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)
|
||||
{
|
||||
@ -514,12 +515,12 @@ RTM_EXPORT(rt_thread_delete);
|
||||
#endif /* RT_USING_HEAP */
|
||||
|
||||
/**
|
||||
* @brief This function will let current thread yield processor, and scheduler will
|
||||
* choose a highest thread to run. After yield processor, the current thread
|
||||
* is still in READY state.
|
||||
* @brief This function will let current thread yield processor, and scheduler will
|
||||
* choose the highest thread to run. After yield processor, the current thread
|
||||
* is still in READY state.
|
||||
*
|
||||
* @return Return the operation status. When the return value is RT_EOK, the function is successfully executed.
|
||||
* When the return value is any other values, it means this operation failed.
|
||||
* @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)
|
||||
{
|
||||
@ -541,10 +542,10 @@ RTM_EXPORT(rt_thread_yield);
|
||||
* @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 Return the operation status. When the return value is RT_EOK, the function is successfully executed.
|
||||
* When the return value is any other values, it means this operation failed.
|
||||
* @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)
|
||||
{
|
||||
@ -581,10 +582,10 @@ rt_err_t rt_thread_sleep(rt_tick_t tick)
|
||||
/**
|
||||
* @brief This function will let current thread delay for some ticks.
|
||||
*
|
||||
* @param tick the delay ticks.
|
||||
* @param tick is the delay ticks.
|
||||
*
|
||||
* @return Return the operation status. When the return value is RT_EOK, the function is successfully executed.
|
||||
* When the return value is any other values, it means this operation failed.
|
||||
* @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)
|
||||
{
|
||||
@ -595,12 +596,12 @@ RTM_EXPORT(rt_thread_delay);
|
||||
/**
|
||||
* @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.
|
||||
* @param inc_tick is the increment tick.
|
||||
*
|
||||
* @return Return the operation status. When the return value is RT_EOK, the function is successfully executed.
|
||||
* When the return value is any other values, it means this operation failed.
|
||||
* @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)
|
||||
{
|
||||
@ -657,10 +658,10 @@ RTM_EXPORT(rt_thread_delay_until);
|
||||
/**
|
||||
* @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 Return the operation status. When the return value is RT_EOK, the function is successfully executed.
|
||||
* When the return value is any other values, it means this operation failed.
|
||||
* @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)
|
||||
{
|
||||
@ -675,9 +676,9 @@ RTM_EXPORT(rt_thread_mdelay);
|
||||
/**
|
||||
* @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.
|
||||
* @param cmd is the control command, which includes.
|
||||
*
|
||||
* RT_THREAD_CTRL_CHANGE_PRIORITY for changing priority level of thread.
|
||||
*
|
||||
@ -687,10 +688,10 @@ RTM_EXPORT(rt_thread_mdelay);
|
||||
*
|
||||
* RT_THREAD_CTRL_BIND_CPU for bind the thread to a CPU.
|
||||
*
|
||||
* @param arg the argument of control command.
|
||||
* @param arg is the argument of control command.
|
||||
*
|
||||
* @return Return the operation status. When the return value is RT_EOK, the function is successfully executed.
|
||||
* When the return value is any other values, it means this operation failed.
|
||||
* @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)
|
||||
{
|
||||
@ -798,13 +799,13 @@ RTM_EXPORT(rt_thread_control);
|
||||
/**
|
||||
* @brief This function will suspend the specified thread and change it to suspend state.
|
||||
*
|
||||
* @note if suspend self thread, after this function call, the
|
||||
* @note If suspend self thread, after this function call, the
|
||||
* rt_schedule() must be invoked.
|
||||
*
|
||||
* @param thread the thread to be suspended.
|
||||
* @param thread is the thread to be suspended.
|
||||
*
|
||||
* @return Return the operation status. When the return value is RT_EOK, the function is successfully executed.
|
||||
* When the return value is any other values, it means this operation failed.
|
||||
* @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_suspend(rt_thread_t thread)
|
||||
{
|
||||
@ -851,10 +852,10 @@ RTM_EXPORT(rt_thread_suspend);
|
||||
/**
|
||||
* @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 Return the operation status. When the return value is RT_EOK, the function is successfully executed.
|
||||
* When the return value is any other values, it means this operation failed.
|
||||
* @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)
|
||||
{
|
||||
@ -897,7 +898,7 @@ RTM_EXPORT(rt_thread_resume);
|
||||
* @brief This function is the timeout function for thread, normally which is invoked
|
||||
* 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)
|
||||
{
|
||||
@ -934,11 +935,12 @@ RTM_EXPORT(rt_thread_timeout);
|
||||
/**
|
||||
* @brief This function will find the specified thread.
|
||||
*
|
||||
* @note please don't invoke this function in interrupt status.
|
||||
* @note Please don't invoke this function in interrupt status.
|
||||
*
|
||||
* @param name the name of thread finding.
|
||||
* @param name is the name of thread finding.
|
||||
*
|
||||
* @return the found 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_find(char *name)
|
||||
{
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user