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