CascadeSemLock Class Reference

an easy to use process semaphore-lock More...

#include <cascade/interprocess/CascadeSemLock.h>

Inheritance diagram for CascadeSemLock:

List of all members.

Public Member Functions
	CascadeSemLock ()
virtual	~CascadeSemLock ()
bool	Open (const char *pName, bool bCreateIfNecessary)
bool	Close ()
bool	Lock ()
bool	Unlock ()
bool	IsLocked ()
bool	GetInstanceCount (u32 &nInstanceCountToSet)

---

Detailed Description

an easy to use process semaphore-lock

Skip the description

CascadeSemLock provides a locking mechanism that protects access to resources that are shared across processes. CascadeSemLock is built on top of System V semaphores.

Note: to protect access to resources that are shared among threads of the same process, use a CascadeMutex, not a CascadeSemLock.

To use CascadeSemLocks in multiple threads of the same process, (either as a heavyweight mutex among the threads, or because multiple threads want to synchronize with an external process), then make sure that each thread has its own instance of a CascadeSemLock opened to the same named semaphore lock. (i.e. Don't be fooled into thinking these process safe objects are also thread-safe!!!).

REMINDER: DON'T EVER SHARE THE SAME INSTANCE OF A SEMLOCK CLASS BETWEEN THREADS. DO USE DIFFERENT CLASS INSTANCES OPENED TO THE SAME NAME. (If you must).

---

class CascadeSemLock

---

Constructor & Destructor Documentation

CascadeSemLock::CascadeSemLock (   )

the default constructor - lightweight This default constructor is lightweight.

virtual CascadeSemLock::~CascadeSemLock (   )  [virtual]

destructor This destructor will unlock and close the SemLock if necessary.

---

Member Function Documentation

bool CascadeSemLock::Close (   )

closes the SemLock Call Close() to close a previously opened semaphore lock. When the last handle to a named semaphore lock is closed, the operating system semaphore lock object is destroyed. This function is provided for convenience - the destructor ~CascadeSemLock() will automatically Close() the semaphore lock if it is still open when the destructor is called. Close() will automatically unlock the semaphore if it is locked, but good programming practice dictates that you should unlock the semlock yourself as soon as you are done with it. Returns: whether or not the SemLock was closed successfully See also: Open() ~CascadeSemLock()

bool CascadeSemLock::GetInstanceCount (  u32 &  nInstanceCountToSet  )

returns the number of CascadeSemLock instances across processes that have the named SemLock open GetInstanceCount() sets nInstanceCountToSet with the number of instances of the CascadeSemLock class across processes that currently have the named sem lock open returning true if successful, false otherwise. Note: You must have the SemLock open and locked when you call this function. If the semlock is not open and locked when this function is called it will return false. The smallest number that nInstanceCountToSet will ever be set to is 1. (This instance). Parameters: nInstanceCountToSet  the variable to set with the instance count Returns: whether or not the instance count was set See also: Open(), Lock()

bool CascadeSemLock::IsLocked (   )

determines whether or not the SemLock is locked IsLocked() returns true if the semlock is open and locked, false otherwise. Returns: whether or not this SemLock instance is currently locked See also: Lock(), Unlock()

bool CascadeSemLock::Lock (   )

locks the SemLock Call Lock() to lock the semaphore lock. If the calling process does not already own the semaphore lock, the calling process will block until the semaphore can be locked. Lock() returns true on successful locking, false otherwise. Returns: whether or not the SemLock was locked successfully See also: Unlock()

bool CascadeSemLock::Open (  const char *  pName, bool  bCreateIfNecessary )

opens a named semaphore lock Call Open() to open a handle to the named semaphore lock named pName. Open() will create the named semaphore lock if it doesn't already exist and bCreateIfNecessary is true. Open() returns true on success, false on failure. Parameters: pName  the name of the SemLock to open bCreateIfNecessary  whether or not the SemLock should be created if it does not already exist Returns: whether or not the SemLock was opened successfully See also: Close()

bool CascadeSemLock::Unlock (   )

unlock the SemLock Call Unlock() to release the lock. Locks may nest so be sure there is a corresponding call to Unlock() for every call to Lock(). Returns: whether or not the SemLock was unlocked successfully See also: Lock() ~CascadeSemLock()

---

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

• CascadeSemLock.h

---