Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

Process_Mutex.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    Process_Mutex.h
00006  *
00007  *  $Id: Process_Mutex.h,v 1.1.1.2 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *   A wrapper for mutexes that can be used across processes on the
00010  *   same host machine, as well as within a process, of course.
00011  *
00012  * @author Douglas C. Schmidt <schmidt@uci.edu>
00013  */
00014 //=============================================================================
00015 
00016 #ifndef ACE_PROCESS_MUTEX_H
00017 #define ACE_PROCESS_MUTEX_H
00018 
00019 #include "ace/pre.h"
00020 
00021 #include "ace/config-all.h"
00022 
00023 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00024 # pragma once
00025 #endif /* ACE_LACKS_PRAGMA_ONCE */
00026 
00027 // To make it easier to carry the setting though this file as well as
00028 // Process_Mutex.{cpp inl}, set a private macro here.
00029 #ifdef _ACE_USE_SV_SEM
00030 #  undef _ACE_USE_SV_SEM
00031 #endif /* _ACE_USE_SV_SEM */
00032 #if defined (ACE_HAS_SYSV_IPC) && !defined (ACE_USES_MUTEX_FOR_PROCESS_MUTEX)
00033 #  include "ace/SV_Semaphore_Complex.h"
00034 #  define _ACE_USE_SV_SEM
00035 #else
00036 #  include "ace/Synch.h"
00037 #endif /* ACE_HAS_SYSV_IPC && !ACE_USES_MUTEX_FOR_PROCESS_MUTEX */
00038 
00039 /**
00040  * @class ACE_Process_Mutex
00041  *
00042  * @brief A wrapper for mutexes that can be used across processes on
00043  * the same host machine, as well as within a process, of
00044  * course.
00045  *
00046  * @attention The mechanism upon which @c ACE_Process_Mutex is based
00047  * can be configured at build time to be either @c ACE_SV_Semaphore_Complex
00048  * (on platforms that support it) or @c ACE_Mutex. On platforms that
00049  * require interprocess mutexes be allocated from shared memory (Pthreads
00050  * and UI Threads are examples), @c ACE_SV_Semaphore_Complex provides a
00051  * more reliable mechanism for implementing inter-process mutex than
00052  * @c ACE_Mutex. However, at least on some platforms,
00053  * @c ACE_SV_Semaphore_Complex is limited to a small number of
00054  * objects by the underlying System V IPC kernel parameters. If you
00055  * want to force use of @c ACE_Mutex as the underlying mechanism, set
00056  * @c ACE_USES_MUTEX_FOR_PROCESS_MUTEX in your @c config.h file.
00057  * Also, if you require the ability to do a timed @c acquire(), you must
00058  * set @c ACE_USES_MUTEX_FOR_PROCESS_MUTEX, as timed acquire does not
00059  * work with System V semaphores.
00060  */
00061 class ACE_Export ACE_Process_Mutex
00062 {
00063 public:
00064   /**
00065    * Create a Process_Mutex, passing in the optional @c name.
00066    *
00067    * @param name optional, null-terminated string containing the name of
00068    * the object. Multiple users of the same @c ACE_Process_Mutex must use
00069    * the same name to access the same object.  If not specified, a name
00070    * is generated.
00071    * @param arg optional, attributes to be used to initialize the mutex.
00072    * If using @c ACE_SV_Semaphore_Complex as the underlying mechanism,
00073    * this argument is ignored.
00074    * @param mode optional, the protection mode for either the backing store
00075    * file (for ACE_Mutex use) or the ACE_SV_Semaphore_Complex that's created.
00076    */
00077   ACE_Process_Mutex (const char *name = 0,
00078                      void *arg = 0,
00079                      mode_t mode = ACE_DEFAULT_FILE_PERMS);
00080 
00081 #if defined (ACE_HAS_WCHAR)
00082   /**
00083    * Create a Process_Mutex, passing in the optional @c name. (@c wchar_t
00084    * version)
00085    *
00086    * @param name optional, null-terminated string containing the name of
00087    * the object. Multiple users of the same @c ACE_Process_Mutex must use
00088    * the same name to access the same object. If not specified, a name
00089    * is generated.
00090    * @param arg optional, attributes to be used to initialize the mutex.
00091    * If using @c ACE_SV_Semaphore_Complex as the underlying mechanism,
00092    * this argument is ignored.
00093    * @param mode optional, the protection mode for either the backing store
00094    * file (for ACE_Mutex use) or the ACE_SV_Semaphore_Complex that's created.
00095    */
00096   ACE_Process_Mutex (const wchar_t *name,
00097                      void *arg = 0,
00098                      mode_t mode = ACE_DEFAULT_FILE_PERMS);
00099 #endif /* ACE_HAS_WCHAR */
00100 
00101   ~ACE_Process_Mutex (void);
00102 
00103   /**
00104    * Explicitly destroy the mutex.  Note that only one thread should
00105    * call this method since it doesn't protect against race
00106    * conditions.
00107    *
00108    * @return 0 on success; -1 on failure.
00109    */
00110   int remove (void);
00111 
00112   /**
00113    * Acquire lock ownership (wait on queue if necessary).
00114    *
00115    * @return 0 on success; -1 on failure.
00116    */
00117   int acquire (void);
00118 
00119   /**
00120    * Acquire lock ownership, but timeout if lock if hasn't been
00121    * acquired by given time.
00122    *
00123    * @param tv the absolute time until which the caller is willing to
00124    * wait to acquire the lock.
00125    *
00126    * @return 0 on success; -1 on failure.
00127    */
00128   int acquire (ACE_Time_Value &tv);
00129 
00130   /**
00131    * Conditionally acquire lock (i.e., don't wait on queue).
00132    *
00133    * @return 0 on success; -1 on failure.  If the lock could not be acquired
00134    * because someone else already had the lock, @c errno is set to @c EBUSY.
00135    */
00136   int tryacquire (void);
00137 
00138   /// Release lock and unblock a thread at head of queue.
00139   int release (void);
00140 
00141   /// Acquire lock ownership (wait on queue if necessary).
00142   int acquire_read (void);
00143 
00144   /// Acquire lock ownership (wait on queue if necessary).
00145   int acquire_write (void);
00146 
00147   /**
00148    * Conditionally acquire a lock (i.e., won't block).  Returns -1 on
00149    * failure.  If we "failed" because someone else already had the
00150    * lock, <errno> is set to <EBUSY>.
00151    */
00152   int tryacquire_read (void);
00153 
00154   /**
00155    * Conditionally acquire a lock (i.e., won't block).  Returns -1 on
00156    * failure.  If we "failed" because someone else already had the
00157    * lock, <errno> is set to <EBUSY>.
00158    */
00159   int tryacquire_write (void);
00160 
00161   /**
00162    * This is only here for consistency with the other synchronization
00163    * APIs and usability with Lock adapters. Assumes the caller already has
00164    * acquired the mutex and returns 0 in all cases.
00165    */
00166   int tryacquire_write_upgrade (void);
00167 
00168 #if !defined (_ACE_USE_SV_SEM)
00169   /// Return the underlying mutex.
00170   const ACE_mutex_t &lock (void) const;
00171 #endif /* !_ACE_USE_SV_SEM */
00172 
00173   /// Dump the state of an object.
00174   void dump (void) const;
00175 
00176   /// Declare the dynamic allocation hooks.
00177   ACE_ALLOC_HOOK_DECLARE;
00178 
00179 private:
00180   /// If the user does not provide a name we generate a unique name in
00181   /// this buffer.
00182   ACE_TCHAR name_[ACE_UNIQUE_NAME_LEN];
00183 
00184   /// Create and return the unique name.
00185   const ACE_TCHAR *unique_name (void);
00186 
00187 #if defined (_ACE_USE_SV_SEM)
00188   /// We need this to get the right semantics...
00189   ACE_SV_Semaphore_Complex lock_;
00190 #else
00191   ACE_Mutex lock_;
00192 #endif /* _ACE_USE_SV_SEM */
00193 };
00194 
00195 #if defined (__ACE_INLINE__)
00196 #include "ace/Process_Mutex.inl"
00197 #endif /* __ACE_INLINE__ */
00198 
00199 #include "ace/post.h"
00200 
00201 #endif /* ACE_PROCESS_MUTEX_H */

Generated on Mon Jun 16 11:20:56 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002