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

ACE_Mutex Class Reference

<ACE_Mutex> wrapper (valid in same process or across processes (depending on TYPE flag)). More...

#include <Synch.h>

List of all members.

Public Methods

 ACE_Mutex (int type=USYNC_THREAD, const ACE_TCHAR *name=0, ACE_mutexattr_t *arg=0, mode_t mode=ACE_DEFAULT_FILE_PERMS)
 Initialize the mutex. More...

 ~ACE_Mutex (void)
 Implicitly destroy the mutex. More...

int remove (void)
int acquire (void)
 Acquire lock ownership (wait on queue if necessary). More...

int acquire (ACE_Time_Value &tv)
int acquire (ACE_Time_Value *tv)
int tryacquire (void)
int release (void)
 Release lock and unblock a thread at head of queue. More...

int acquire_read (void)
int acquire_write (void)
int tryacquire_read (void)
int tryacquire_write (void)
int tryacquire_write_upgrade (void)
const ACE_mutex_t & lock (void) const
 Return the underlying mutex. More...

void dump (void) const
 Dump the state of an object. More...


Public Attributes

 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks. More...

ACE_mutex_t lock_
 Mutex type supported by the OS. More...

int removed_
 Keeps track of whether <remove> has been called yet to avoid multiple <remove> calls, e.g., explicitly and implicitly in the destructor. This flag isn't protected by a lock, so make sure that you don't have multiple threads simultaneously calling <remove> on the same object, which is a bad idea anyway... More...


Private Methods

void operator= (const ACE_Mutex &)
 ACE_Mutex (const ACE_Mutex &)


Detailed Description

<ACE_Mutex> wrapper (valid in same process or across processes (depending on TYPE flag)).

Definition at line 473 of file Synch.h.


Constructor & Destructor Documentation

ACE_Mutex::ACE_Mutex int    type = USYNC_THREAD,
const ACE_TCHAR   name = 0,
ACE_mutexattr_t *    arg = 0,
mode_t    mode = ACE_DEFAULT_FILE_PERMS
 

Initialize the mutex.

Definition at line 189 of file Synch.cpp.

References ACE_ERROR, ACE_LIB_TEXT, ACE_TCHAR, ACE_OS::close, ACE_OS::ftruncate, LM_ERROR, MAP_FAILED, MAP_SHARED, ACE_OS::mmap, mode_t, ACE_OS::mutex_init, PROT_RDWR, ACE_OS::shm_open, and ACE_OS_String::strdup.

00191   :
00192 #if defined (CHORUS) || defined (ACE_HAS_PTHREADS) || defined(ACE_HAS_STHREADS)
00193     process_lock_ (0),
00194     lockname_ (0),
00195 #endif /* CHORUS */
00196     removed_ (0)
00197 {
00198   // ACE_TRACE ("ACE_Mutex::ACE_Mutex");
00199 
00200   // These platforms need process-wide mutex to be in shared memory.
00201 #if defined (CHORUS) || defined(ACE_HAS_PTHREADS) || defined (ACE_HAS_STHREADS)
00202   if (type == USYNC_PROCESS)
00203     {
00204       // Let's see if the shared memory entity already exists.
00205       ACE_HANDLE fd = ACE_OS::shm_open (name, O_RDWR | O_CREAT | O_EXCL, mode);
00206       if (fd == ACE_INVALID_HANDLE)
00207         {
00208           if (errno == EEXIST)
00209             fd = ACE_OS::shm_open (name, O_RDWR | O_CREAT, mode);
00210           else
00211             return;
00212         }
00213       else
00214         {
00215           // We own this shared memory object!  Let's set its size.
00216           if (ACE_OS::ftruncate (fd,
00217                                  sizeof (ACE_mutex_t)) == -1)
00218             {
00219               ACE_OS::close (fd);
00220               return;
00221             }
00222           this->lockname_ = ACE_OS::strdup (name);
00223           if (this->lockname_ == 0)
00224             {
00225               ACE_OS::close (fd);
00226               return;
00227             }
00228         }
00229 
00230       this->process_lock_ =
00231         (ACE_mutex_t *) ACE_OS::mmap (0,
00232                                       sizeof (ACE_mutex_t),
00233                                       PROT_RDWR,
00234                                       MAP_SHARED,
00235                                       fd,
00236                                       0);
00237       ACE_OS::close (fd);
00238       if (this->process_lock_ == MAP_FAILED)
00239         return;
00240 
00241       if (this->lockname_
00242           && ACE_OS::mutex_init (this->process_lock_,
00243                                  type,
00244                                  name,
00245                                  arg) != 0)
00246         return;
00247     }
00248    // It is ok to fall through into the <mutex_init> below if the
00249    // USYNC_PROCESS flag is not enabled.
00250 #else
00251   ACE_UNUSED_ARG (mode);
00252 #endif /* CHORUS */
00253 
00254   if (ACE_OS::mutex_init (&this->lock_,
00255                           type,
00256                           name,
00257                           arg) != 0)
00258     ACE_ERROR ((LM_ERROR,
00259                 ACE_LIB_TEXT ("%p\n"),
00260                 ACE_LIB_TEXT ("ACE_Mutex::ACE_Mutex")));
00261 }

ACE_Mutex::~ACE_Mutex void   
 

Implicitly destroy the mutex.

Definition at line 263 of file Synch.cpp.

References remove.

00264 {
00265 // ACE_TRACE ("ACE_Mutex::~ACE_Mutex");
00266   this->remove ();
00267 }

ACE_Mutex::ACE_Mutex const ACE_Mutex &    [private]
 


Member Function Documentation

ACE_INLINE int ACE_Mutex::acquire ACE_Time_Value   tv
 

If <tv> == 0 then call <acquire()> directly. Otherwise, block the thread until the mutex is acquired or <tv> times out, in which case -1 is returned and <errno> == <ETIME>. Note that <*tv> is assumed to be in "absolute" rather than "relative" time. The value of <*tv> is updated upon return to show the actual (absolute) acquisition time.

Definition at line 175 of file Synch.i.

References ACE_OS::mutex_lock.

00176 {
00177   // ACE_TRACE ("ACE_Mutex::acquire");
00178   return ACE_OS::mutex_lock (&this->lock_, tv);
00179 }

ACE_INLINE int ACE_Mutex::acquire ACE_Time_Value   tv
 

Block the thread until the mutex is acquired or <tv> times out, in which case -1 is returned and <errno> == <ETIME>. Note that <tv> is assumed to be in "absolute" rather than "relative" time. The value of <tv> is updated upon return to show the actual (absolute) acquisition time.

Definition at line 168 of file Synch.i.

References ACE_OS::mutex_lock.

00169 {
00170   // ACE_TRACE ("ACE_Mutex::acquire");
00171   return ACE_OS::mutex_lock (&this->lock_, tv);
00172 }

ACE_INLINE int ACE_Mutex::acquire void   
 

Acquire lock ownership (wait on queue if necessary).

Definition at line 157 of file Synch.i.

References ACE_OS::mutex_lock.

Referenced by ACE_Process_Mutex::acquire.

00158 {
00159 // ACE_TRACE ("ACE_Mutex::acquire");
00160 #if defined (CHORUS)
00161    if (this->process_lock_)
00162      return ACE_OS::mutex_lock (this->process_lock_);
00163 #endif /* CHORUS */
00164   return ACE_OS::mutex_lock (&this->lock_);
00165 }

ACE_INLINE int ACE_Mutex::acquire_read void   
 

Acquire mutex ownership. This calls <acquire> and is only here to make the <ACE_Mutex> interface consistent with the other synchronization APIs.

Definition at line 95 of file Synch.i.

References ACE_OS::mutex_lock.

Referenced by ACE_Process_Mutex::acquire_read.

00096 {
00097 // ACE_TRACE ("ACE_Mutex::acquire_read");
00098 #if defined (CHORUS)
00099    if (this->process_lock_)
00100      return ACE_OS::mutex_lock (this->process_lock_);
00101 #endif /* CHORUS */
00102   return ACE_OS::mutex_lock (&this->lock_);
00103 }

ACE_INLINE int ACE_Mutex::acquire_write void   
 

Acquire mutex ownership. This calls <acquire> and is only here to make the <ACE_Mutex> interface consistent with the other synchronization APIs.

