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 //--------------------------------------------------------------------------------------------------
   82 le_sem_Ref_t le_sem_Create
   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 //--------------------------------------------------------------------------------------------------
  106 LE_DECLARE_INLINE le_sem_Ref_t le_sem_Create
  107 (
  108     const char *name,
  109     int32_t initialCount
  110 )
  111 {
  112     return _le_sem_Create(initialCount);
  113 }
  114 #endif /* end LE_CONFIG_SEM_NAMES_ENABLED */
  115 
  116 
  117 //--------------------------------------------------------------------------------------------------
  118 /**
  119  * Delete a semaphore.
  120  *
  121  */
  122 //--------------------------------------------------------------------------------------------------
  123 void le_sem_Delete
  124 (
  125     le_sem_Ref_t    semaphorePtr   ///< [IN] Pointer to the semaphore.
  126 );
  127 
  128 
  129 #if LE_CONFIG_SEM_NAMES_ENABLED
  130 //--------------------------------------------------------------------------------------------------
  131 /**
  132  * Finds a specified semaphore's name.
  133  *
  134  *  @param[in]  name    Name of the semaphore.
  135  *
  136  *  @return
  137  *      Reference to the semaphore, or NULL if the semaphore doesn't exist.
  138  */
  139 //--------------------------------------------------------------------------------------------------
  140 le_sem_Ref_t le_sem_FindSemaphore
  141 (
  142     const char* name
  143 );
  144 #else /* if not LE_CONFIG_SEM_NAMES_ENABLED */
  145 //--------------------------------------------------------------------------------------------------
  146 /**
  147  * Finds a specified semaphore's name.
  148  *
  149  *  @param[in]  name    Name of the semaphore.
  150  *
  151  *  @return
  152  *      Reference to the semaphore, or NULL if the semaphore doesn't exist.
  153  */
  154 //--------------------------------------------------------------------------------------------------
  155 LE_DECLARE_INLINE le_sem_Ref_t le_sem_FindSemaphore
  156 (
  157     const char* name
  158 )
  159 {
  160     // Cannot look up semaphores by name if names do not exist.
  161     return NULL;
  162 }
  163 #endif /* end LE_CONFIG_SEM_NAMES_ENABLED */
  164 
  165 //--------------------------------------------------------------------------------------------------
  166 /**
  167  * Wait for a semaphore.
  168  *
  169  * @return Nothing.
  170  */
  171 //--------------------------------------------------------------------------------------------------
  172 void le_sem_Wait
  173 (
  174     le_sem_Ref_t    semaphorePtr   ///< [IN] Pointer to the semaphore.
  175 );
  176 
  177 //--------------------------------------------------------------------------------------------------
  178 /**
  179  * Try to wait for a semaphore.
  180  *
  181  * It's the same as @ref le_sem_Wait, except if it can't be immediately performed,
  182  * then returns an LE_WOULD_BLOCK instead of blocking it.
  183  *
  184  * @return Upon successful completion, returns LE_OK (0), otherwise it returns
  185  * LE_WOULD_BLOCK as the call would block if it was a blocking call.
  186  */
  187 //--------------------------------------------------------------------------------------------------
  188 le_result_t le_sem_TryWait
  189 (
  190     le_sem_Ref_t    semaphorePtr   ///< [IN] Pointer to the semaphore.
  191 );
  192 
  193 //--------------------------------------------------------------------------------------------------
  194 /**
  195  * Wait for a semaphore with a limit on how long to wait.
  196  *
  197  * @return
  198  *      - LE_OK         The function succeed
  199  *      - LE_TIMEOUT    timeToWait elapsed
  200  *
  201  * @note When LE_TIMEOUT occurs the semaphore is not decremented.
  202  */
  203 //--------------------------------------------------------------------------------------------------
  204 le_result_t le_sem_WaitWithTimeOut
  205 (
  206     le_sem_Ref_t    semaphorePtr,   ///< [IN] Pointer to the semaphore.
  207     le_clk_Time_t   timeToWait      ///< [IN] Time to wait
  208 );
  209 
  210 //--------------------------------------------------------------------------------------------------
  211 /**
  212  * Post a semaphore.
  213  *
  214  * @return Nothing.
  215  */
  216 //--------------------------------------------------------------------------------------------------
  217 void le_sem_Post
  218 (
  219     le_sem_Ref_t    semaphorePtr      ///< [IN] Pointer to the semaphore.
  220 );
  221 
  222 //--------------------------------------------------------------------------------------------------
  223 /**
  224  * Get the value of a semaphore.
  225  *
  226  * @return value of the semaphore
  227  */
  228 //--------------------------------------------------------------------------------------------------
  229 int le_sem_GetValue
  230 (
  231     le_sem_Ref_t    semaphorePtr   ///< [IN] Pointer to the semaphore.
  232 );
  233 
  234 #endif // LEGATO_SEMAPHORE_INCLUDE_GUARD
le_sem_TryWait
le_result_t le_sem_TryWait(le_sem_Ref_t semaphorePtr)


le_result_t
le_result_t
Definition: le_basics.h:35


le_sem_Ref_t
struct le_sem_t * le_sem_Ref_t
Definition: le_semaphore.h:68


le_clk_Time_t
Definition: le_clock.h:98


le_sem_FindSemaphore
le_sem_Ref_t le_sem_FindSemaphore(const char *name)


le_sem_Post
void le_sem_Post(le_sem_Ref_t semaphorePtr)


le_sem_Delete
void le_sem_Delete(le_sem_Ref_t semaphorePtr)


le_sem_Wait
void le_sem_Wait(le_sem_Ref_t semaphorePtr)


le_sem_WaitWithTimeOut
le_result_t le_sem_WaitWithTimeOut(le_sem_Ref_t semaphorePtr, le_clk_Time_t timeToWait)


le_sem_Create
le_sem_Ref_t le_sem_Create(const char *name, int32_t initialCount)


le_sem_GetValue
int le_sem_GetValue(le_sem_Ref_t semaphorePtr)


LE_DECLARE_INLINE
#define LE_DECLARE_INLINE
Definition: le_basics.h:274