vrpn 07.35
Virtual Reality Peripheral Network
Loading...
Searching...
No Matches
vrpn_PeerMutex Class Reference

vrpn_PeerMutex More...

#include <vrpn_Mutex.h>

Collaboration diagram for vrpn_PeerMutex:

Classes

struct  mutexCallback
 
struct  peerData
 

Public Member Functions

 vrpn_PeerMutex (const char *name, int port, const char *NICaddress=NULL)
 This constructor opens a new connection/port for the mutex.
 
 ~vrpn_PeerMutex (void)
 If isHeldLocally(), calls release().
 
vrpn_bool isAvailable (void) const
 True from when release() is called or we receive a release message from another process until request() is called or we grant the lock to another process in response to its request message.
 
vrpn_bool isHeldLocally (void) const
 True from when RequestGranted callbacks are triggered until release() is called.
 
vrpn_bool isHeldRemotely (void) const
 True from when we grant the lock to another process in response to its request message until we receive a release message from another process.
 
int numPeers (void) const
 
void mainloop (void)
 
void request (void)
 Request the distributed lock. Does not request the lock if !isAvailable(), instead automatically triggering DeniedCallbacks.
 
void release (void)
 Release the distributed lock. Does nothing if !isHeldLocally() and there isn't a request pending.
 
vrpn_bool addPeer (const char *stationName)
 Takes a VRPN station name of the form "<host>:<port>".
 
vrpn_bool addRequestGrantedCallback (void *userdata, int(*)(void *))
 These callbacks are triggered when OUR request is granted.
 
vrpn_bool addRequestDeniedCallback (void *userdata, int(*)(void *))
 These callbacks are triggered when OUR request is denied.
 
vrpn_bool addTakeCallback (void *userdata, int(*)(void *))
 These callbacks are triggered when ANY peer gets the mutex. (If several peers are competing for the mutex, and the implementation issues multiple "grants", these callbacks will only be triggered once between triggerings of ReleaseCallbacks.)
 
vrpn_bool addReleaseCallback (void *userdata, int(*)(void *))
 These callbacks are triggered when ANY peer releases the mutex.
 

Protected Types

enum  state { OURS , REQUESTING , AVAILABLE , HELD_REMOTELY }
 

Protected Member Functions

void sendRequest (vrpn_Connection *)
 
void sendRelease (vrpn_Connection *)
 
void sendGrantRequest (vrpn_Connection *, vrpn_uint32 IPnumber, vrpn_uint32 PortNumber)
 
void sendDenyRequest (vrpn_Connection *, vrpn_uint32 IPnumber, vrpn_uint32 PortNumber)
 
void triggerGrantCallbacks (void)
 
void triggerDenyCallbacks (void)
 
void triggerTakeCallbacks (void)
 
void triggerReleaseCallbacks (void)
 
void checkGrantMutex (void)
 
void init (const char *name)
 
 vrpn_PeerMutex (const char *name, vrpn_Connection *c)
 This constructor reuses a SERVER connection for the mutex. BUG BUG BUG - do not use this constructor; it does not reliably resolve race conditions.
 

Static Protected Member Functions

static int VRPN_CALLBACK handle_request (void *, vrpn_HANDLERPARAM)
 
static int VRPN_CALLBACK handle_release (void *, vrpn_HANDLERPARAM)
 
static int VRPN_CALLBACK handle_grantRequest (void *, vrpn_HANDLERPARAM)
 
static int VRPN_CALLBACK handle_denyRequest (void *, vrpn_HANDLERPARAM)
 
static int VRPN_CALLBACK handle_losePeer (void *, vrpn_HANDLERPARAM)
 

Protected Attributes

char * d_mutexName
 
state d_state
 
int d_numPeersGrantingLock
 Counts the number of "grants" we've received after issuing a request; when this reaches d_numPeers, the lock is ours.
 
vrpn_Connectiond_server
 Receive on this connection.
 