Definition at line 106 of file Synch.i.

References ACE_OS::mutex_lock.

Referenced by ACE_Process_Mutex::acquire_write.

00107 {
00108 // ACE_TRACE ("ACE_Mutex::acquire_write");
00109 #if defined (CHORUS)
00110    if (this->process_lock_)
00111      return ACE_OS::mutex_lock (this->process_lock_);
00112 #endif /* CHORUS */
00113   return ACE_OS::mutex_lock (&this->lock_);
00114 }

void ACE_Mutex::dump void    const
 

Dump the state of an object.

Definition at line 176 of file Synch.cpp.

References ACE_BEGIN_DUMP, ACE_DEBUG, ACE_END_DUMP, ACE_LIB_TEXT, and LM_DEBUG.

Referenced by ACE_Process_Mutex::dump.

00177 {
00178 // ACE_TRACE ("ACE_Mutex::dump");
00179 
00180   ACE_DEBUG ((LM_DEBUG, ACE_BEGIN_DUMP, this));
00181 #if defined (CHORUS)
00182   ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("lockname_ = %s\n"), this->lockname_));
00183   ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("process_lock_ = %x\n"), this->process_lock_));
00184 #endif /* CHORUS */
00185   ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("\n")));
00186   ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP));
00187 }

ACE_INLINE const ACE_mutex_t & ACE_Mutex::lock void    const
 

Return the underlying mutex.

Definition at line 128 of file Synch.i.

References lock_.

Referenced by ACE_Process_Mutex::lock.

00129 {
00130 // ACE_TRACE ("ACE_Mutex::lock");
00131 #if defined (CHORUS)
00132   if (this->process_lock_)
00133     return *this->process_lock_;
00134 #endif /* CHORUS */
00135   return this->lock_;
00136 }

void ACE_Mutex::operator= const ACE_Mutex &    [private]
 

ACE_INLINE int ACE_Mutex::release void   
 

Release lock and unblock a thread at head of queue.

Definition at line 193 of file Synch.i.

References ACE_OS::mutex_unlock.

Referenced by ACE_Process_Mutex::release.

00194 {
00195 // ACE_TRACE ("ACE_Mutex::release");
00196 #if defined (CHORUS)
00197    if (this->process_lock_)
00198      return ACE_OS::mutex_unlock (this->process_lock_);
00199 #endif /* CHORUS */
00200   return ACE_OS::mutex_unlock (&this->lock_);
00201 }

ACE_INLINE int ACE_Mutex::remove void   
 

Explicitly destroy the mutex. Note that only one thread should call this method since it doesn't protect against race conditions.

Definition at line 204 of file Synch.i.

References ACE_TCHAR, ACE_OS_Memory::free, ACE_OS::munmap, ACE_OS::mutex_destroy, removed_, and ACE_OS::shm_unlink.

Referenced by ACE_Process_Mutex::remove, and ~ACE_Mutex.

00205 {
00206 // ACE_TRACE ("ACE_Mutex::remove");
00207 #if defined (CHORUS) || defined (ACE_HAS_PTHREADS) || defined (ACE_HAS_STHREADS)
00208    int result = 0;
00209    // In the case of a interprocess mutex, the owner is the first
00210    // process that created the shared memory object. In this case, the
00211    // lockname_ pointer will be non-zero (points to allocated memory
00212    // for the name).  Owner or not, the memory needs to be unmapped
00213    // from the process.  If we are the owner, the file used for
00214    // shm_open needs to be deleted as well.
00215    if (this->process_lock_)
00216      {
00217        if (this->removed_ == 0)
00218          {
00219            this->removed_ = 1;
00220 
00221            // Only destroy the lock if we're the ones who initialized
00222            // it.
00223            if (!this->lockname_)
00224              ACE_OS::munmap ((void *) this->process_lock_,
00225                              sizeof (ACE_mutex_t));
00226            else
00227              {
00228                result = ACE_OS::mutex_destroy (this->process_lock_);
00229                ACE_OS::munmap ((void *) this->process_lock_,
00230                                sizeof (ACE_mutex_t));
00231                ACE_OS::shm_unlink (this->lockname_);
00232                ACE_OS::free (ACE_static_cast (void *,
00233                                               ACE_const_cast (ACE_TCHAR *,
00234                                                             this->lockname_)));
00235              }
00236          }
00237      }
00238    return result;
00239 #else /* !CHORUS */
00240   int result = 0;
00241   if (this->removed_ == 0)
00242     {
00243       this->removed_ = 1;
00244       result = ACE_OS::mutex_destroy (&this->lock_);
00245     }
00246   return result;
00247 #endif /* CHORUS */
00248 }

