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>
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.
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.
int ACE_Process_Mutex::acquire |
( |
void |
| ) |
|
|
inline |
Acquire lock ownership (wait on queue if necessary).
- Returns
- 0 on success; -1 on failure.
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.
const ACE_TCHAR * ACE_Process_Mutex::name |
( |
void |
| ) |
const |
|
inline |
Get the name used for the lock, or null if no name is used.
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.
int ACE_Process_Mutex::unlink |
( |
const ACE_TCHAR * |
name | ) |
|
|
static |
If a file was created as the underlying storage for the mutex, remove it from the filesystem.
ACE_Process_Mutex::ACE_ALLOC_HOOK_DECLARE |
Declare the dynamic allocation hooks.
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: