Kernel/include/semaphore.h

   1 /*
   2  * Acess2 Kernel
   3  * semaphore.h
   4  * - Semaphore syncronisation primitive
   5  */
   6 #ifndef _SEMAPHORE_H
   7 #define _SEMAPHORE_H
   8
   9 #include <acess.h>
  10
  11 /**
  12  * \brief Semaphore typedef
  13  */
  14 typedef struct sSemaphore       tSemaphore;
  15
  16 /**
  17  * \brief Semaphore structure
  18  */
  19 struct sSemaphore {
  20         tShortSpinlock  Protector;      //!< Protector for the lock strucure
  21         const char      *ModName;       //!< Human-readable module name
  22         const char      *Name;  //!< Human-readable name
  23         volatile int    Value;  //!< Current value
  24         volatile int    MaxValue;       //!< Maximum value (signal will wait if it will go over this)
  25
  26         struct sThread  *Waiting;       //!< Waiting threads
  27         struct sThread  *LastWaiting;   //!< Waiting threads
  28         struct sThread  *Signaling;     //!< Waiting threads (from Semaphore_Signal)
  29         struct sThread  *LastSignaling; //!< Last waiting thread (from Semaphore_Signal)
  30 };
  31
  32 /**
  33  * \brief Initialise the semaphore
  34  * \param Sem   Semaphore structure to initialsie
  35  * \param Value Initial value of the semaphore
  36  * \param Module        Module name
  37  * \param Name  Symbolic name
  38  * \note Not always needed, as initialising to 0 is valid, but it is preferred
  39  *       if all semaphores have \a Name set
  40  *
  41  * \note \a Module and \a Name must be avaliable for as long as the semaphore is used
  42  */
  43 extern void     Semaphore_Init(tSemaphore *Sem, int InitValue, int MaxValue, const char *Module, const char *Name);
  44 /**
  45  * \brief Acquire items from the semaphore
  46  * \param Semaphore     Semaphore structure to use
  47  * \param MaxToTake     Maximum number of items to take off the list (if zero, as much as possible is taken)
  48  * \return Number of items fetched
  49  * \retval 0    Semaphore interrupted (signal/message)
  50  * \retval -1   Unspecified error
  51  */
  52 extern int      Semaphore_Wait(tSemaphore *Sem, int MaxToTake);
  53 /**
  54  * \brief Add an "item" to the semaphore
  55  * \param Sem   Semaphore to use
  56  * \param AmmountToAdd  Number of items to add
  57  * \return Actual number of items added
  58  * \retval 0    Semaphore interrupted
  59  * \retval -1   Unspecified error
  60  */
  61 extern int      Semaphore_Signal(tSemaphore *Sem, int AmmountToAdd);
  62 /**
  63  * \brief Get the number of items waiting in a semaphore
  64  * \param Sem   Semaphore to use
  65  * \return Number of waiting items
  66  */
  67 extern int      Semaphore_GetValue(tSemaphore *Sem);
  68
  69 #endif