ACE/ace/RW_Process_Mutex.h

   1 // -*- C++ -*-
   2 //
   3 //=============================================================================
   4 /**
   5  *  @file    RW_Process_Mutex.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_RW_PROCESS_MUTEX_H
  12 #define ACE_RW_PROCESS_MUTEX_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include "ace/File_Lock.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include "ace/Default_Constants.h"
  23
  24 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  25
  26 /**
  27  * @class ACE_RW_Process_Mutex
  28  *
  29  * @brief Wrapper for readers/writer locks that exist across processes.
  30  *
  31  * @note This class uses an ACE_File_Lock as its implementation. Thus, it
  32  * can only be reliably used between separate processes, rather than
  33  * threads in the same process.  This isn't a limitation of ACE, it's simply
  34  * the file lock semantics on UNIX and Win32.
  35  *
  36  * @todo For systems with pthread_rwlockattr_setpshared one
  37  * may consider using them to make the mutex faster.
  38  */
  39 class ACE_Export ACE_RW_Process_Mutex
  40 {
  41 public:
  42   /// Create a cross-process readers/writer mutex, passing in the optional
  43   /// @a name, @a flags and @a mode \sa ACE_File_Lock.
  44   /// If not specified, a name is generated and flags and mode are set
  45   /// to default platform values.
  46   ACE_RW_Process_Mutex (const ACE_TCHAR *name = 0,
  47                         int flags = O_CREAT|O_RDWR,
  48                         mode_t mode =  ACE_DEFAULT_RW_PROCESS_MUTEX_PERMS);
  49
  50   ~ACE_RW_Process_Mutex (void);
  51
  52   /**
  53    * Explicitly destroy the mutex.  Note that only one thread should
  54    * call this method since it doesn't protect against race
  55    * conditions.
  56    */
  57   int remove (void);
  58
  59   /// Same as acquire_write().
  60   /// Acquire lock ownership; blocks until the lock is acquired or the
  61   /// operation fails.
  62   int acquire (void);
  63
  64   /**
  65    * Same as tryacquire_write().
  66    * Try to acquire the lock, but do not block if the lock is not immediately
  67    * acquired.
  68    *
  69    * @retval -1 on failure. If the lock is already held, @c errno is set
  70    *         to @c EBUSY.
  71    */
  72   int tryacquire (void);
  73
  74   /// Release lock.
  75   int release (void);
  76
  77   /// Acquire read lock; blocks until the lock is acquired or the
  78   /// operation fails.
  79   int acquire_read (void);
  80
  81   /// Acquire write lock; blocks until the lock is acquired or the
  82   /// operation fails.
  83   int acquire_write (void);
  84
  85   /**
  86    * Try to acquire the read lock, but do not block if the lock is not
  87    * immediately acquired.
  88    *
  89    * @retval -1 on failure. If the lock is already held, @c errno is set
  90    *         to @c EBUSY.
  91    */
  92   int tryacquire_read (void);
  93
  94   /**
  95    * Try to acquire the write lock, but do not block if the lock is not
  96    * immediately acquired.
  97    *
  98    * @retval -1 on failure. If the lock is already held, @c errno is set
  99    *         to @c EBUSY.
 100    */
 101   int tryacquire_write (void);
 102
 103   /// Attempt to upgrade a read lock to a write lock. Returns 0 on
 104   /// success, -1 on failure.
 105   int tryacquire_write_upgrade (void);
 106
 107   /// Return the underlying lock.
 108   const ACE_File_Lock &lock (void) const;
 109
 110   /// Dump the state of an object.
 111   void dump () const;
 112
 113   /// Declare the dynamic allocation hooks.
 114   ACE_ALLOC_HOOK_DECLARE;
 115
 116 private:
 117   /// If the user does not provide a name we generate a unique name in
 118   /// this buffer.
 119   ACE_TCHAR name_[ACE_UNIQUE_NAME_LEN];
 120
 121   /// Create and return the unique name.
 122   const ACE_TCHAR *unique_name (void);
 123
 124   /// We need this to get the readers/writer semantics...
 125   ACE_File_Lock lock_;
 126 };
 127
 128 ACE_END_VERSIONED_NAMESPACE_DECL
 129
 130 #if defined (__ACE_INLINE__)
 131 #include "ace/RW_Process_Mutex.inl"
 132 #endif /* __ACE_INLINE__ */
 133
 134 #include /**/ "ace/post.h"
 135 #endif /* ACE_RW_PROCESS_MUTEX_H */