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:

[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_SV_Semaphore_Complex	lock_
	We need this to get the right semantics...
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.

Definition at line 86 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 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.

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	(	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.

Definition at line 86 of file Process_Mutex.cpp.

00087 {
00088 }

Member Function Documentation

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.

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 }

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.

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 }

int ACE_Process_Mutex::acquire_read ( void )

Acquire lock ownership (wait on queue if necessary).

Definition at line 70 of file Process_Mutex.inl.

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 }

int ACE_Process_Mutex::acquire_write ( void )

Acquire lock ownership (wait on queue if necessary).

Definition at line 81 of file Process_Mutex.inl.

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 }

void ACE_Process_Mutex::dump ( void ) const

Dump the state of an object.

Definition at line 21 of file Process_Mutex.cpp.

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 }

const ACE_mutex_t & ACE_Process_Mutex::lock ( void ) const

Return the underlying mutex.

Definition at line 9 of file Process_Mutex.inl.

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

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.

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 }

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.

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

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.

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 }

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.

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 }

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.

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 }

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.

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 }