dep/ACE_wrappers/ace/Semaphore.h

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