vrpn_Connection ** d_peer
 Send on these connections to other Mutex's well-known-ports.
 
int d_numPeers
 
int d_numConnectionsAllocated
 Dynamic array size for d_peer and d_peerGrantedLock.
 
vrpn_uint32 d_myIP
 
vrpn_uint32 d_myPort
 
vrpn_uint32 d_holderIP
 
vrpn_int32 d_holderPort
 
vrpn_int32 d_myId
 
vrpn_int32 d_request_type
 
vrpn_int32 d_release_type
 
vrpn_int32 d_grantRequest_type
 
vrpn_int32 d_denyRequest_type
 
mutexCallbackd_reqGrantedCB
 
mutexCallbackd_reqDeniedCB
 
mutexCallbackd_takeCB
 
mutexCallbackd_releaseCB
 
peerDatad_peerData
 Needed only to clean up when a peer shuts down (mid-request). It isn't currently feasible to have all this data, so instead we abort requests that were interrupted by a shutdown.
 

Detailed Description

vrpn_PeerMutex

This class provides distributed mutual exclusion between every instance with the same name for which addPeer() has been called. If a process calls request() when isAvailable() returns true, the mutex will attempt to secure a lock to whatever resource it is governing; either RequestGranted or RequestDenied callbacks will be triggered. If RequestGranted callbacks are triggered, the process has the lock until it explicitly calls release() (and can verify this by checking isHeldLocally()). Once the lock-owner calls release(), Release callbacks at every peer will be triggered.

Like most vrpn classes, the mainloop() must be called frequently.

Note that none of isAvailable(), isHeldLocally(), and isHeldRemotely() are true between when request() is called and either RequestGranted or RequestDenied callbacks are triggered.

Definition at line 196 of file vrpn_Mutex.h.

Member Enumeration Documentation

◆ state

enum vrpn_PeerMutex::state
protected
Enumerator
OURS 
REQUESTING 
AVAILABLE 
HELD_REMOTELY 

Definition at line 251 of file vrpn_Mutex.h.

Constructor & Destructor Documentation

◆ vrpn_PeerMutex() [1/2]

vrpn_PeerMutex::vrpn_PeerMutex ( const char * name,
int port,
const char * NICaddress = NULL )

This constructor opens a new connection/port for the mutex.

Definition at line 779 of file vrpn_Mutex.C.

References vrpn_Connection::addReference(), d_server, init(), vrpn_Connection::setAutoDeleteStatus(), and vrpn_create_server_connection().

Here is the call graph for this function:

◆ ~vrpn_PeerMutex()

vrpn_PeerMutex::~vrpn_PeerMutex ( void )

If isHeldLocally(), calls release().

Definition at line 851 of file vrpn_Mutex.C.

References d_mutexName, d_numPeers, d_peer, d_server, isHeldLocally(), release(), and vrpn_Connection::removeReference().

Here is the call graph for this function:

◆ vrpn_PeerMutex() [2/2]

vrpn_PeerMutex::vrpn_PeerMutex ( const char * name,
vrpn_Connection * c )
protected

This constructor reuses a SERVER connection for the mutex. BUG BUG BUG - do not use this constructor; it does not reliably resolve race conditions.

Definition at line 819 of file vrpn_Mutex.C.

References vrpn_Connection::addReference(), d_server, and init().

Here is the call graph for this function:

Member Function Documentation

◆ addPeer()

vrpn_bool vrpn_PeerMutex::addPeer ( const char * stationName)

◆ addReleaseCallback()

vrpn_bool vrpn_PeerMutex::addReleaseCallback ( void * userdata,
int(*)(void *) f )

These callbacks are triggered when ANY peer releases the mutex.

Definition at line 1120 of file vrpn_Mutex.C.

References d_releaseCB, vrpn_PeerMutex::mutexCallback::f, vrpn_PeerMutex::mutexCallback::next, and vrpn_PeerMutex::mutexCallback::userdata.

