thread_flags.h
4.76 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
/*
* Copyright (C) 2015 Kaspar Schleiser <kaspar@schleiser.de>
*
* This file is subject to the terms and conditions of the GNU Lesser
* General Public License v2.1. See the file LICENSE in the top level
* directory for more details.
*/
/**
* @ingroup core_thread
* @brief Thread flags
* @{
*
* @file
* @brief Thread flags API
*
* This API can be used to notify threads of conditions in a race-free
* and allocation-less way.
*
* Each thread can handle up to 16 boolean flags, stored as a bitmask in the
* flags field of its thread. Those flags can be set or unset, using
* thread_flags_set(), from ISR's, other threads or even by the thread itself.
*
* A thread can wait for any combination of its flags to become set, using
* thread_flags_wait_any() or thread_flags_wait_all().
* Those functions clear flags that caused them to return.
* It is not possible to wait for flags to become unset.
*
* Thread flags have certain properties that make them the preferred choice
* over messages or mutexes in some circumstances:
*
* - setting thread flags cannot fail
* If messages are used to notify a thread of a condition from within an ISR,
* and the receiving thread is not waiting, has no queue or the queue is
* full, the ISR cannot deliver the message. A thread flag can always be set.
*
* - thread flags are very flexible
* With thread flags it is possible to wait for multiple conditions and
* messages at the same time. When mutexes are used to notify about events,
* only one event can be waited for.
*
* Usually, if it is only of interest that an event occurred, but not how many
* of them, thread flags should be considered.
*
* Note that some flags (currently the three most significant bits) are used by
* core functions and should not be set by the user. They can be waited for.
*
* @author Kaspar Schleiser <kaspar@schleiser.de>
*/
#ifndef THREAD_FLAG_H
#define THREAD_FLAG_H
#include "kernel_types.h"
#include "sched.h" /* for thread_t typedef */
#ifdef __cplusplus
extern "C" {
#endif
/**
* @name reserved thread flags
* @{
*/
#define THREAD_FLAG_MSG_WAITING (0x1<<15)
#define THREAD_FLAG_MUTEX_UNLOCKED (0x1<<14)
#define THREAD_FLAG_TIMEOUT (0x1<<13)
/** @} */
/**
* @name Define type of thread_flags_t
*/
typedef uint16_t thread_flags_t;
/**
* @brief Set thread flags, possibly waking it up
*
* @param[in] thread thread to work on
* @param[in] mask additional flags to be set for the current thread,
* represented as a bitmask
*/
void thread_flags_set(thread_t *thread, thread_flags_t mask);
/**
* @brief Clear current thread's flags
*
* @param[in] mask unset flags for the current thread,
* represented as a bitmask
*
* @returns flags that have actually been cleared (mask & thread->flags before clear)
*/
thread_flags_t thread_flags_clear(thread_flags_t mask);
/**
* @brief Wait for any flag in mask to become set (blocking)
*
* If any of the flags in mask are already set, this function will return
* immediately, otherwise, it will suspend the thread (as
* THREAD_STATUS_WAIT_ANY) until any of the flags in mask get set.
*
* Both ways, it will clear and return (sched_active_thread-flags & mask).
*
* @param[in] mask mask of flags to wait for
*
* @returns flags that caused return/wakeup ((sched_active_thread-flags & mask).
*/
thread_flags_t thread_flags_wait_any(thread_flags_t mask);
/**
* @brief Wait for all flags in mask to become set (blocking)
*
* If all the flags in mask are already set, this function will return
* immediately, otherwise, it will suspend the thread (as
* THREAD_STATUS_WAIT_ALL) until all of the flags in mask have been set.
*
* Both ways, it will clear and return (sched_active_thread-flags & mask).
*
* @param[in] mask mask of flags to wait for
*
* @returns mask
*/
thread_flags_t thread_flags_wait_all(thread_flags_t mask);
/**
* @brief Wait for any flags in mask to become set (blocking), one at a time
*
* This function is like thread_flags_wait_any(), but will only clear and return
* one flag at a time, least significant set bit first.
*
* @param[in] mask mask of flags to wait for
*
* @returns flag that triggered the return / wait
*/
thread_flags_t thread_flags_wait_one(thread_flags_t mask);
/**
* @brief Possibly Wake up thread waiting for flags
*
* Wakes up a thread if it is thread flag blocked and its condition is met.
* Has to be called with interrupts disabled.
* Does not trigger yield.
*
* @internal
*
* @param[in] thread thread to possibly wake up
* @return 1 if @p thread has been woken up
* 0 otherwise
*/
int thread_flags_wake(thread_t *thread);
#ifdef __cplusplus
}
#endif
/** @} */
#endif /* THREAD_FLAG_H */