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:

[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_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 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:

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.

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:

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.

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:

tv	the 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

ACE_Process_Mutex::ACE_ALLOC_HOOK_DECLARE

Declare the dynamic allocation hooks.

ACE_Mutex ACE_Process_Mutex::lock_ [private]

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:

Public Member Functions

Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation