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 InitValue     Initial value of the semaphore
  36  * \param MaxValue      Maximum value for the semaphore
  37  * \param Module        Module name
  38  * \param Name  Symbolic name
  39  * \note Not always needed, as initialising to 0 is valid, but it is preferred
  40  *       if all semaphores have \a Name set
  41  *
  42  * \note \a Module and \a Name must be avaliable for as long as the semaphore is used
  43  */
  44 extern void     Semaphore_Init(tSemaphore *Sem, int InitValue, int MaxValue, const char *Module, const char *Name);
  45 /**
  46  * \brief Acquire items from the semaphore
  47  * \param Sem   Semaphore structure to use
  48  * \param MaxToTake     Maximum number of items to take off the list (if zero, as much as possible is taken)
  49  * \return Number of items fetched
  50  * \retval 0    Semaphore interrupted (signal/message)
  51  * \retval -1   Unspecified error
  52  */
  53 extern int      Semaphore_Wait(tSemaphore *Sem, int MaxToTake);
  54 /**
  55  * \brief Add an "item" to the semaphore
  56  * \param Sem   Semaphore to use
  57  * \param AmmountToAdd  Number of items to add
  58  * \return Actual number of items added
  59  * \retval 0    Semaphore interrupted
  60  * \retval -1   Unspecified error
  61  */
  62 extern int      Semaphore_Signal(tSemaphore *Sem, int AmmountToAdd);
  63 /**
  64  * \brief Get the number of items waiting in a semaphore
  65  * \param Sem   Semaphore to use
  66  * \return Number of waiting items
  67  */
  68 extern int      Semaphore_GetValue(tSemaphore *Sem);
  69
  70 #endif