.TH ACE_Process_Mutex 3 "1 Dec 2001" "ACE" \" -*- nroff -*-
.ad l
.nh
.SH NAME
ACE_Process_Mutex \- A wrapper for mutexes that can be used across processes on the same host machine, as well as within a process, of course. 
.SH SYNOPSIS
.br
.PP
\fC#include <Process_Mutex.h>\fR
.PP
.SS Public Methods

.in +1c
.ti -1c
.RI "\fBACE_Process_Mutex\fR (const char *name = 0, void *arg = 0)"
.br
.ti -1c
.RI "\fBACE_Process_Mutex\fR (const wchar_t *name, void *arg = 0)"
.br
.ti -1c
.RI "\fB~ACE_Process_Mutex\fR (void)"
.br
.ti -1c
.RI "int \fBremove\fR (void)"
.br
.ti -1c
.RI "int \fBacquire\fR (void)"
.br
.ti -1c
.RI "int \fBacquire\fR (\fBACE_Time_Value\fR &tv)"
.br
.ti -1c
.RI "int \fBtryacquire\fR (void)"
.br
.ti -1c
.RI "int \fBrelease\fR (void)"
.br
.RI "\fIRelease lock and unblock a thread at head of queue.\fR"
.ti -1c
.RI "int \fBacquire_read\fR (void)"
.br
.RI "\fIAcquire lock ownership (wait on queue if necessary).\fR"
.ti -1c
.RI "int \fBacquire_write\fR (void)"
.br
.RI "\fIAcquire lock ownership (wait on queue if necessary).\fR"
.ti -1c
.RI "int \fBtryacquire_read\fR (void)"
.br
.ti -1c
.RI "int \fBtryacquire_write\fR (void)"
.br
.ti -1c
.RI "int \fBtryacquire_write_upgrade\fR (void)"
.br
.ti -1c
.RI "const ACE_mutex_t& \fBlock\fR (void) const"
.br
.RI "\fIReturn the underlying mutex.\fR"
.ti -1c
.RI "void \fBdump\fR (void) const"
.br
.RI "\fIDump the state of an object.\fR"
.in -1c
.SS Public Attributes

.in +1c
.ti -1c
.RI "\fBACE_ALLOC_HOOK_DECLARE\fR"
.br
.RI "\fIDeclare the dynamic allocation hooks.\fR"
.in -1c
.SS Private Attributes

.in +1c
.ti -1c
.RI "\fBACE_Mutex\fR \fBlock_\fR"
.br
.in -1c
.SH DETAILED DESCRIPTION
.PP 
A wrapper for mutexes that can be used across processes on the same host machine, as well as within a process, of course.
.PP
.PP
 
.PP
\fBAttention: \fR
.in +1c
 The mechanism upon which \fCACE_Process_Mutex\fR is based can be configured at build time to be either \fC\fBACE_SV_Semaphore_Complex\fR\fR (on platforms that support it) or \fC\fBACE_Mutex\fR\fR. On platforms that require interprocess mutexes be allocated from shared memory (Pthreads and UI Threads are examples), \fC\fBACE_SV_Semaphore_Complex\fR\fR provides a more reliable mechanism for implementing inter-process mutex than \fC\fBACE_Mutex\fR\fR. However, at least on some platforms, \fC\fBACE_SV_Semaphore_Complex\fR\fR is limited to a small number of objects by the underlying System V IPC kernel parameters. If you want to force use of \fC\fBACE_Mutex\fR\fR as the underlying mechanism, set \fCACE_USES_MUTEX_FOR_PROCESS_MUTEX\fR in your \fCconfig.h\fR file. Also, if you require the ability to do a timed \fC\fBacquire\fR()\fR, you must set \fCACE_USES_MUTEX_FOR_PROCESS_MUTEX\fR, as timed acquire does not work with System V semaphores. 
