ACE/ace/RW_Mutex.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    RW_Mutex.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //==========================================================================
  10
  11 #ifndef ACE_RW_MUTEX_H
  12 #define ACE_RW_MUTEX_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "ace/ACE_export.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 // ACE platform supports some form of threading.
  23 #if defined (ACE_HAS_THREADS)
  24
  25 #include "ace/OS_NS_Thread.h"
  26
  27 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  28
  29 /**
  30  * @class ACE_RW_Mutex
  31  *
  32  * @brief Wrapper for readers/writer locks.
  33  *
  34  * These are most useful for applications that have many more
  35  * parallel readers than writers...
  36  */
  37 class ACE_Export ACE_RW_Mutex
  38 {
  39 public:
  40   /// Initialize a readers/writer lock.
  41   ACE_RW_Mutex (int type = USYNC_THREAD,
  42                 const ACE_TCHAR *name = 0,
  43                 void *arg = 0);
  44
  45   /// Implicitly destroy a readers/writer lock
  46   ~ACE_RW_Mutex ();
  47
  48   /**
  49    * Explicitly destroy a readers/writer lock.  Note that only one
  50    * thread should call this method since it doesn't protect against
  51    * race conditions.
  52    */
  53   int remove ();
  54
  55   /// Acquire a read lock, but block if a writer hold the lock.
  56   int acquire_read ();
  57
  58   /// Acquire a write lock, but block if any readers or a
  59   /// writer hold the lock.
  60   int acquire_write ();
  61
  62   /**
  63    * Conditionally acquire a read lock (i.e., won't block).  Returns
  64    * -1 on failure.  If we "failed" because someone else already had
  65    * the lock, @c errno is set to @c EBUSY.
  66    */
  67   int tryacquire_read ();
  68
  69   /// Conditionally acquire a write lock (i.e., won't block).
  70   int tryacquire_write ();
  71
  72   /**
  73    * Conditionally upgrade a read lock to a write lock.  This only
  74    * works if there are no other readers present, in which case the
  75    * method returns 0.  Otherwise, the method returns -1 and sets
  76    * @c errno to @c EBUSY.  Note that the caller of this method *must*
  77    * already possess this lock as a read lock (but this condition is
  78    * not checked by the current implementation).
  79    */
  80   int tryacquire_write_upgrade ();
  81
  82   /**
  83    * Note, for interface uniformity with other synchronization
  84    * wrappers we include the <acquire> method.  This is implemented as
  85    * a write-lock to safe...
  86    */
  87   int acquire ();
  88
  89   /**
  90    * Note, for interface uniformity with other synchronization
  91    * wrappers we include the tryacquire() method.  This is implemented
  92    * as a write-lock to be safe...  Returns -1 on failure.  If we
  93    * "failed" because someone else already had the lock, @c errno is
  94    * set to @c EBUSY.
  95    */
  96   int tryacquire ();
  97
  98   /// Unlock a readers/writer lock.
  99   int release ();
 100
 101   /// Return the underlying lock.
 102   const ACE_rwlock_t &lock () const;
 103
 104   /// Dump the state of an object.
 105   void dump () const;
 106
 107   /// Declare the dynamic allocation hooks.
 108   ACE_ALLOC_HOOK_DECLARE;
 109
 110 protected:
 111   /// Readers/writer lock.
 112   ACE_rwlock_t lock_;
 113
 114   /// Keeps track of whether remove() has been called yet to avoid
 115   /// multiple remove() calls, e.g., explicitly and implicitly in the
 116   /// destructor. This flag isn't protected by a lock, so make sure
 117   /// that you don't have multiple threads simultaneously calling
 118   /// remove() on the same object, which is a bad idea anyway...
 119   bool removed_;
 120
 121 private:
 122   void operator= (const ACE_RW_Mutex &) = delete;
 123   ACE_RW_Mutex (const ACE_RW_Mutex &) = delete;
 124 };
 125
 126 ACE_END_VERSIONED_NAMESPACE_DECL
 127
 128 #if defined (__ACE_INLINE__)
 129 #include "ace/RW_Mutex.inl"
 130 #endif /* __ACE_INLINE__ */
 131
 132 #endif /* ACE_HAS_THREADS */
 133
 134 #include /**/ "ace/post.h"
 135
 136 #endif /* ACE_RW_MUTEX_H */