00001 // -*- C++ -*- 00002 00003 //========================================================================== 00004 /** 00005 * @file Mutex.h 00006 * 00007 * $Id: Mutex.h 80826 2008-03-04 14:51:23Z wotte $ 00008 * 00009 * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> 00010 */ 00011 //========================================================================== 00012 00013 #ifndef ACE_MUTEX_H 00014 #define ACE_MUTEX_H 00015 00016 #include /**/ "ace/pre.h" 00017 00018 #include /**/ "ace/ACE_export.h" 00019 00020 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00021 # pragma once 00022 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00023 00024 #include "ace/OS_NS_Thread.h" 00025 #include "ace/OS_NS_unistd.h" 00026 #include "ace/os_include/os_fcntl.h" 00027 00028 # if !defined (ACE_DEFAULT_MUTEX_A) 00029 # define ACE_DEFAULT_MUTEX_A "ACE_MUTEX" 00030 # endif /* ACE_DEFAULT_MUTEX_A */ 00031 00032 # if defined (ACE_HAS_WCHAR) 00033 # define ACE_DEFAULT_MUTEX_W ACE_TEXT_WIDE(ACE_DEFAULT_MUTEX_A) 00034 # endif /* ACE_HAS_WCHAR */ 00035 00036 # define ACE_DEFAULT_MUTEX ACE_TEXT (ACE_DEFAULT_MUTEX_A) 00037 00038 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00039 00040 class ACE_Time_Value; 00041 00042 /** 00043 * @class ACE_Mutex 00044 * 00045 * @brief @c ACE_Mutex wrapper (valid in same process or across 00046 * processes (depending on @a TYPE flag)). In general, 00047 * however, we recommend using @a ACE_Process_Mutex or @a 00048 * ACE_Thread_Mutex rather than @a ACE_Mutex. 00049 */ 00050 class ACE_Export ACE_Mutex 00051 { 00052 public: 00053 /// Initialize the mutex. 00054 ACE_Mutex (int type = USYNC_THREAD, 00055 const ACE_TCHAR *name = 0, 00056 ACE_mutexattr_t *arg = 0, 00057 mode_t mode = ACE_DEFAULT_FILE_PERMS); 00058 00059 /// Implicitly destroy the mutex. 00060 ~ACE_Mutex (void); 00061 00062 /// Explicitly destroy the mutex. 00063 /** 00064 * @note Only one thread should call this method since it doesn't 00065 * protect against race conditions. 00066 */ 00067 int remove (void); 00068 00069 /// Acquire lock ownership (wait on queue if necessary). 00070 int acquire (void); 00071 00072 /// Block the thread until the mutex is acquired or @a tv times out, 00073 /// in which case -1 is returned and @c errno == @c ETIME. 00074 /** 00075 * @note @a tv is assumed to be in "absolute" rather than 00076 * " relative" time. The value of @a tv is updated upon return 00077 * to show the actual(absolute) acquisition time. 00078 */ 00079 int acquire (ACE_Time_Value &tv); 00080 00081 /// Block the thread until the mutex is acquired or @a *tv times 00082 /// out, in which case -1 is returned and @c errno == @c ETIME. 00083 /** 00084 * If @a tv == 0 then call @c acquire() directly. Otherwise, block 00085 * the thread until the mutex is acquired or @a tv times out, in 00086 * which case -1 is returned and @c errno == @c ETIME. 00087 * 00088 * @note @a *tv is assumed to be in "absolute" rather than 00089 * "relative" time. The value of @a *tv is updated upon 00090 * return to show the actual (absolute) acquisition time. 00091 */ 00092 int acquire (ACE_Time_Value *tv); 00093 00094 /// Conditionally acquire lock (i.e., don't wait on queue). 00095 /** 00096 * @return -1 on failure. If we "failed" because someone 00097 * else already had the lock, @c errno is set to @c EBUSY. 00098 */ 00099 int tryacquire (void); 00100 00101 /// Release lock and unblock a thread at head of queue. 00102 int release (void); 00103 00104 /// Acquire mutex ownership. 00105 /** 00106 * This calls @c acquire and is only here to make the @c ACE_Mutex 00107 * interface consistent with the other synchronization APIs. 00108 */ 00109 int acquire_read (void); 00110 00111 /// Acquire mutex ownership. 00112 /** 00113 * This calls @c acquire and is only here to make the @c ACE_Mutex 00114 * interface consistent with the other synchronization APIs. 00115 */ 00116 int acquire_write (void); 00117 00118 /// Conditionally acquire mutex (i.e., won't block). 00119 /** 00120 * This calls @c tryacquire and is only here to make the @c ACE_Mutex 00121 * interface consistent with the other synchronization APIs. 00122 * 00123 * @return -1 on failure. If we "failed" because someone else 00124 * already had the lock, @c errno is set to @c EBUSY. 00125 */ 00126 int tryacquire_read (void); 00127 00128 /// Conditionally acquire mutex (i.e., won't block). 00129 /** 00130 * This calls @c tryacquire and is only here to make the @c ACE_Mutex 00131 * interface consistent with the other synchronization APIs. 00132 * 00133 * @return -1 on failure. If we "failed" because someone else 00134 * already had the lock, @c errno is set to @c EBUSY. 00135 */ 00136 int tryacquire_write (void); 00137 00138 /** 00139 * This is only here for consistency with the other synchronization 00140 * APIs and usability with Lock adapters. Assumes the caller already has 00141 * acquired the mutex and returns 0 in all cases. 00142 */ 00143 int tryacquire_write_upgrade (void); 00144 00145 /// Return the underlying mutex. 00146 const ACE_mutex_t &lock (void) const; 00147 00148 /// Dump the state of an object. 00149 void dump (void) const; 00150 00151 /// Declare the dynamic allocation hooks. 00152 ACE_ALLOC_HOOK_DECLARE; 00153 00154 // = This should be protected but some C++ compilers complain... 00155 public: 00156 #if defined (ACE_HAS_PTHREADS) || defined(ACE_HAS_STHREADS) 00157 /// This lock resides in shared memory. 00158 ACE_mutex_t *process_lock_; 00159 00160 /** 00161 * Remember the name of the mutex if we created it so we can unlink 00162 * it when we go away (only the actor that initialized the memory 00163 * can destroy it). 00164 */ 00165 const ACE_TCHAR *lockname_; 00166 #endif /* ACE_HAS_PTHREADS */ 00167 00168 /// Mutex type supported by the OS. 00169 ACE_mutex_t lock_; 00170 00171 /// Keeps track of whether @c remove has been called yet to avoid 00172 /// multiple @c remove calls, e.g., explicitly and implicitly in the 00173 /// destructor. This flag isn't protected by a lock, so make sure 00174 /// that you don't have multiple threads simultaneously calling 00175 /// @c remove on the same object, which is a bad idea anyway. 00176 bool removed_; 00177 00178 private: 00179 // Prevent assignment and initialization. 00180 void operator= (const ACE_Mutex &); 00181 ACE_Mutex (const ACE_Mutex &); 00182 }; 00183 00184 ACE_END_VERSIONED_NAMESPACE_DECL 00185 00186 #if defined (__ACE_INLINE__) 00187 #include "ace/Mutex.inl" 00188 #endif /* __ACE_INLINE__ */ 00189 00190 #include /**/ "ace/post.h" 00191 00192 #endif /* ACE_MUTEX_H */