Public Member Functions | Public Attributes | Private Member Functions

ACE_Mutex Class Reference

ACE_Mutex wrapper (valid in same process or across processes (depending on TYPE flag)). In general, however, we recommend using ACE_Process_Mutex or ACE_Thread_Mutex rather than ACE_Mutex. More...

#include <Mutex.h>

List of all members.

Public Member Functions

 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.
 ~ACE_Mutex (void)
 Implicitly destroy the mutex.
int remove (void)
 Explicitly destroy the mutex.
int acquire (void)
 Acquire lock ownership (wait on queue if necessary).
int acquire (ACE_Time_Value &tv)
int acquire (ACE_Time_Value *tv)
int tryacquire (void)
 Conditionally acquire lock (i.e., don't wait on queue).
int release (void)
 Release lock and unblock a thread at head of queue.
int acquire_read (void)
 Acquire mutex ownership.
int acquire_write (void)
 Acquire mutex ownership.
int tryacquire_read (void)
 Conditionally acquire mutex (i.e., won't block).
int tryacquire_write (void)
 Conditionally acquire mutex (i.e., won't block).
int tryacquire_write_upgrade (void)
const ACE_mutex_t & lock (void) const
 Return the underlying mutex.
void dump (void) const
 Dump the state of an object.

Public Attributes

 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks.
ACE_mutex_t lock_
 Mutex type supported by the OS.
bool removed_

Private Member Functions

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)). In general, however, we recommend using ACE_Process_Mutex or ACE_Thread_Mutex rather than ACE_Mutex.

Definition at line 50 of file Mutex.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 38 of file Mutex.cpp.

  :
#if defined (ACE_HAS_PTHREADS) || defined(ACE_HAS_STHREADS)
    process_lock_ (0),
    lockname_ (0),
#endif /* ACE_HAS_PTHREADS || ACE_HAS_STHREADS */
    removed_ (false)
{
  // ACE_TRACE ("ACE_Mutex::ACE_Mutex");

  // These platforms need process-wide mutex to be in shared memory.
#if defined(ACE_HAS_PTHREADS) || defined (ACE_HAS_STHREADS)
  if (type == USYNC_PROCESS)
    {
      // Let's see if the shared memory entity already exists.
      ACE_HANDLE fd = ACE_OS::shm_open (name, O_RDWR | O_CREAT | O_EXCL, mode);
      if (fd == ACE_INVALID_HANDLE)
        {
          if (errno == EEXIST)
            fd = ACE_OS::shm_open (name, O_RDWR | O_CREAT, mode);
          else
            return;
        }
      else
        {
          // We own this shared memory object!  Let's set its size.
          if (ACE_OS::ftruncate (fd,
                                 sizeof (ACE_mutex_t)) == -1)
            {
              ACE_OS::close (fd);
              return;
            }
          this->lockname_ = ACE_OS::strdup (name);
          if (this->lockname_ == 0)
            {
              ACE_OS::close (fd);
              return;
            }
        }

      this->process_lock_ =
        (ACE_mutex_t *) ACE_OS::mmap (0,
                                      sizeof (ACE_mutex_t),
                                      PROT_RDWR,
                                      MAP_SHARED,
                                      fd,
                                      0);
      ACE_OS::close (fd);
      if (this->process_lock_ == MAP_FAILED)
        return;

      if (this->lockname_
          && ACE_OS::mutex_init (this->process_lock_,
                                 type,
                                 name,
                                 arg) != 0)
        {
          ACE_ERROR ((LM_ERROR,
                      ACE_TEXT ("%p\n"),
                      ACE_TEXT ("ACE_Mutex::ACE_Mutex")));
          return;
        }
    }
  else
    {
      // local mutex init if USYNC_PROCESS flag is not enabled.
#else
      ACE_UNUSED_ARG (mode);
#endif /* ACE_HAS_PTHREADS || ACE_HAS_STHREADS */

      if (ACE_OS::mutex_init (&this->lock_,
                              type,
                              name,
                              arg) != 0)
        ACE_ERROR ((LM_ERROR,
                    ACE_TEXT ("%p\n"),
                    ACE_TEXT ("ACE_Mutex::ACE_Mutex")));
#if defined(ACE_HAS_PTHREADS) || defined (ACE_HAS_STHREADS)
    }
#endif /* ACE_HAS_PTHREADS || ACE_HAS_STHREADS */
}

ACE_Mutex::~ACE_Mutex ( void   ) 

Implicitly destroy the mutex.

Definition at line 121 of file Mutex.cpp.

{
// ACE_TRACE ("ACE_Mutex::~ACE_Mutex");
  this->remove ();
}

ACE_Mutex::ACE_Mutex ( const ACE_Mutex &   )  [private]

Member Function Documentation

int ACE_Mutex::acquire ( void   )  [inline]

Acquire lock ownership (wait on queue if necessary).

Definition at line 73 of file Mutex.inl.

{
// ACE_TRACE ("ACE_Mutex::acquire");
#if defined (ACE_HAS_PTHREADS) || defined(ACE_HAS_STHREADS)
   if (this->process_lock_)
     return ACE_OS::mutex_lock (this->process_lock_);
#endif /* ACE_HAS_PTHREADS || ACE_HAS_STHREADS */
  return ACE_OS::mutex_lock (&this->lock_);
}

int ACE_Mutex::acquire ( ACE_Time_Value *  tv  )  [inline]

Block the thread until the mutex is acquired or *tv times out, in which case -1 is returned and errno == ETIME. 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:
*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 95 of file Mutex.inl.

{
 #if defined (ACE_HAS_PTHREADS) || defined(ACE_HAS_STHREADS)
   if (this->process_lock_)
     return ACE_OS::mutex_lock (this->process_lock_, tv);
#endif /* ACE_HAS_PTHREADS || ACE_HAS_STHREADS*/
  return ACE_OS::mutex_lock (&this->lock_, tv);
}

int ACE_Mutex::acquire ( ACE_Time_Value &  tv  )  [inline]

Block the thread until the mutex is acquired or tv times out, in which case -1 is returned and errno == ETIME.

Note:
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 84 of file Mutex.inl.

{
  // ACE_TRACE ("ACE_Mutex::acquire");
 #if defined (ACE_HAS_PTHREADS) || defined(ACE_HAS_STHREADS)
   if (this->process_lock_)
     return ACE_OS::mutex_lock (this->process_lock_, tv);
#endif /* ACE_HAS_PTHREADS || ACE_HAS_STHREADS*/
  return ACE_OS::mutex_lock (&this->lock_, tv);
}

int ACE_Mutex::acquire_read ( void   )  [inline]

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 11 of file Mutex.inl.

{
// ACE_TRACE ("ACE_Mutex::acquire_read");
#if defined (ACE_HAS_PTHREADS) || defined(ACE_HAS_STHREADS)
   if (this->process_lock_)
     return ACE_OS::mutex_lock (this->process_lock_);
#endif /* ACE_HAS_PTHREADS || ACE_HAS_STHREADS */
  return ACE_OS::mutex_lock (&this->lock_);
}

int ACE_Mutex::acquire_write ( void   )  [inline]

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 22 of file Mutex.inl.

{
// ACE_TRACE ("ACE_Mutex::acquire_write");
#if defined (ACE_HAS_PTHREADS) || defined(ACE_HAS_STHREADS)
   if (this->process_lock_)
     return ACE_OS::mutex_lock (this->process_lock_);
#endif /* ACE_HAS_PTHREADS || ACE_HAS_STHREADS */
  return ACE_OS::mutex_lock (&this->lock_);
}

void ACE_Mutex::dump ( void   )  const

Dump the state of an object.

const ACE_mutex_t & ACE_Mutex::lock ( void   )  const [inline]

Return the underlying mutex.

Definition at line 44 of file Mutex.inl.

{
// ACE_TRACE ("ACE_Mutex::lock");
#if defined (ACE_HAS_PTHREADS) || defined(ACE_HAS_STHREADS)
  if (this->process_lock_)
    return *this->process_lock_;
#endif /* ACE_HAS_PTHREADS || ACE_HAS_STHREADS */
  return this->lock_;
}

void ACE_Mutex::operator= ( const ACE_Mutex &   )  [private]
int ACE_Mutex::release ( void   )  [inline]

Release lock and unblock a thread at head of queue.

Definition at line 116 of file Mutex.inl.

{
// ACE_TRACE ("ACE_Mutex::release");
#if defined (ACE_HAS_PTHREADS) || defined(ACE_HAS_STHREADS)
   if (this->process_lock_)
     return ACE_OS::mutex_unlock (this->process_lock_);
#endif /* ACE_HAS_PTHREADS || ACE_HAS_STHREADS */
  return ACE_OS::mutex_unlock (&this->lock_);
}

int ACE_Mutex::remove ( void   )  [inline]

Explicitly destroy the mutex.

Note:
Only one thread should call this method since it doesn't protect against race conditions.

Definition at line 127 of file Mutex.inl.

{
// ACE_TRACE ("ACE_Mutex::remove");
  int result = 0;
#if defined (ACE_HAS_PTHREADS) || defined (ACE_HAS_STHREADS)
  // In the case of a interprocess mutex, the owner is the first
  // process that created the shared memory object. In this case, the
  // lockname_ pointer will be non-zero (points to allocated memory
  // for the name).  Owner or not, the memory needs to be unmapped
  // from the process.  If we are the owner, the file used for
  // shm_open needs to be deleted as well.
  if (this->process_lock_)
    {
      if (this->removed_ == false)
        {
          this->removed_ = true;
          // Only destroy the lock if we're the ones who initialized
          // it.
          if (!this->lockname_)
            ACE_OS::munmap ((void *) this->process_lock_,
                            sizeof (ACE_mutex_t));
          else
            {
              result = ACE_OS::mutex_destroy (this->process_lock_);
              ACE_OS::munmap ((void *) this->process_lock_,
                              sizeof (ACE_mutex_t));
              ACE_OS::shm_unlink (this->lockname_);
              ACE_OS::free (
                static_cast<void *> (
                  const_cast<ACE_TCHAR *> (this->lockname_)));
            }
        }
    }
  else
  {
#else /* !ACE_HAS_PTHREADS && !ACE_HAS_STHREADS */
    if (this->removed_ == false)
      {
        this->removed_ = true;
        result = ACE_OS::mutex_destroy (&this->lock_);
      }
#endif /* ACE_HAS_PTHREADS || ACE_HAS_STHREADS */
#if defined (ACE_HAS_PTHREADS) || defined (ACE_HAS_STHREADS)
  }
#endif /* ACE_HAS_PTHREADS || ACE_HAS_STHREADS */
  return result;
}

int ACE_Mutex::tryacquire ( void   )  [inline]

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 105 of file Mutex.inl.

{
// ACE_TRACE ("ACE_Mutex::tryacquire");
#if defined (ACE_HAS_PTHREADS) || defined(ACE_HAS_STHREADS)
   if (this->process_lock_)
     return ACE_OS::mutex_trylock (this->process_lock_);
#endif /* ACE_HAS_PTHREADS || ACE_HAS_STHREADS */
  return ACE_OS::mutex_trylock (&this->lock_);
}

int ACE_Mutex::tryacquire_read ( void   )  [inline]

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 33 of file Mutex.inl.

{
// ACE_TRACE ("ACE_Mutex::tryacquire_read");
#if defined (ACE_HAS_PTHREADS) || defined(ACE_HAS_STHREADS)
   if (this->process_lock_)
     return ACE_OS::mutex_trylock (this->process_lock_);
#endif /* ACE_HAS_PTHREADS || ACE_HAS_STHREADS */
  return ACE_OS::mutex_trylock (&this->lock_);
}

int ACE_Mutex::tryacquire_write ( void   )  [inline]

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 55 of file Mutex.inl.

{
// ACE_TRACE ("ACE_Mutex::tryacquire_write");
#if defined (ACE_HAS_PTHREADS) || defined(ACE_HAS_STHREADS)
   if (this->process_lock_)
     return ACE_OS::mutex_trylock (this->process_lock_);
#endif /* ACE_HAS_PTHREADS || ACE_HAS_STHREADS */
  return ACE_OS::mutex_trylock (&this->lock_);
}

int ACE_Mutex::tryacquire_write_upgrade ( void   )  [inline]

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 66 of file Mutex.inl.

{
// ACE_TRACE ("ACE_Mutex::tryacquire_write_upgrade");
  return 0;
}

Member Data Documentation

ACE_Mutex::ACE_ALLOC_HOOK_DECLARE

Declare the dynamic allocation hooks.

Definition at line 152 of file Mutex.h.

ACE_mutex_t ACE_Mutex::lock_

Mutex type supported by the OS.

Definition at line 169 of file Mutex.h.

bool 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 176 of file Mutex.h.

The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Generated on Thu Dec 9 2010 11:57:53 for ACE by  doxygen 1.7.0