◆ addRequestDeniedCallback()

vrpn_bool vrpn_PeerMutex::addRequestDeniedCallback ( void * userdata,
int(*)(void *) f )

These callbacks are triggered when OUR request is denied.

Definition at line 1086 of file vrpn_Mutex.C.

References d_reqDeniedCB, vrpn_PeerMutex::mutexCallback::f, vrpn_PeerMutex::mutexCallback::next, and vrpn_PeerMutex::mutexCallback::userdata.

◆ addRequestGrantedCallback()

vrpn_bool vrpn_PeerMutex::addRequestGrantedCallback ( void * userdata,
int(*)(void *) f )

These callbacks are triggered when OUR request is granted.

Definition at line 1069 of file vrpn_Mutex.C.

References d_reqGrantedCB, vrpn_PeerMutex::mutexCallback::f, vrpn_PeerMutex::mutexCallback::next, and vrpn_PeerMutex::mutexCallback::userdata.

◆ addTakeCallback()

vrpn_bool vrpn_PeerMutex::addTakeCallback ( void * userdata,
int(*)(void *) f )

These callbacks are triggered when ANY peer gets the mutex. (If several peers are competing for the mutex, and the implementation issues multiple "grants", these callbacks will only be triggered once between triggerings of ReleaseCallbacks.)

Definition at line 1103 of file vrpn_Mutex.C.

References d_takeCB, vrpn_PeerMutex::mutexCallback::f, vrpn_PeerMutex::mutexCallback::next, and vrpn_PeerMutex::mutexCallback::userdata.

◆ checkGrantMutex()

void vrpn_PeerMutex::checkGrantMutex ( void )
protected

Definition at line 1436 of file vrpn_Mutex.C.

References d_numPeers, d_numPeersGrantingLock, d_state, OURS, REQUESTING, triggerGrantCallbacks(), and triggerTakeCallbacks().

Referenced by handle_grantRequest(), mainloop(), and request().

Here is the call graph for this function:

◆ handle_denyRequest()

int vrpn_PeerMutex::handle_denyRequest ( void * userdata,
vrpn_HANDLERPARAM p )
staticprotected

Definition at line 1259 of file vrpn_Mutex.C.

References vrpn_HANDLERPARAM::buffer, d_myIP, d_myPort, d_numPeersGrantingLock, d_state, HELD_REMOTELY, triggerDenyCallbacks(), and vrpn_unbuffer().

Referenced by init().

Here is the call graph for this function:

◆ handle_grantRequest()

int vrpn_PeerMutex::handle_grantRequest ( void * userdata,
vrpn_HANDLERPARAM p )
staticprotected

Definition at line 1226 of file vrpn_Mutex.C.

References vrpn_HANDLERPARAM::buffer, checkGrantMutex(), d_myIP, d_myPort, d_numPeersGrantingLock, and vrpn_unbuffer().

Referenced by init().

Here is the call graph for this function:

◆ handle_losePeer()

int vrpn_PeerMutex::handle_losePeer ( void * userdata,
vrpn_HANDLERPARAM  )
staticprotected

Definition at line 1291 of file vrpn_Mutex.C.

References d_numPeers, d_peer, d_state, release(), vrpn_Connection::removeReference(), and REQUESTING.

Referenced by addPeer().

Here is the call graph for this function:

◆ handle_release()

int vrpn_PeerMutex::handle_release ( void * userdata,
vrpn_HANDLERPARAM p )
staticprotected

Definition at line 1191 of file vrpn_Mutex.C.

References AVAILABLE, vrpn_HANDLERPARAM::buffer, d_holderIP, d_holderPort, d_state, triggerReleaseCallbacks(), and vrpn_unbuffer().

Referenced by init().

Here is the call graph for this function:

◆ handle_request()

int vrpn_PeerMutex::handle_request ( void * userdata,
vrpn_HANDLERPARAM p )
staticprotected

◆ init()

◆ isAvailable()

vrpn_bool vrpn_PeerMutex::isAvailable ( void ) const

True from when release() is called or we receive a release message from another process until request() is called or we grant the lock to another process in response to its request message.

Definition at line 898 of file vrpn_Mutex.C.

References AVAILABLE, and d_state.

Referenced by request().

◆ isHeldLocally()

vrpn_bool vrpn_PeerMutex::isHeldLocally ( void ) const

True from when RequestGranted callbacks are triggered until release() is called.

Definition at line 903 of file vrpn_Mutex.C.

References d_state, and OURS.

Referenced by release(), and ~vrpn_PeerMutex().

◆ isHeldRemotely()

vrpn_bool vrpn_PeerMutex::isHeldRemotely ( void ) const

True from when we grant the lock to another process in response to its request message until we receive a release message from another process.

Definition at line 908 of file vrpn_Mutex.C.

References d_state, and HELD_REMOTELY.

◆ mainloop()

void vrpn_PeerMutex::mainloop ( void )

Definition at line 915 of file vrpn_Mutex.C.

References checkGrantMutex(), d_numPeers, d_peer, d_server, and vrpn_Connection::mainloop().

Here is the call graph for this function:

◆ numPeers()

int vrpn_PeerMutex::numPeers ( void ) const

Definition at line 913 of file vrpn_Mutex.C.

References d_numPeers.

◆ release()

void vrpn_PeerMutex::release ( void )

Release the distributed lock. Does nothing if !isHeldLocally() and there isn't a request pending.

Definition at line 973 of file vrpn_Mutex.C.

References AVAILABLE, d_holderIP, d_holderPort, d_numPeers, d_peer, d_state, isHeldLocally(), sendRelease(), and triggerReleaseCallbacks().

Referenced by handle_losePeer(), and ~vrpn_PeerMutex().

Here is the call graph for this function:

◆ request()

void vrpn_PeerMutex::request ( void )

Request the distributed lock. Does not request the lock if !isAvailable(), instead automatically triggering DeniedCallbacks.

Definition at line 927 of file vrpn_Mutex.C.

References checkGrantMutex(), d_holderIP, d_holderPort, d_myIP, d_myPort, d_numPeers, d_numPeersGrantingLock, d_peer, d_state, isAvailable(), REQUESTING, sendRequest(), and triggerDenyCallbacks().

Here is the call graph for this function:

◆ sendDenyRequest()

void vrpn_PeerMutex::sendDenyRequest ( vrpn_Connection * c,
vrpn_uint32 IPnumber,
vrpn_uint32 PortNumber )
protected

◆ sendGrantRequest()

void vrpn_PeerMutex::sendGrantRequest ( vrpn_Connection * c,
vrpn_uint32 IPnumber,
vrpn_uint32 PortNumber )
protected

◆ sendRelease()

void vrpn_PeerMutex::sendRelease ( vrpn_Connection * c)
protected

◆ sendRequest()

void vrpn_PeerMutex::sendRequest ( vrpn_Connection * c)
protected

◆ triggerDenyCallbacks()

void vrpn_PeerMutex::triggerDenyCallbacks ( void )
protected

◆ triggerGrantCallbacks()

void vrpn_PeerMutex::triggerGrantCallbacks ( void )
protected

◆ triggerReleaseCallbacks()

void vrpn_PeerMutex::triggerReleaseCallbacks ( void )
protected

◆ triggerTakeCallbacks()

void vrpn_PeerMutex::triggerTakeCallbacks ( void )
protected

Member Data Documentation

◆ d_denyRequest_type

vrpn_int32 vrpn_PeerMutex::d_denyRequest_type
protected

Definition at line 279 of file vrpn_Mutex.h.

Referenced by init().

◆ d_grantRequest_type

vrpn_int32 vrpn_PeerMutex::d_grantRequest_type
protected

Definition at line 278 of file vrpn_Mutex.h.

Referenced by init().

◆ d_holderIP