.PP
.SH CONSTRUCTOR & DESTRUCTOR DOCUMENTATION
.PP 
.SS ACE_Process_Mutex::ACE_Process_Mutex (const char * name = 0, void * arg = 0)
.PP
Create a Process_Mutex, passing in the optional \fCname\fR.
.PP
\fBParameters: \fR
.in +1c
.TP
\fB\fIname\fR\fR optional, null-terminated string containing the name of the object. Multiple users of the same \fCACE_Process_Mutex\fR must use the same name to access the same object. If not specified, a name is generated. 
.TP
\fB\fIarg\fR\fR optional, attributes to be used to initialize the mutex. If using \fC\fBACE_SV_Semaphore_Complex\fR\fR as the underlying mechanism, this argument is ignored. 
.SS ACE_Process_Mutex::ACE_Process_Mutex (const wchar_t * name, void * arg = 0)
.PP
Create a Process_Mutex, passing in the optional \fCname\fR. (\fCwchar_t\fR version)
.PP
\fBParameters: \fR
.in +1c
.TP
\fB\fIname\fR\fR optional, null-terminated string containing the name of the object. Multiple users of the same \fCACE_Process_Mutex\fR must use the same name to access the same object. If not specified, a name is generated. 
.TP
\fB\fIarg\fR\fR optional, attributes to be used to initialize the mutex. If using \fC\fBACE_SV_Semaphore_Complex\fR\fR as the underlying mechanism, this argument is ignored. 
.SS ACE_Process_Mutex::~ACE_Process_Mutex (void)
.PP
.SH MEMBER FUNCTION DOCUMENTATION
.PP 
.SS int ACE_Process_Mutex::acquire (\fBACE_Time_Value\fR & tv)
.PP
Acquire lock ownership, but timeout if lock if hasn't been acquired by given time.
.PP
\fBParameters: \fR
.in +1c
.TP
\fB\fItv\fR\fR the absolute time until which the caller is willing to wait to acquire the lock.
.PP
\fBReturns: \fR
.in +1c
 0 on success; -1 on failure. 
.SS int ACE_Process_Mutex::acquire (void)
.PP
Acquire lock ownership (wait on queue if necessary).
.PP
\fBReturns: \fR
.in +1c
 0 on success; -1 on failure. 
.SS int ACE_Process_Mutex::acquire_read (void)
.PP
Acquire lock ownership (wait on queue if necessary).
.PP
.SS int ACE_Process_Mutex::acquire_write (void)
.PP
Acquire lock ownership (wait on queue if necessary).
.PP
.SS void ACE_Process_Mutex::dump (void) const
.PP
Dump the state of an object.
.PP
.SS const ACE_mutex_t & ACE_Process_Mutex::lock (void) const
.PP
Return the underlying mutex.
.PP
.SS int ACE_Process_Mutex::release (void)
.PP
Release lock and unblock a thread at head of queue.
.PP
.SS int ACE_Process_Mutex::remove (void)
.PP
Explicitly destroy the mutex. Note that only one thread should call this method since it doesn't protect against race conditions.
.PP
\fBReturns: \fR
.in +1c
 0 on success; -1 on failure. 
.SS int ACE_Process_Mutex::tryacquire (void)
.PP
Conditionally acquire lock (i.e., don't wait on queue).
.PP
\fBReturns: \fR
.in +1c
 0 on success; -1 on failure. If the lock could not be acquired because someone else already had the lock, \fCerrno\fR is set to \fCEBUSY\fR. 
.SS int ACE_Process_Mutex::tryacquire_read (void)
.PP
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>. 
.SS int ACE_Process_Mutex::tryacquire_write (void)
.PP
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>. 
.SS int ACE_Process_Mutex::tryacquire_write_upgrade (void)
.PP
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. 
.SH MEMBER DATA DOCUMENTATION
.PP 
.SS ACE_Process_Mutex::ACE_ALLOC_HOOK_DECLARE
.PP
Declare the dynamic allocation hooks.
.PP
.SS \fBACE_Mutex\fR ACE_Process_Mutex::lock_\fC [private]\fR
.PP


.SH AUTHOR
.PP 
Generated automatically by Doxygen for ACE from the source code.