ACE_Process_Mutex Class Reference

A wrapper for mutexes that can be used across processes on the same host machine, as well as within a process, of course. More...

#include <Process_Mutex.h>

Collaboration diagram for ACE_Process_Mutex:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 ACE_Process_Mutex (const char *name=0, void *arg=0, mode_t mode=ACE_DEFAULT_FILE_PERMS)
 ~ACE_Process_Mutex (void)
int remove (void)
int acquire (void)
int acquire (ACE_Time_Value &tv)
int tryacquire (void)
int release (void)
 Release lock and unblock a thread at head of queue.
int acquire_read (void)
 Acquire lock ownership (wait on queue if necessary).
int acquire_write (void)
 Acquire lock ownership (wait on queue if necessary).
int tryacquire_read (void)
int tryacquire_write (void)
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.

Private Member Functions

const ACE_TCHAR * unique_name (void)
 Create and return the unique name.

Private Attributes

ACE_TCHAR name_ [ACE_UNIQUE_NAME_LEN]
ACE_Mutex lock_

Detailed Description

A wrapper for mutexes that can be used across processes on the same host machine, as well as within a process, of course.

Attention:
The mechanism upon which ACE_Process_Mutex is based can be configured at build time to be either ACE_SV_Semaphore_Complex (on platforms that support it) or ACE_Mutex. On platforms that require interprocess mutexes be allocated from shared memory (Pthreads and UI Threads are examples), ACE_SV_Semaphore_Complex provides a more reliable mechanism for implementing inter-process mutex than ACE_Mutex. However, at least on some platforms, ACE_SV_Semaphore_Complex is limited to a small number of objects by the underlying System V IPC kernel parameters. If you want to force use of ACE_Mutex as the underlying mechanism, set ACE_USES_MUTEX_FOR_PROCESS_MUTEX in your config.h file. Also, if you require the ability to do a timed acquire(), you must set ACE_USES_MUTEX_FOR_PROCESS_MUTEX, as timed acquire does not work with System V semaphores.

Currently there is also the operational difference between pthreads and semaphores based . For semaphore base the semaphore is destroyed after the last instance of in OS. In contrary, pthread based is destroyed when the owner, namely the process which created the first instance of destroys the mutex. For protable applications it is better to always ensure that the owner of the mutex destroys it after the other processes.

Definition at line 74 of file Process_Mutex.h.

Constructor & Destructor Documentation

ACE_Process_Mutex::ACE_Process_Mutex ( const char *  name = 0,
void *  arg = 0,
mode_t  mode = ACE_DEFAULT_FILE_PERMS 
)

Create a Process_Mutex, passing in the optional name.

Parameters:
name optional, null-terminated string containing the name of the object. Multiple users of the same ACE_Process_Mutex must use the same name to access the same object. If not specified, a name is generated.
arg optional, attributes to be used to initialize the mutex. If using ACE_SV_Semaphore_Complex as the underlying mechanism, this argument is ignored.
mode optional, the protection mode for either the backing store file (for ACE_Mutex use) or the ACE_SV_Semaphore_Complex that's created.

Definition at line 41 of file Process_Mutex.cpp.

00043   : lock_ (name ? name : ACE_TEXT_ALWAYS_CHAR (this->unique_name ()),
00044            ACE_SV_Semaphore_Complex::ACE_CREATE,
00045            1,
00046            1,
00047            mode)
00048 #else
00049   : lock_ (USYNC_PROCESS,
00050            name ?
00051              ACE_TEXT_CHAR_TO_TCHAR (name) : this->unique_name (),
00052            (ACE_mutexattr_t *) arg,
00053            mode)
00054 #endif /* _ACE_USE_SV_SEM */
00055 {
00056 #if defined (_ACE_USE_SV_SEM)
00057   ACE_UNUSED_ARG (arg);
00058 #endif /* !_ACE_USE_SV_SEM */
00059 }

ACE_Process_Mutex::~ACE_Process_Mutex ( void   ) 

Definition at line 86 of file Process_Mutex.cpp.

