Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

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 Methods

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

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

 ~ACE_Process_Mutex (void)
int remove (void)
 Explicitly destroy the mutex. More...

int acquire (void)
 Acquire lock ownership (wait on queue if necessary). More...

int acquire (ACE_Time_Value &tv)
 Acquire lock ownership, but timeout if lock if hasn't been acquired by given time. More...

int tryacquire (void)
 Conditionally acquire lock (i.e., don't wait on queue). More...

int release (void)
 Release lock and unblock a thread at head of queue. More...

int acquire_read (void)
 Acquire lock ownership (wait on queue if necessary). More...

int acquire_write (void)
 Acquire lock ownership (wait on queue if necessary). More...

int tryacquire_read (void)
 Conditionally acquire a lock (i.e., won't block). More...

int tryacquire_write (void)
 Conditionally acquire a lock (i.e., won't block). More...

int tryacquire_write_upgrade (void)
 This is only here for consistency with the other synchronization APIs and usability with Lock adapters. More...

const ACE_mutex_t & lock (void) const
 Return the underlying mutex. More...

void dump (void) const
 Dump the state of an object. More...


Public Attributes

 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks. More...


Private Methods

const ACE_TCHARunique_name (void)
 Create and return the unique name. More...


Private Attributes

ACE_TCHAR name_ [ACE_UNIQUE_NAME_LEN]
 If the user does not provide a name we generate a unique name in this buffer. More...

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.


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

void ACE_Process_Mutex::dump void    const
 

Dump the state of an object.

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:
Generated on Fri Nov 22 06:02:01 2002 for ACE by doxygen1.2.13.1 written by Dimitri van Heesch, © 1997-2001