le_semaphore.h

Go to the documentation of this file.
1 /** @page c_semaphore Semaphore API
2  *
3  * @subpage le_semaphore.h "API Reference"
4  *
5  * <HR>
6  * This API provides standard semaphore functionality, but with added diagnostic capabilities.
7  * These semaphores can only be shared by threads within the same process.
8  *
9  * Semaphores can wait (decrease value by one) and post (increase value by one).
10  *
11  * In Legato, semaphores are dynamically allocated objects.
12  *
13  * @section create_semaphore Creating a Semaphore
14  *
15  * le_sem_Create() creates a semaphore, returning a reference to it (of type le_sem_Ref_t).
16  *
17  * All semaphores have names. This is required for diagnostic purposes. See
18  * @ref diagnostics_semaphore below.
19  *
20  * @section use_semaphore Using a Semaphore
21  *
22  * Functions to increase and decrease semaphores are:
23  * - @c le_sem_Post()
24  * - @c le_sem_Wait()
25  * - @c le_sem_TryWait()
26  * - @c le_sem_WaitWithTimeOut()
27  *
28  * Function to get a semaphore's current value is:
29  * - @c le_sem_GetValue()
30  *
31  * @section delete_semaphore Deleting a Semaphore
32  *
33  * When you are finished with a semaphore, you must delete it by calling le_sem_Delete().
34  *
35  * There must not be anything using the semaphore when it is deleted
36  * (i.e., no one can be waiting on it).
37  *
38  * @section diagnostics_semaphore Diagnostics
39  *
40  * The command-line @ref toolsTarget_inspect tool can be used to list the
41  * semaphores that currently exist inside a given process.
42  * The state of each semaphore can be seen, including a list of any threads that
43  * might be waiting for that semaphore.
44  *
45  * <HR>
46  *
47  * Copyright (C) Sierra Wireless Inc.
48  *
49  */
50 
51 /** @file le_semaphore.h
52  *
53  *
54  * Legato @ref c_semaphore include file.
55  *
56  * Copyright (C) Sierra Wireless Inc.
57  */
58 
59 #ifndef LEGATO_SEMAPHORE_INCLUDE_GUARD
60 #define LEGATO_SEMAPHORE_INCLUDE_GUARD
61 
62 //--------------------------------------------------------------------------------------------------
63 /**
64  * Reference to Semaphore structure.
65  *
66  */
67 //--------------------------------------------------------------------------------------------------
68 typedef struct le_sem_t* le_sem_Ref_t;
69 
70 
71 #if LE_CONFIG_SEM_NAMES_ENABLED
72 //--------------------------------------------------------------------------------------------------
73 /**
74  * Create a semaphore shared by threads within the same process.
75  *
76  * @param[in] name Name of the semaphore.
77  * @param[in] initialCount Initial number of semaphore.
78  *
79  * @note Terminates the process on failure, no need to check the return value for errors.
80  */
81 //--------------------------------------------------------------------------------------------------
83 (
84  const char *name,
85  int32_t initialCount
86 );
87 #else /* if not LE_CONFIG_SEM_NAMES_ENABLED */
88 /// @cond HIDDEN_IN_USER_DOCS
89 //--------------------------------------------------------------------------------------------------
90 /**
91  * Internal function used to implement le_sem_Create().
92  */
93 //--------------------------------------------------------------------------------------------------
94 le_sem_Ref_t _le_sem_Create(int32_t initialCount);
95 /// @endcond
96 //--------------------------------------------------------------------------------------------------
97 /**
98  * Create a semaphore shared by threads within the same process.
99  *
100  * @param[in] name Name of the semaphore.
101  * @param[in] initialCount Initial number of semaphore.
102  *
103  * @note Terminates the process on failure, no need to check the return value for errors.
104  */
105 //--------------------------------------------------------------------------------------------------
107 (
108  const char *name,
109  int32_t initialCount
110 )
111 {
112  LE_UNUSED(name);
113  return _le_sem_Create(initialCount);
114 }
115 #endif /* end LE_CONFIG_SEM_NAMES_ENABLED */
116 
117 
118 //--------------------------------------------------------------------------------------------------
119 /**
120  * Delete a semaphore.
121  *
122  */
123 //--------------------------------------------------------------------------------------------------
124 void le_sem_Delete
125 (
126  le_sem_Ref_t semaphorePtr ///< [IN] Pointer to the semaphore.
127 );
128 
129 
130 #if LE_CONFIG_SEM_NAMES_ENABLED
131 //--------------------------------------------------------------------------------------------------
132 /**
133  * Finds a specified semaphore's name.
134  *
135  * @param[in] name Name of the semaphore.
136  *
137  * @return
138  * Reference to the semaphore, or NULL if the semaphore doesn't exist.
139  */
140 //--------------------------------------------------------------------------------------------------
142 (
143  const char* name
144 );
145 #else /* if not LE_CONFIG_SEM_NAMES_ENABLED */
146 //--------------------------------------------------------------------------------------------------
147 /**
148  * Finds a specified semaphore's name.
149  *
150  * @param[in] name Name of the semaphore.
151  *
152  * @return
153  * Reference to the semaphore, or NULL if the semaphore doesn't exist.
154  */
155 //--------------------------------------------------------------------------------------------------
157 (
158  const char* name
159 )
160 {
161  LE_UNUSED(name);
162  // Cannot look up semaphores by name if names do not exist.
163  return NULL;
164 }
165 #endif /* end LE_CONFIG_SEM_NAMES_ENABLED */
166 
167 //--------------------------------------------------------------------------------------------------
168 /**
169  * Wait for a semaphore.
170  *
171  * @return Nothing.
172  */
173 //--------------------------------------------------------------------------------------------------
174 void le_sem_Wait
175 (
176  le_sem_Ref_t semaphorePtr ///< [IN] Pointer to the semaphore.
177 );
178 
179 //--------------------------------------------------------------------------------------------------
180 /**
181  * Try to wait for a semaphore.
182  *
183  * It's the same as @ref le_sem_Wait, except if it can't be immediately performed,
184  * then returns an LE_WOULD_BLOCK instead of blocking it.
185  *
186  * @return Upon successful completion, returns LE_OK (0), otherwise it returns
187  * LE_WOULD_BLOCK as the call would block if it was a blocking call.
188  */
189 //--------------------------------------------------------------------------------------------------
191 (
192  le_sem_Ref_t semaphorePtr ///< [IN] Pointer to the semaphore.
193 );
194 
195 //--------------------------------------------------------------------------------------------------
196 /**
197  * Wait for a semaphore with a limit on how long to wait.
198  *
199  * @return
200  * - LE_OK The function succeed
201  * - LE_TIMEOUT timeToWait elapsed
202  *
203  * @note When LE_TIMEOUT occurs the semaphore is not decremented.
204  */
205 //--------------------------------------------------------------------------------------------------
207 (
208  le_sem_Ref_t semaphorePtr, ///< [IN] Pointer to the semaphore.
209  le_clk_Time_t timeToWait ///< [IN] Time to wait
210 );
211 
212 //--------------------------------------------------------------------------------------------------
213 /**
214  * Post a semaphore.
215  *
216  * @return Nothing.
217  */
218 //--------------------------------------------------------------------------------------------------
219 void le_sem_Post
220 (
221  le_sem_Ref_t semaphorePtr ///< [IN] Pointer to the semaphore.
222 );
223 
224 //--------------------------------------------------------------------------------------------------
225 /**
226  * Get the value of a semaphore.
227  *
228  * @return value of the semaphore
229  */
230 //--------------------------------------------------------------------------------------------------
231 int le_sem_GetValue
232 (
233  le_sem_Ref_t semaphorePtr ///< [IN] Pointer to the semaphore.
234 );
235 
236 #endif // LEGATO_SEMAPHORE_INCLUDE_GUARD
le_result_t le_sem_TryWait(le_sem_Ref_t semaphorePtr)
le_result_t
Definition: le_basics.h:45
struct le_sem_t * le_sem_Ref_t
Definition: le_semaphore.h:68
#define LE_UNUSED(v)
Definition: le_basics.h:366
Definition: le_clock.h:98
le_sem_Ref_t le_sem_FindSemaphore(const char *name)
void le_sem_Post(le_sem_Ref_t semaphorePtr)
void le_sem_Delete(le_sem_Ref_t semaphorePtr)
void le_sem_Wait(le_sem_Ref_t semaphorePtr)
le_result_t le_sem_WaitWithTimeOut(le_sem_Ref_t semaphorePtr, le_clk_Time_t timeToWait)
le_sem_Ref_t le_sem_Create(const char *name, int32_t initialCount)
int le_sem_GetValue(le_sem_Ref_t semaphorePtr)
#define LE_DECLARE_INLINE
Definition: le_basics.h:317