00087 {
00088 }

Member Function Documentation

ACE_INLINE int ACE_Process_Mutex::acquire ( ACE_Time_Value &  tv  ) 

Acquire lock ownership, but timeout if lock if hasn't been acquired by given time.

Parameters:
tv the absolute time until which the caller is willing to wait to acquire the lock.
Returns:
0 on success; -1 on failure.

Definition at line 36 of file Process_Mutex.inl.

References ACE_NOTSUP_RETURN, ACE_Mutex::acquire(), and lock_.

00037 {
00038 #if !defined (_ACE_USE_SV_SEM)
00039   return this->lock_.acquire (tv);
00040 #else
00041   ACE_UNUSED_ARG (tv);
00042   ACE_NOTSUP_RETURN (-1);
00043 #endif  /* !_ACE_USE_SV_SEM */
00044 }

ACE_INLINE int ACE_Process_Mutex::acquire ( void   ) 

Acquire lock ownership (wait on queue if necessary).

Returns:
0 on success; -1 on failure.

Definition at line 25 of file Process_Mutex.inl.

References ACE_Mutex::acquire(), lock_, and SEM_UNDO.

00026 {
00027 #if defined (_ACE_USE_SV_SEM)
00028   return this->lock_.acquire (0, SEM_UNDO);
00029 #else
00030   return this->lock_.acquire ();
00031 #endif // _ACE_USE_SV_SEM
00032 }

ACE_INLINE int ACE_Process_Mutex::acquire_read ( void   ) 

Acquire lock ownership (wait on queue if necessary).

Definition at line 70 of file Process_Mutex.inl.

References ACE_Mutex::acquire_read(), lock_, and SEM_UNDO.

00071 {
00072 #if defined (_ACE_USE_SV_SEM)
00073   return this->lock_.acquire_read (0, SEM_UNDO);
00074 #else
00075   return this->lock_.acquire_read ();
00076 #endif // _ACE_USE_SV_SEM
00077 }

ACE_INLINE int ACE_Process_Mutex::acquire_write ( void   ) 

Acquire lock ownership (wait on queue if necessary).

Definition at line 81 of file Process_Mutex.inl.

References ACE_Mutex::acquire_write(), lock_, and SEM_UNDO.

00082 {
00083 #if defined (_ACE_USE_SV_SEM)
00084   return this->lock_.acquire_write (0, SEM_UNDO);
00085 #else
00086   return this->lock_.acquire_write ();
00087 #endif // _ACE_USE_SV_SEM
00088 }

ACE_BEGIN_VERSIONED_NAMESPACE_DECL void ACE_Process_Mutex::dump ( void   )  const

Dump the state of an object.

Definition at line 21 of file Process_Mutex.cpp.

References ACE_BEGIN_DUMP, ACE_DEBUG, ACE_END_DUMP, and LM_DEBUG.

00022 {
00023 #if defined (ACE_HAS_DUMP)
00024 // ACE_TRACE ("ACE_Process_Mutex::dump");
00025   ACE_DEBUG ((LM_DEBUG, ACE_BEGIN_DUMP, this));
00026   this->lock_.dump ();
00027   ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP));
00028 #endif /* ACE_HAS_DUMP */
00029 }

ACE_BEGIN_VERSIONED_NAMESPACE_DECL ACE_INLINE const ACE_mutex_t & ACE_Process_Mutex::lock ( void   )  const

Return the underlying mutex.

Definition at line 9 of file Process_Mutex.inl.

References ACE_Mutex::lock(), and lock_.

00010 {
00011 // ACE_TRACE ("ACE_Process_Mutex::lock");
00012   return this->lock_.lock ();
00013 }

ACE_INLINE int ACE_Process_Mutex::release ( void   ) 

Release lock and unblock a thread at head of queue.

Definition at line 59 of file Process_Mutex.inl.

References lock_, ACE_Mutex::release(), and SEM_UNDO.

