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 //--------------------------------------------------------------------------------------------------
   77 le_sem_Ref_t le_sem_Create
   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 //--------------------------------------------------------------------------------------------------
  102 le_sem_Ref_t le_sem_FindSemaphore
  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 //--------------------------------------------------------------------------------------------------
  130 le_result_t le_sem_TryWait
  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 //--------------------------------------------------------------------------------------------------
  146 le_result_t le_sem_WaitWithTimeOut
  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_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_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_clk_Time_t
Definition: le_clock.h:92


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)