1 /*
2 * Copyright (c) 2006-2024, RT-Thread Development Team
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 *
6 * Change Logs:
7 * Date Author Notes
8 * 2024-04-26 Shell lockless rt_completion
9 */
10 #include <rtthread.h>
11 #include <rthw.h>
12 #include <rtdevice.h>
13
14 /**
15 * @brief This function indicates a completion has done.
16 *
17 * @param completion is a pointer to a completion object.
18 */
rt_completion_done(struct rt_completion * completion)19 void rt_completion_done(struct rt_completion *completion)
20 {
21 rt_completion_wakeup_by_errno(completion, -1);
22 }
23 RTM_EXPORT(rt_completion_done);
24
25 /**
26 * @brief This function indicates a completion has done and wakeup the thread
27 *
28 * @param completion is a pointer to a completion object.
29 * @return RT_EOK if wakeup succeed.
30 * RT_EEMPTY if wakeup failure and the completion is set to completed.
31 * RT_EBUSY if the completion is still in completed state
32 */
rt_completion_wakeup(struct rt_completion * completion)33 rt_err_t rt_completion_wakeup(struct rt_completion *completion)
34 {
35 return rt_completion_wakeup_by_errno(completion, -1);
36 }
37
38 /**
39 * @brief This is same as rt_completion_wait(), except that this API is NOT
40 * ISR-safe (you can NOT call completion_done() on isr routine).
41 *
42 * @param completion is a pointer to a completion object.
43 *
44 * @param timeout is a timeout period (unit: OS ticks). If the completion is unavailable, the thread will wait for
45 * the completion done up to the amount of time specified by the argument.
46 * NOTE: Generally, we use the macro RT_WAITING_FOREVER to set this parameter, which means that when the
47 * completion is unavailable, the thread will be waitting forever.
48 *
49 * @return Return the operation status. ONLY when the return value is RT_EOK, the operation is successful.
50 * If the return value is any other values, it means that the completion wait failed.
51 *
52 * @warning This function can ONLY be called in the thread context. It MUST NOT be called in interrupt context.
53 */
rt_completion_wait_noisr(struct rt_completion * completion,rt_int32_t timeout)54 rt_err_t rt_completion_wait_noisr(struct rt_completion *completion,
55 rt_int32_t timeout)
56 {
57 return rt_completion_wait_flags_noisr(completion, timeout, RT_UNINTERRUPTIBLE);
58 }
59
60 /**
61 * @brief This function will wait for a completion, if the completion is unavailable, the thread shall wait for
62 * the completion up to a specified time.
63 *
64 * @param completion is a pointer to a completion object.
65 *
66 * @param timeout is a timeout period (unit: OS ticks). If the completion is unavailable, the thread will wait for
67 * the completion done up to the amount of time specified by the argument.
68 * NOTE: Generally, we use the macro RT_WAITING_FOREVER to set this parameter, which means that when the
69 * completion is unavailable, the thread will be waitting forever.
70 *
71 * @return Return the operation status. ONLY when the return value is RT_EOK, the operation is successful.
72 * If the return value is any other values, it means that the completion wait failed.
73 *
74 * @warning This function can ONLY be called in the thread context. It MUST NOT be called in interrupt context.
75 */
rt_completion_wait(struct rt_completion * completion,rt_int32_t timeout)76 rt_err_t rt_completion_wait(struct rt_completion *completion,
77 rt_int32_t timeout)
78 {
79 return rt_completion_wait_flags(completion, timeout, RT_UNINTERRUPTIBLE);
80 }
81 RTM_EXPORT(rt_completion_wait);
82