ACE_INLINE int ACE_Mutex::tryacquire void   
 

Conditionally acquire lock (i.e., don't wait on queue). Returns -1 on failure. If we "failed" because someone else already had the lock, <errno> is set to <EBUSY>.

Definition at line 182 of file Synch.i.

References ACE_OS::mutex_trylock.

Referenced by ACE_Process_Mutex::tryacquire.

00183 {
00184 // ACE_TRACE ("ACE_Mutex::tryacquire");
00185 #if defined (CHORUS)
00186    if (this->process_lock_)
00187      return ACE_OS::mutex_trylock (this->process_lock_);
00188 #endif /* CHORUS */
00189   return ACE_OS::mutex_trylock (&this->lock_);
00190 }

ACE_INLINE int ACE_Mutex::tryacquire_read void   
 

Conditionally acquire mutex (i.e., won't block). This calls <tryacquire> and is only here to make the <ACE_Mutex> interface consistent with the other synchronization APIs. Returns -1 on failure. If we "failed" because someone else already had the lock, <errno> is set to <EBUSY>.

Definition at line 117 of file Synch.i.

References ACE_OS::mutex_trylock.

Referenced by ACE_Process_Mutex::tryacquire_read.

00118 {
00119 // ACE_TRACE ("ACE_Mutex::tryacquire_read");
00120 #if defined (CHORUS)
00121    if (this->process_lock_)
00122      return ACE_OS::mutex_trylock (this->process_lock_);
00123 #endif /* CHORUS */
00124   return ACE_OS::mutex_trylock (&this->lock_);
00125 }

ACE_INLINE int ACE_Mutex::tryacquire_write void   
 

Conditionally acquire mutex (i.e., won't block). This calls <tryacquire> and is only here to make the <ACE_Mutex> interface consistent with the other synchronization APIs. Returns -1 on failure. If we "failed" because someone else already had the lock, <errno> is set to <EBUSY>.

Definition at line 139 of file Synch.i.

References ACE_OS::mutex_trylock.

Referenced by ACE_Process_Mutex::tryacquire_write.

00140 {
00141 // ACE_TRACE ("ACE_Mutex::tryacquire_write");
00142 #if defined (CHORUS)
00143    if (this->process_lock_)
00144      return ACE_OS::mutex_trylock (this->process_lock_);
00145 #endif /* CHORUS */
00146   return ACE_OS::mutex_trylock (&this->lock_);
00147 }

ACE_INLINE int ACE_Mutex::tryacquire_write_upgrade void   
 

This is only here for consistency with the other synchronization APIs and usability with Lock adapters. Assumes the caller already has acquired the mutex and returns 0 in all cases.

Definition at line 150 of file Synch.i.

00151 {
00152 // ACE_TRACE ("ACE_Mutex::tryacquire_write_upgrade");
00153   return 0;
00154 }


Member Data Documentation

ACE_Mutex::ACE_ALLOC_HOOK_DECLARE
 

Declare the dynamic allocation hooks.

Definition at line 569 of file Synch.h.

ACE_mutex_t ACE_Mutex::lock_
 

Mutex type supported by the OS.

Definition at line 586 of file Synch.h.

Referenced by lock.

int ACE_Mutex::removed_
 

Keeps track of whether <remove> has been called yet to avoid multiple <remove> calls, e.g., explicitly and implicitly in the destructor. This flag isn't protected by a lock, so make sure that you don't have multiple threads simultaneously calling <remove> on the same object, which is a bad idea anyway...

Definition at line 593 of file Synch.h.

Referenced by remove.


The documentation for this class was generated from the following files:
Generated on Mon Jun 16 12:50:49 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002