ACE/ace/Semaphore.h

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