mbo::CPotentialLock Class Reference

Lock that might be entered. More...

#include <MboSynch.h>

Inheritance diagram for mbo::CPotentialLock:

[legend]

Collaboration diagram for mbo::CPotentialLock:

[legend]

List of all members.

Public Member Functions
	CPotentialLock (const IMutex *pmx, DWORD nMilliseconds=0, bool bThrowAlreadyEntered=true) throw ( logic_error , CAlreadyEntered )
	CPotentialLock (const CPotentialLock &lx) throw ( logic_error , CAlreadyEntered )
virtual	~CPotentialLock () throw ( logic_error )
virtual bool	IsValid () const
virtual void	Enter () const
virtual void	Leave () const throw ( logic_error )
virtual unsigned long	GetLevel () const
Protected Member Functions
virtual void	Enter (DWORD nMilliseconds, bool bThrowAlreadyEntered=true) const throw ( logic_error , CAlreadyEntered )

---

Detailed Description

Lock that might be entered.

This lock operates on a Mutex rather than a CriticalSection hence it is recognizeable slower than using normal locks with CriticalSections.

This lock tries to enter the mutex. If entering fails IsValid() will return false. For a valid lock IsValid() will even return true if it is temporarily unlocked with an CUnlock. Thus IsValid() does not say anything about the enter level of the underlying mutex.

The lock can operate in two ways. First setting bThrowAlreadyEntered true results in throwing an exception of type CAlreadyEntered once when the constructor cannot enter the mutex in the specified time. Therefor the block in which the lock is being initalized automatically gets destructed and no operation with the underlying mutex being unentered is possible. In contrast setting bThrowAlreadyEntered false does not terminate that stackframe and hence requires the user to check IsValid() before continuing. Thus the second is dangerous and not recommended - however it allows to omit the try/catch block and can therefor be much faster (which is the reason for its existence).

Definition at line 544 of file MboSynch.h.

---

Constructor & Destructor Documentation

mbo::CPotentialLock::CPotentialLock	(	const IMutex *	pmx,
		DWORD	nMilliseconds = 0,
		bool	bThrowAlreadyEntered = true
	)			throw ( logic_error , CAlreadyEntered ) [inline, explicit]

constructor to allow selective call to Enter()

/*! default constructor which directly calls Enter()

Parameters:

	pmx	Mutex to use for Lock
	nMilliseconds	time to try to enter in milliseconds
	bThrowAlreadyEntered	throws an exception if another thread has entered the mutex already

Exceptions:

	CAlreadyLocked	if another thread has entered the mutex already and parameter bThrowAlreadyEntered is set true.
	logic_error	if mutex was not entered in constructor

Definition at line 562 of file MboSynch.h.

        : m_pmx(const_cast<IMutex*>(pmx))
    {
        assert(pmx);
        Enter(nMilliseconds, bThrowAlreadyEntered);
    }

mbo::CPotentialLock::CPotentialLock

(

const CPotentialLock &

lx

)

throw ( logic_error , CAlreadyEntered ) [inline, explicit]

copy constructor

Ensure the lock is entered since the destructor will call Leave().

Parameters:

lx

reference to lock to be copied

Exceptions:

	CAlreadyLocked	if another thread has entered the mutex already and parameter bThrowAlreadyEntered is set true.
	logic_error	if mutex was not entered in constructor

Definition at line 583 of file MboSynch.h.

        : m_pmx(lx.m_pmx)
    {
        if (m_pmx)
        {
            Enter(INFINITE, true);
        }
    }

virtual mbo::CPotentialLock::~CPotentialLock

(

)

throw ( logic_error ) [inline, virtual]

destructor

Exceptions:

logic_error

if mutex was not entered in constructor

Definition at line 597 of file MboSynch.h.

    {
        // Otherwise destructor would throw an exception. Since that might 
        // happen in an exception handler that would lead to an unconditious 
        // termination.
        if (m_pmx) 
        {
            Leave();
        }
    }

---

Member Function Documentation

virtual bool mbo::CPotentialLock::IsValid

(

)

const [inline, virtual]

Returns:

whether lock is valid (not entered)

Definition at line 610 of file MboSynch.h.

    {
        return m_pmx ? true : false;
    }

virtual void mbo::CPotentialLock::Enter	(	DWORD	nMilliseconds,
		bool	bThrowAlreadyEntered = true
	)			const throw ( logic_error , CAlreadyEntered ) [inline, protected, virtual]

enter the Lock

Parameters:

	nMilliseconds	time to try to enter in milliseconds
	bThrowAlreadyEntered	throws an exception if another thread has entered the mutex already

Exceptions:

	CAlreadyLocked	if another thread has entered the mutex already and parameter bThrowAlreadyEntered is set true.
	logic_error	if mutex was not entered in constructor

Note:

is compatible with CUnlock as long as its destructor calls this Enter() method with parameter nMilliseconds set to INFINITE.

Definition at line 630 of file MboSynch.h.

    {
        if (!m_pmx)
        {
            throw logic_error("CPotentialLock is invalid");
        }
        if (!m_pmx->Try(nMilliseconds))
        {
            m_pmx = NULL;
            if (bThrowAlreadyEntered)
            {
                throw CAlreadyEntered();
            }
        }
    }

virtual void mbo::CPotentialLock::Enter

(

)

const [inline, virtual]

default enter lock implements ILock::Enter()

Implements mbo::ILock.

Definition at line 654 of file MboSynch.h.

    {
        Enter(INFINITE,true);
    }

virtual void mbo::CPotentialLock::Leave

(

)

const throw ( logic_error ) [inline, virtual]

leave the Lock

Exceptions:

logic_error

if mutex was not entered in constructor

Implements mbo::ILock.

Definition at line 662 of file MboSynch.h.

    {
        if (!m_pmx)
        {
            throw logic_error("CPotentialLock is invalid");
        }
        m_pmx->Leave();
    }

virtual unsigned long mbo::CPotentialLock::GetLevel

(

)

const [inline, virtual]

Returns:

Number of times CriticalSection/Mutex is entered

Note:

This is only valie when the CriticalSection/Mutex is owned by the current thread.

This may not be correctly available in which case 1 is returned to signal Enter state.

Implements mbo::ILock.

Definition at line 672 of file MboSynch.h.

    {
        return m_pmx ? m_pmx->GetLevel() : 0;
    }

---

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

• MboSynch.h

---