ACE/ace/Semaphore.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Semaphore.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //==========================================================================
  10
  11 #ifndef ACE_SEMAPHORE_H
  12 #define ACE_SEMAPHORE_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include /**/ "ace/ACE_export.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #include "ace/OS_NS_Thread.h"
  22
  23 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  24
  25 class ACE_Time_Value;
  26
  27 /**
  28  * @class ACE_Semaphore
  29  *
  30  * @brief Wrapper for Dijkstra style general semaphores.
  31  */
  32 class ACE_Export ACE_Semaphore
  33 {
  34 public:
  35   /// Initialize the semaphore, with initial value of "count".
  36   ACE_Semaphore (unsigned int count = 1, // By default make this unlocked.
  37                  int type = USYNC_THREAD,
  38                  const ACE_TCHAR *name = 0,
  39                  void * = 0,
  40                  int max = 0x7fffffff);
  41
  42   /// Implicitly destroy the semaphore.
  43   ~ACE_Semaphore ();
  44
  45   /**
  46    * Explicitly destroy the semaphore.  Note that only one thread
  47    * should call this method since it doesn't protect against race
  48    * conditions.
  49    */
  50   int remove ();
  51
  52   /// Block the thread until the semaphore count becomes
  53   /// greater than 0, then decrement it.
  54   int acquire ();
  55
  56   /**
  57    * Block the thread until the semaphore count becomes greater than 0
  58    * (at which point it is decremented) or until @a tv times out (in
  59    * which case -1 is returned and @c errno == @c ETIME).  Note that @a tv
  60    * is assumed to be in "absolute" rather than "relative" time.  The
  61    * value of @a tv is updated upon return to show the actual
  62    * (absolute) acquisition time.
  63    */
  64   int acquire (ACE_Time_Value &tv);
  65
  66   /**
  67    * If @a tv == 0 then call <acquire()> directly.  Otherwise, Block
  68    * the thread until the semaphore count becomes greater than 0
  69    * (at which point it is decremented) or until @a tv times out (in
  70    * which case -1 is returned and @c errno == @c ETIME).  Note that
  71    * <*tv> is assumed to be in "absolute" rather than "relative" time.
  72    * The value of <*tv> is updated upon return to show the actual
  73    * (absolute) acquisition time.
  74    */
  75   int acquire (ACE_Time_Value *tv);
  76
  77   /**
  78    * Conditionally decrement the semaphore if count is greater than 0
  79    * (i.e., won't block).  Returns -1 on failure.  If we "failed"
  80    * because someone else already had the lock, @c errno is set to
  81    * @c EBUSY.
  82    */
  83   int tryacquire ();
  84
  85   /// Increment the semaphore by 1, potentially unblocking a waiting
  86   /// thread.
  87   int release ();
  88
  89   /// Increment the semaphore by @a release_count, potentially
  90   /// unblocking waiting threads.
  91   int release (unsigned int release_count);
  92
  93   /**
  94    * Acquire semaphore ownership.  This calls <acquire> and is only
  95    * here to make the ACE_Semaphore interface consistent with the
  96    * other synchronization APIs.
  97    */
  98   int acquire_read ();
  99
 100   /**
 101    * Acquire semaphore ownership.  This calls <acquire> and is only
 102    * here to make the ACE_Semaphore interface consistent with the
 103    * other synchronization APIs.
 104    */
 105   int acquire_write ();
 106
 107   /**
 108    * Conditionally acquire semaphore (i.e., won't block).  This calls
 109    * <tryacquire> and is only here to make the ACE_Semaphore
 110    * interface consistent with the other synchronization APIs.
 111    * Returns -1 on failure.  If we "failed" because someone else
 112    * already had the lock, @c errno is set to @c EBUSY.
 113    */
 114   int tryacquire_read ();
 115
 116   /**
 117    * Conditionally acquire semaphore (i.e., won't block).  This calls
 118    * <tryacquire> and is only here to make the ACE_Semaphore
 119    * interface consistent with the other synchronization APIs.
 120    * Returns -1 on failure.  If we "failed" because someone else
 121    * already had the lock, @c errno is set to @c EBUSY.
 122    */
 123   int tryacquire_write ();
 124
 125   /**
 126    * This is only here to make the ACE_Semaphore
 127    * interface consistent with the other synchronization APIs.
 128    * Assumes the caller has already acquired the semaphore using one of
 129    * the above calls, and returns 0 (success) always.
 130    */
 131   int tryacquire_write_upgrade ();
 132
 133   /// Dump the state of an object.
 134   void dump () const;
 135
 136   /// Declare the dynamic allocation hooks.
 137   ACE_ALLOC_HOOK_DECLARE;
 138
 139   /// Return the underlying lock.
 140   const ACE_sema_t &lock () const;
 141
 142 protected:
 143   ACE_sema_t semaphore_;
 144
 145   /// Keeps track of whether remove() has been called yet to avoid
 146   /// multiple remove() calls, e.g., explicitly and implicitly in the
 147   /// destructor.  This flag isn't protected by a lock, so make sure
 148   /// that you don't have multiple threads simultaneously calling
 149   /// remove () on the same object, which is a bad idea anyway...
 150   bool removed_;
 151
 152 private:
 153   void operator= (const ACE_Semaphore &) = delete;
 154   ACE_Semaphore (const ACE_Semaphore &) = delete;
 155 };
 156
 157 ACE_END_VERSIONED_NAMESPACE_DECL
 158
 159 #if defined (__ACE_INLINE__)
 160 #include "ace/Semaphore.inl"
 161 #endif /* __ACE_INLINE__ */
 162
 163 #include /**/ "ace/post.h"
 164 #endif /* ACE_SEMAPHORE_H */