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

---

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.

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

Create a Process_Mutex, passing in the optional name. (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   )

---

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.

ACE_INLINE int ACE_Process_Mutex::acquire (  void   )

Acquire lock ownership (wait on queue if necessary). Returns: 0 on success; -1 on failure.

ACE_INLINE int ACE_Process_Mutex::acquire_read (  void   )

Acquire lock ownership (wait on queue if necessary).

ACE_INLINE int ACE_Process_Mutex::acquire_write (  void   )

Acquire lock ownership (wait on queue if necessary).

ACE_BEGIN_VERSIONED_NAMESPACE_DECL void ACE_Process_Mutex::dump (  void   )  const

Dump the state of an object.

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

Return the underlying mutex.

ACE_INLINE int ACE_Process_Mutex::release (  void   )

Release lock and unblock a thread at head of queue.

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.

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.

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

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

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.

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:

• Process_Mutex.h
• Process_Mutex.cpp
• Process_Mutex.inl

---