TNeoKernel  v1.02
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
tn_sem.h
Go to the documentation of this file.
1 /*******************************************************************************
2  *
3  * TNeoKernel: real-time kernel initially based on TNKernel
4  *
5  * TNKernel: copyright © 2004, 2013 Yuri Tiomkin.
6  * PIC32-specific routines: copyright © 2013, 2014 Anders Montonen.
7  * TNeoKernel: copyright © 2014 Dmitry Frank.
8  *
9  * TNeoKernel was born as a thorough review and re-implementation of
10  * TNKernel. The new kernel has well-formed code, inherited bugs are fixed
11  * as well as new features being added, and it is tested carefully with
12  * unit-tests.
13  *
14  * API is changed somewhat, so it's not 100% compatible with TNKernel,
15  * hence the new name: TNeoKernel.
16  *
17  * Permission to use, copy, modify, and distribute this software in source
18  * and binary forms and its documentation for any purpose and without fee
19  * is hereby granted, provided that the above copyright notice appear
20  * in all copies and that both that copyright notice and this permission
21  * notice appear in supporting documentation.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE DMITRY FRANK AND CONTRIBUTORS "AS IS"
24  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
26  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL DMITRY FRANK OR CONTRIBUTORS BE
27  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
28  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
32  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
33  * THE POSSIBILITY OF SUCH DAMAGE.
34  *
35  ******************************************************************************/
36 
37 /**
38  * \file
39  *
40  * A semaphore: an object to provide signaling mechanism.
41  *
42  * There is a lot of confusion about differences between semaphores and
43  * mutexes, so, it's quite recommended to read small article by Michael Barr:
44  * [Mutexes and Semaphores Demystified](http://goo.gl/YprPBW).
45  *
46  * Very short:
47  *
48  * While mutex is seemingly similar to a semaphore with maximum count of `1`
49  * (the so-called binary semaphore), their usage is very different: the purpose
50  * of mutex is to protect shared resource. A locked mutex is "owned" by the
51  * task that locked it, and only the same task may unlock it. This ownership
52  * allows to implement algorithms to prevent priority inversion. So, mutex is
53  * a *locking mechanism*.
54  *
55  * Semaphore, on the other hand, is *signaling mechanism*. It's quite legal and
56  * encouraged for semaphore to be waited for in the task A, and then signaled
57  * from task B or even from ISR. It may be used in situations like "producer
58  * and consumer", etc.
59  *
60  * In addition to the article mentioned above, you may want to look at the
61  * [related question on stackoverflow.com](http://goo.gl/ZBReHK).
62  *
63  */
64 
65 #ifndef _TN_SEM_H
66 #define _TN_SEM_H
67 
68 /*******************************************************************************
69  * INCLUDED FILES
70  ******************************************************************************/
71 
72 #include "tn_list.h"
73 #include "tn_common.h"
74 
75 
76 
77 #ifdef __cplusplus
78 extern "C" { /*}*/
79 #endif
80 
81 /*******************************************************************************
82  * PUBLIC TYPES
83  ******************************************************************************/
84 
85 /**
86  * Semaphore
87  */
88 struct TN_Sem {
89  ///
90  /// List of tasks that wait for the semaphore
91  struct TN_ListItem wait_queue;
92  ///
93  /// Current semaphore counter value
94  int count;
95  ///
96  /// Max value of `count`
97  int max_count;
98  ///
99  /// id for object validity verification
100  enum TN_ObjId id_sem;
101 };
102 
103 
104 /*******************************************************************************
105  * GLOBAL VARIABLES
106  ******************************************************************************/
107 
108 /*******************************************************************************
109  * DEFINITIONS
110  ******************************************************************************/
111 
112 /*******************************************************************************
113  * PUBLIC FUNCTION PROTOTYPES
114  ******************************************************************************/
115 
116 /**
117  * Construct the semaphore. `id_sem` field should not contain
118  * `#TN_ID_SEMAPHORE`, otherwise, `#TN_RC_WPARAM` is returned.
119  *
120  * $(TN_CALL_FROM_TASK)
121  * $(TN_CALL_FROM_ISR)
122  * $(TN_LEGEND_LINK)
123  *
124  * @param sem
125  * Pointer to already allocated `struct TN_Sem`
126  * @param start_count
127  * Initial counter value, typically it is equal to `max_count`
128  * @param max_count
129  * Maximum counter value.
130  *
131  * @return
132  * * `#TN_RC_OK` if semaphore was successfully created;
133  * * If `#TN_CHECK_PARAM` is non-zero, additional return code
134  * is available: `#TN_RC_WPARAM`.
135  */
136 enum TN_RCode tn_sem_create(
137  struct TN_Sem *sem,
138  int start_count,
139  int max_count
140  );
141 
142 /**
143  * Destruct the semaphore.
144  *
145  * All tasks that wait for the semaphore become runnable with
146  * `#TN_RC_DELETED` code returned.
147  *
148  * $(TN_CALL_FROM_TASK)
149  * $(TN_CAN_SWITCH_CONTEXT)
150  * $(TN_LEGEND_LINK)
151  *
152  * @param sem semaphore to destruct
153  *
154  * @return
155  * * `#TN_RC_OK` if semaphore was successfully deleted;
156  * * `#TN_RC_WCONTEXT` if called from wrong context;
157  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
158  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
159  */
160 enum TN_RCode tn_sem_delete(struct TN_Sem *sem);
161 
162 /**
163  * Signal the semaphore.
164  *
165  * If current semaphore counter (`count`) is less than `max_count`, counter is
166  * incremented by one, and first task (if any) that \ref tn_sem_wait() "waits"
167  * for the semaphore becomes runnable with `#TN_RC_OK` returned from
168  * `tn_sem_wait()`.
169  *
170  * if semaphore counter is already has its max value, no action performed and
171  * `#TN_RC_OVERFLOW` is returned
172  *
173  * $(TN_CALL_FROM_TASK)
174  * $(TN_CAN_SWITCH_CONTEXT)
175  * $(TN_LEGEND_LINK)
176  *
177  * @param sem semaphore to signal
178  *
179  * @return
180  * * `#TN_RC_OK` if successful
181  * * `#TN_RC_WCONTEXT` if called from wrong context;
182  * * `#TN_RC_OVERFLOW` if `count` is already at maximum value (`max_count`)
183  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
184  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
185  */
186 enum TN_RCode tn_sem_signal(struct TN_Sem *sem);
187 
188 /**
189  * The same as `tn_sem_signal()` but for using in the ISR.
190  *
191  * $(TN_CALL_FROM_ISR)
192  * $(TN_CAN_SWITCH_CONTEXT)
193  * $(TN_LEGEND_LINK)
194  *
195  */
196 enum TN_RCode tn_sem_isignal(struct TN_Sem *sem);
197 
198 /**
199  * Wait for the semaphore.
200  *
201  * If the current semaphore counter (`count`) is non-zero, it is decremented
202  * and `#TN_RC_OK` is returned. Otherwise, behavior depends on `timeout` value:
203  * task might switch to $(TN_TASK_STATE_WAIT) state until someone \ref
204  * tn_sem_signal "signaled" the semaphore or until the `timeout` expired. refer
205  * to `#TN_Timeout`.
206  *
207  * $(TN_CALL_FROM_TASK)
208  * $(TN_CAN_SWITCH_CONTEXT)
209  * $(TN_CAN_SLEEP)
210  * $(TN_LEGEND_LINK)
211  *
212  * @param sem semaphore to wait for
213  * @param timeout refer to `#TN_Timeout`
214  *
215  * @return
216  * * `#TN_RC_OK` if waiting was successfull
217  * * Other possible return codes depend on `timeout` value,
218  * refer to `#TN_Timeout`
219  * * If `#TN_CHECK_PARAM` is non-zero, additional return codes
220  * are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
221  */
222 enum TN_RCode tn_sem_wait(struct TN_Sem *sem, TN_Timeout timeout);
223 
224 /**
225  * The same as `tn_sem_wait()` with zero timeout.
226  *
227  * $(TN_CALL_FROM_TASK)
228  * $(TN_CAN_SWITCH_CONTEXT)
229  * $(TN_LEGEND_LINK)
230  */
231 enum TN_RCode tn_sem_wait_polling(struct TN_Sem *sem);
232 
233 /**
234  * The same as `tn_sem_wait()` with zero timeout, but for using in the ISR.
235  *
236  * $(TN_CALL_FROM_ISR)
237  * $(TN_CAN_SWITCH_CONTEXT)
238  * $(TN_LEGEND_LINK)
239  */
240 enum TN_RCode tn_sem_iwait_polling(struct TN_Sem *sem);
241 
242 
243 #ifdef __cplusplus
244 } /* extern "C" */
245 #endif
246 
247 #endif // _TN_SEM_H
248 
249 /*******************************************************************************
250  * end of file
251  ******************************************************************************/
252 
253 
TN_Sem
Semaphore.
Definition: tn_sem.h:88
TN_RCode
TN_RCode
Result code returned by kernel services.
Definition: tn_common.h:100
TN_ObjId
TN_ObjId
Magic number for object validity verification.
Definition: tn_common.h:87
TN_Timeout
unsigned long TN_Timeout
The value representing maximum number of system ticks to wait.
Definition: tn_common.h:203
tn_sem_signal
enum TN_RCode tn_sem_signal(struct TN_Sem *sem)
Signal the semaphore.
tn_common.h
Definitions used through the whole kernel.
tn_sem_wait_polling
enum TN_RCode tn_sem_wait_polling(struct TN_Sem *sem)
The same as tn_sem_wait() with zero timeout.
TN_Sem::wait_queue
struct TN_ListItem wait_queue
List of tasks that wait for the semaphore.
Definition: tn_sem.h:91
TN_Sem::id_sem
enum TN_ObjId id_sem
id for object validity verification
Definition: tn_sem.h:100
tn_sem_iwait_polling
enum TN_RCode tn_sem_iwait_polling(struct TN_Sem *sem)
The same as tn_sem_wait() with zero timeout, but for using in the ISR.
tn_sem_delete
enum TN_RCode tn_sem_delete(struct TN_Sem *sem)
Destruct the semaphore.
tn_sem_isignal
enum TN_RCode tn_sem_isignal(struct TN_Sem *sem)
The same as tn_sem_signal() but for using in the ISR.
tn_sem_create
enum TN_RCode tn_sem_create(struct TN_Sem *sem, int start_count, int max_count)
Construct the semaphore.
TN_Sem::count
int count
Current semaphore counter value.
Definition: tn_sem.h:94
tn_sem_wait
enum TN_RCode tn_sem_wait(struct TN_Sem *sem, TN_Timeout timeout)
Wait for the semaphore.
TN_Sem::max_count
int max_count
Max value of count
Definition: tn_sem.h:97
Generated on Tue Oct 14 2014 18:35:55 for TNeoKernel by   doxygen 1.8.8