le_semaphore.h

Go to the documentation of this file.
1 /** @page c_semaphore Semaphore API
2  *
3  * @ref 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. Use of this work is subject to license.
48  *
49  */
50 
51 /** @file le_semaphore.h
52  *
53  *
54  * Legato @ref c_semaphore include file.
55  *
56  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
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 /**
72  * Create a semaphore shared by threads within the same process.
73  *
74  * @note Terminates the process on failure, no need to check the return value for errors.
75  */
76 //--------------------------------------------------------------------------------------------------
78 (
79  const char* name, ///< [IN] Name of the semaphore.
80  int32_t initialCount ///< [IN] Initial number of semaphore.
81 );
82 
83 //--------------------------------------------------------------------------------------------------
84 /**
85  * Delete a semaphore.
86  *
87  */
88 //--------------------------------------------------------------------------------------------------
89 void le_sem_Delete
90 (
91  le_sem_Ref_t semaphorePtr ///< [IN] Pointer to the semaphore.
92 );
93 
94 //--------------------------------------------------------------------------------------------------
95 /**
96  * Finds a specified semaphore's name.
97  *
98  * @return
99  * Reference to the semaphore, or NULL if the semaphore doesn't exist.
100  */
101 //--------------------------------------------------------------------------------------------------
103 (
104  const char* name ///< [IN] Name of the semaphore.
105 );
106 
107 //--------------------------------------------------------------------------------------------------
108 /**
109  * Wait for a semaphore.
110  *
111  * @return Nothing.
112  */
113 //--------------------------------------------------------------------------------------------------
114 void le_sem_Wait
115 (
116  le_sem_Ref_t semaphorePtr ///< [IN] Pointer to the semaphore.
117 );
118 
119 //--------------------------------------------------------------------------------------------------
120 /**
121  * Try to wait for a semaphore.
122  *
123  * It's the same as @ref le_sem_Wait, except if it can't be immediately performed,
124  * then returns an LE_WOULD_BLOCK instead of blocking it.
125  *
126  * @return Upon successful completion, returns LE_OK (0), otherwise it returns
127  * LE_WOULD_BLOCK as the call would block if it was a blocking call.
128  */
129 //--------------------------------------------------------------------------------------------------
131 (
132  le_sem_Ref_t semaphorePtr ///< [IN] Pointer to the semaphore.
133 );
134 
135 //--------------------------------------------------------------------------------------------------
136 /**
137  * Wait for a semaphore with a limit on how long to wait.
138  *
139  * @return
140  * - LE_OK The function succeed
141  * - LE_TIMEOUT timeToWait elapsed
142  *
143  * @note When LE_TIMEOUT occurs the semaphore is not decremented.
144  */
145 //--------------------------------------------------------------------------------------------------
147 (
148  le_sem_Ref_t semaphorePtr, ///< [IN] Pointer to the semaphore.
149  le_clk_Time_t timeToWait ///< [IN] Time to wait
150 );
151 
152 //--------------------------------------------------------------------------------------------------
153 /**
154  * Post a semaphore.
155  *
156  * @return Nothing.
157  */
158 //--------------------------------------------------------------------------------------------------
159 void le_sem_Post
160 (
161  le_sem_Ref_t semaphorePtr ///< [IN] Pointer to the semaphore.
162 );
163 
164 //--------------------------------------------------------------------------------------------------
165 /**
166  * Get the value of a semaphore.
167  *
168  * @return value of the semaphore
169  */
170 //--------------------------------------------------------------------------------------------------
171 int le_sem_GetValue
172 (
173  le_sem_Ref_t semaphorePtr ///< [IN] Pointer to the semaphore.
174 );
175 
176 #endif // LEGATO_SEMAPHORE_INCLUDE_GUARD
le_result_t le_sem_TryWait(le_sem_Ref_t semaphorePtr)
le_result_t
Definition: le_basics.h:35
struct le_sem_t * le_sem_Ref_t
Definition: le_semaphore.h:68
le_sem_Ref_t le_sem_FindSemaphore(const char *name)
void le_sem_Post(le_sem_Ref_t semaphorePtr)
Definition: le_clock.h:92
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)