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     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 //--------------------------------------------------------------------------------------------------
  141 le_sem_Ref_t le_sem_FindSemaphore
  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 //--------------------------------------------------------------------------------------------------
  156 LE_DECLARE_INLINE le_sem_Ref_t le_sem_FindSemaphore
  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 //--------------------------------------------------------------------------------------------------
  190 le_result_t le_sem_TryWait
  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 //--------------------------------------------------------------------------------------------------
  206 le_result_t le_sem_WaitWithTimeOut
  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_sem_TryWait
le_result_t le_sem_TryWait(le_sem_Ref_t semaphorePtr)
le_result_t
le_result_t
Definition: le_basics.h:46
le_sem_Ref_t
struct le_sem_t * le_sem_Ref_t
Definition: le_semaphore.h:68
LE_UNUSED
#define LE_UNUSED(v)
Definition: le_basics.h:369
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:320