vrpn_uint32 vrpn_PeerMutex::d_holderIP
protected

Definition at line 272 of file vrpn_Mutex.h.

Referenced by handle_release(), handle_request(), release(), and request().

◆ d_holderPort

vrpn_int32 vrpn_PeerMutex::d_holderPort
protected

Definition at line 273 of file vrpn_Mutex.h.

Referenced by handle_release(), handle_request(), release(), and request().

◆ d_mutexName

char* vrpn_PeerMutex::d_mutexName
protected

◆ d_myId

vrpn_int32 vrpn_PeerMutex::d_myId
protected

Definition at line 275 of file vrpn_Mutex.h.

Referenced by init().

◆ d_myIP

vrpn_uint32 vrpn_PeerMutex::d_myIP
protected

◆ d_myPort

vrpn_uint32 vrpn_PeerMutex::d_myPort
protected

◆ d_numConnectionsAllocated

int vrpn_PeerMutex::d_numConnectionsAllocated
protected

Dynamic array size for d_peer and d_peerGrantedLock.

Definition at line 267 of file vrpn_Mutex.h.

Referenced by addPeer().

◆ d_numPeers

int vrpn_PeerMutex::d_numPeers
protected

◆ d_numPeersGrantingLock

int vrpn_PeerMutex::d_numPeersGrantingLock
protected

Counts the number of "grants" we've received after issuing a request; when this reaches d_numPeers, the lock is ours.

Definition at line 257 of file vrpn_Mutex.h.

Referenced by checkGrantMutex(), handle_denyRequest(), handle_grantRequest(), and request().

◆ d_peer

vrpn_Connection** vrpn_PeerMutex::d_peer
protected

Send on these connections to other Mutex's well-known-ports.

Definition at line 263 of file vrpn_Mutex.h.

Referenced by addPeer(), handle_losePeer(), handle_request(), mainloop(), release(), request(), and ~vrpn_PeerMutex().

◆ d_peerData

peerData* vrpn_PeerMutex::d_peerData
protected

Needed only to clean up when a peer shuts down (mid-request). It isn't currently feasible to have all this data, so instead we abort requests that were interrupted by a shutdown.

Definition at line 322 of file vrpn_Mutex.h.

Referenced by addPeer().

◆ d_release_type

vrpn_int32 vrpn_PeerMutex::d_release_type
protected

Definition at line 277 of file vrpn_Mutex.h.

Referenced by init().

◆ d_releaseCB

mutexCallback* vrpn_PeerMutex::d_releaseCB
protected

Definition at line 314 of file vrpn_Mutex.h.

Referenced by addReleaseCallback(), and triggerReleaseCallbacks().

◆ d_reqDeniedCB

mutexCallback* vrpn_PeerMutex::d_reqDeniedCB
protected

Definition at line 312 of file vrpn_Mutex.h.

Referenced by addRequestDeniedCallback(), and triggerDenyCallbacks().

◆ d_reqGrantedCB

mutexCallback* vrpn_PeerMutex::d_reqGrantedCB
protected

Definition at line 311 of file vrpn_Mutex.h.

Referenced by addRequestGrantedCallback(), and triggerGrantCallbacks().

◆ d_request_type

vrpn_int32 vrpn_PeerMutex::d_request_type
protected

Definition at line 276 of file vrpn_Mutex.h.

Referenced by init().

◆ d_server

vrpn_Connection* vrpn_PeerMutex::d_server
protected

Receive on this connection.

Definition at line 261 of file vrpn_Mutex.h.

Referenced by init(), mainloop(), vrpn_PeerMutex(), vrpn_PeerMutex(), and ~vrpn_PeerMutex().

◆ d_state

◆ d_takeCB

mutexCallback* vrpn_PeerMutex::d_takeCB
protected

Definition at line 313 of file vrpn_Mutex.h.

Referenced by addTakeCallback(), and triggerTakeCallbacks().


The documentation for this class was generated from the following files: