ACE/ace/RW_Mutex.h

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