ACE  6.1.0
Public Member Functions | Public Attributes | Private Member Functions | Private Attributes
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 (const wchar_t *name, 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_TCHARunique_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 offer System V IPC (the ACE_HAS_SYSV_IPC config macro is defined) ACE_SV_Semaphore_Complex is the default because it is more convenient and easy to use. ACE_Mutex is the default on all other platforms. On platforms where ACE_SV_Semaphore_Complex is used by default, the mechanism can be changed to ACE_Mutex when ACE is built by adding
   #define ACE_USES_MUTEX_FOR_PROCESS_MUTEX
to your config.h file.
Consider these tradeoffs when evaluating whether or not to change the default:
  • Some platforms (e.g., Pthreads and UI Threads) require interprocess mutexes to be allocated from shared memory. On these platforms, using ACE_Mutex as the underlying mechanism requires that ACE_Process_Mutex objects be allocated in shared memory. Using ACE_SV_Semaphore_Complex avoids this restriction.
  • System V IPC kernel parameters have a low default limit on some platforms. This would restrict the number of ACE_Process_Mutex objects that can be in use simultaneously when using ACE_SV_Semaphore_Complex.
  • If you require the ability to do a timed acquire(), you must use ACE_Mutex as the underlying mechanism because timed acquire does not work with System V semaphores.
  • When using ACE_Mutex on a Pthreads-based platform, an ACE_Process_Mutex object is deleted when the process which created the object destroys it, regardless of whether or not there are other processes still accessing the ACE_Process_Mutex. Using ACE_SV_Semaphore_Complex avoids this problem; the semaphore is destroyed when the last use of the object ends. For portable applications it is better to always ensure that the owner of the mutex destroys it after all other processes have stopped using it.

Constructor & Destructor Documentation

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

Create an ACE_Process_Mutex.

Parameters:
nameoptional, 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.
argoptional, attributes to be used to initialize the mutex. If using ACE_SV_Semaphore_Complex as the underlying mechanism, this argument is ignored.
modeoptional, the protection mode for either the backing store file (for ACE_Mutex use) or the ACE_SV_Semaphore_Complex that's created.
ACE_Process_Mutex::ACE_Process_Mutex ( const wchar_t *  name,
void *  arg = 0,
mode_t  mode = ACE_DEFAULT_FILE_PERMS 
)

Create an ACE_Process_Mutex (wchar_t version)

Parameters:
nameoptional, 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.
argoptional, attributes to be used to initialize the mutex. If using ACE_SV_Semaphore_Complex as the underlying mechanism, this argument is ignored.
modeoptional, the protection mode for either the backing store file (for ACE_Mutex use) or the ACE_SV_Semaphore_Complex that's created.
ACE_Process_Mutex::~ACE_Process_Mutex ( void  )

Destructor.

Note:
The destructor will not release an acquired mutex except on Windows.

Member Function Documentation

int ACE_Process_Mutex::acquire ( void  ) [inline]

Acquire lock ownership (wait on queue if necessary).

Returns:
0 on success; -1 on failure.
int ACE_Process_Mutex::acquire ( ACE_Time_Value tv) [inline]

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

Parameters:
tvthe absolute time until which the caller is willing to wait to acquire the lock.
Returns:
0 on success; -1 on failure.
int ACE_Process_Mutex::acquire_read ( void  ) [inline]

Acquire lock ownership (wait on queue if necessary).

int ACE_Process_Mutex::acquire_write ( void  ) [inline]

Acquire lock ownership (wait on queue if necessary).

void ACE_Process_Mutex::dump ( void  ) const

Dump the state of an object.

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

Return the underlying mutex.

int ACE_Process_Mutex::release ( void  ) [inline]

Release lock and unblock a thread at head of queue.

int ACE_Process_Mutex::remove ( void  ) [inline]

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.
int ACE_Process_Mutex::tryacquire ( void  ) [inline]

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.
int ACE_Process_Mutex::tryacquire_read ( void  ) [inline]

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.

int ACE_Process_Mutex::tryacquire_write ( void  ) [inline]

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.

int ACE_Process_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.

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

Create and return the unique name.


Member Data Documentation

Declare the dynamic allocation hooks.

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.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines