ACE/ace/Process_Semaphore.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Process_Semaphore.h
   6  *
   7  *   Wrapper for Dijkstra style general semaphores that work
   8  *   across processes.
   9  *
  10  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
  11  */
  12 //=============================================================================
  13
  14 #ifndef ACE_PROCESS_SEMAPHORE_H
  15 #define ACE_PROCESS_SEMAPHORE_H
  16
  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 #if !(defined (ACE_WIN32) || defined (ACE_HAS_POSIX_SEM))
  26 # include "ace/SV_Semaphore_Complex.h"
  27 #else
  28 # include "ace/Semaphore.h"
  29 #endif /* !(ACE_WIN32 || ACE_HAS_POSIX_SEM) */
  30
  31 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  32
  33 /**
  34  * @class ACE_Process_Semaphore
  35  *
  36  * @brief Wrapper for Dijkstra style general semaphores that work
  37  * across processes.
  38  */
  39 class ACE_Export ACE_Process_Semaphore
  40 {
  41 public:
  42   /// Initialize the semaphore, with an initial value of @a count and a
  43   /// maximum value of @a max.
  44   ACE_Process_Semaphore (u_int count = 1, // By default make this unlocked.
  45                          const ACE_TCHAR *name = 0,
  46                          void * = 0,
  47                          int max = 0x7FFFFFFF);
  48
  49   /**
  50    * Explicitly destroy the semaphore.  Note that only one thread
  51    * should call this method since it doesn't protect against race
  52    * conditions.
  53    */
  54   int remove ();
  55
  56   /// Block the thread until the semaphore count becomes greater than
  57   /// 0, then decrement it.
  58   int acquire ();
  59
  60   /**
  61    * Conditionally decrement the semaphore if count is greater than 0
  62    * (i.e., won't block).  Returns -1 on failure.  If we "failed"
  63    * because someone else already had the lock, @c errno is set to
  64    * @c EBUSY.
  65    */
  66   int tryacquire ();
  67
  68   /// Increment the semaphore, potentially unblocking a waiting thread.
  69   int release ();
  70
  71   /**
  72    * Acquire semaphore ownership.  This calls acquire() and is only
  73    * here to make the ACE_Process_Semaphore interface consistent
  74    * with the other synchronization APIs.
  75    */
  76   int acquire_read ();
  77
  78   /**
  79    * Acquire semaphore ownership.  This calls acquire() and is only
  80    * here to make the ACE_Process_Semaphore interface consistent
  81    * with the other synchronization APIs.
  82    */
  83   int acquire_write ();
  84
  85   /**
  86    * Conditionally acquire semaphore (i.e., won't block).  This calls
  87    * tryacquire() and is only here to make the ACE_Process_Semaphore
  88    * interface consistent with the other synchronization APIs.
  89    * Returns -1 on failure.  If we "failed" because someone else
  90    * already had the lock, @c errno is set to @c EBUSY.
  91    */
  92   int tryacquire_read ();
  93
  94   /**
  95    * Conditionally acquire semaphore (i.e., won't block).  This calls
  96    * tryacquire() and is only here to make the ACE_Process_Semaphore
  97    * interface consistent with the other synchronization APIs.
  98    * Returns -1 on failure.  If we "failed" because someone else
  99    * already had the lock, @c errno is set to @c EBUSY.
 100    */
 101   int tryacquire_write ();
 102
 103   /**
 104    * This is only here to make the ACE_Process_Semaphore
 105    * interface consistent with the other synchronization APIs.
 106    * Assumes the caller has already acquired the semaphore using one of
 107    * the above calls, and returns 0 (success) always.
 108    */
 109   int tryacquire_write_upgrade ();
 110
 111 #if defined (ACE_WIN32) || defined (ACE_HAS_POSIX_SEM)
 112   /// Return the underlying lock.
 113   const ACE_sema_t &lock () const;
 114 #endif /* ACE_WIN32 || ACE_HAS_POSIX_SEM */
 115
 116   /// Dump the state of an object.
 117   void dump () const;
 118
 119   /// Declare the dynamic allocation hooks.
 120   ACE_ALLOC_HOOK_DECLARE;
 121
 122 protected:
 123 #if defined (ACE_WIN32) || defined (ACE_HAS_POSIX_SEM)
 124   ACE_Semaphore lock_;
 125 #else
 126   /// We need this to get the right semantics...
 127   ACE_SV_Semaphore_Complex lock_;
 128 #endif /* ACE_WIN32 || ACE_HAS_POSIX_SEM */
 129 };
 130
 131 /*****************************************************************************/
 132
 133 template <class T> class ACE_Malloc_Lock_Adapter_T;
 134
 135 /**
 136  * @brief Template specialization of ACE_Malloc_Lock_Adapter_T for
 137  * ACE_Process_Semaphore.
 138  *
 139  * This is needed since the constructor for ACE_Process_Semaphore doesn't match
 140  * the standard form used by other lock strategy classes.
 141  */
 142 template<>
 143 class ACE_Export ACE_Malloc_Lock_Adapter_T<ACE_Process_Semaphore>
 144 {
 145 public:
 146   ACE_Process_Semaphore * operator () (const ACE_TCHAR *name);
 147 };
 148
 149 ACE_END_VERSIONED_NAMESPACE_DECL
 150
 151 #if defined (__ACE_INLINE__)
 152 #include "ace/Process_Semaphore.inl"
 153 #endif /* __ACE_INLINE__ */
 154
 155 #include /**/ "ace/post.h"
 156 #endif /* ACE_PROCESS_SEMAPHORE_H */