00060 {
00061 #if defined (_ACE_USE_SV_SEM)
00062   return this->lock_.release (0, SEM_UNDO);
00063 #else
00064   return this->lock_.release ();
00065 #endif // _ACE_USE_SV_SEM
00066 }

ACE_INLINE int ACE_Process_Mutex::remove ( void   ) 

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

Returns:
0 on success; -1 on failure.

Definition at line 18 of file Process_Mutex.inl.

References lock_, and ACE_Mutex::remove().

00019 {
00020   return this->lock_.remove ();
00021 }

ACE_INLINE int ACE_Process_Mutex::tryacquire ( void   ) 

Conditionally acquire lock (i.e., don't wait on queue).

Returns:
0 on success; -1 on failure. If the lock could not be acquired because someone else already had the lock, errno is set to EBUSY.

Definition at line 48 of file Process_Mutex.inl.

References lock_, SEM_UNDO, and ACE_Mutex::tryacquire().

00049 {
00050 #if defined (_ACE_USE_SV_SEM)
00051   return this->lock_.tryacquire (0, SEM_UNDO);
00052 #else
00053   return this->lock_.tryacquire ();
00054 #endif // _ACE_USE_SV_SEM
00055 }

ACE_INLINE int ACE_Process_Mutex::tryacquire_read ( void   ) 

Conditionally acquire a lock (i.e., won't block). Returns -1 on failure. If we "failed" because someone else already had the lock, errno is set to EBUSY.

Definition at line 92 of file Process_Mutex.inl.

References lock_, SEM_UNDO, and ACE_Mutex::tryacquire_read().

00093 {
00094 #if defined (_ACE_USE_SV_SEM)
00095   return this->lock_.tryacquire_read (0, SEM_UNDO);
00096 #else
00097   return this->lock_.tryacquire_read ();
00098 #endif // _ACE_USE_SV_SEM
00099 }

ACE_INLINE int ACE_Process_Mutex::tryacquire_write ( void   ) 

Conditionally acquire a lock (i.e., won't block). Returns -1 on failure. If we "failed" because someone else already had the lock, errno is set to EBUSY.

Definition at line 103 of file Process_Mutex.inl.

References lock_, SEM_UNDO, and ACE_Mutex::tryacquire_write().

00104 {
00105 #if defined (_ACE_USE_SV_SEM)
00106   return this->lock_.tryacquire_write (0, SEM_UNDO);
00107 #else
00108   return this->lock_.tryacquire_write ();
00109 #endif // _ACE_USE_SV_SEM
00110 }

ACE_INLINE int ACE_Process_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 113 of file Process_Mutex.inl.

00114 {
00115   return 0;
00116 }

const ACE_TCHAR * ACE_Process_Mutex::unique_name ( void   )  [private]

Create and return the unique name.

Definition at line 32 of file Process_Mutex.cpp.

References ACE_UNIQUE_NAME_LEN, name_, and ACE::unique_name().

00033 {
00034   // For all platforms other than Win32, we are going to create a
00035   // machine-wide unique name if one is not provided by the user.  On
00036   // Win32, unnamed synchronization objects are acceptable.
00037   ACE::unique_name (this, this->name_, ACE_UNIQUE_NAME_LEN);
00038   return this->name_;
00039 }

Member Data Documentation

ACE_Process_Mutex::ACE_ALLOC_HOOK_DECLARE

Declare the dynamic allocation hooks.

Definition at line 190 of file Process_Mutex.h.

ACE_Mutex ACE_Process_Mutex::lock_ [private]

Definition at line 204 of file Process_Mutex.h.

Referenced by acquire(), acquire_read(), acquire_write(), lock(), release(), remove(), tryacquire(), tryacquire_read(), and tryacquire_write().

ACE_TCHAR ACE_Process_Mutex::name_[ACE_UNIQUE_NAME_LEN] [private]

If the user does not provide a name we generate a unique name in this buffer.

Definition at line 195 of file Process_Mutex.h.

Referenced by unique_name().

The documentation for this class was generated from the following files:
Generated on Tue Feb 2 17:35:27 2010 for ACE by  doxygen 1.4.7