IlsSafeMutex Class Reference

API FOR ADVANCED USERS – A mutex is an object that provides mutually exclusive access to the object. A mutex is one of the basic building blocks of a multithreaded application. More...

#include <ilserver/ilthread.h>

Inheritance diagram for IlsSafeMutex:

Public Member Functions
	IlsSafeMutex (IlsBoolean check=IlsFalse, IlsBoolean wantTrylock=IlsFalse)
	Constructor. More...
long	count () const
	This member function returns the number of times the mutex has been locked by the owner thread. More...
IlsSafeMutexLockResult	lock ()
	This member function locks the mutex. More...
IlsSafeMutexLockResult	trylock ()
	This member function tries to lock the mutex. More...
IlsSafeMutexUnlockResult	unlock ()
	This member function unlocks the mutex. More...
Public Member Functions inherited from IlsMTBase
virtual	~IlsMTBase ()
	This is the public virtual destructor for this class.
virtual IlsThreadObjectName	getName () const
	This member function returns the name of an object. More...

Friends
ostream &	operator<< (ostream &, const IlsSafeMutex &)
	This operator prints the name of the object to the output stream. More...

Detailed Description

API FOR ADVANCED USERS – A mutex is an object that provides mutually exclusive access to the object. A mutex is one of the basic building blocks of a multithreaded application.

Library: server
and mvcomp

This class provides a safe mutex. A safe mutex can be locked more than once by the same thread. It also detects attempts to perform illegal calls to lock() and unlock(), such as attempts to unlock a mutex which is not locked.

Note

For efficiency reasons, this class does not inherit from IlsUnsafeMutex. This would require virtual lock() and unlock() member functions to cause an unacceptable performance degradation.

See also

IlsThread, IlsUnsafeMutex.

Constructor & Destructor Documentation

IlsSafeMutex()

IlsSafeMutex::IlsSafeMutex	(	IlsBoolean	check = IlsFalse,
		IlsBoolean	wantTrylock = IlsFalse
	)

Constructor.

The first optional Boolean that can be passed to the constructor is used to turn on extra checking. The second optional argument is used to enable the trylock() member function. The reason for this is that on Windows®, trylock() is possible only on an inter-process mutex. Unfortunately, the lock() and unlock() member functions for this mutex are extremely slow.

If the safe mutex is created with the extra checking on, then the safe mutex generates a warning each time the mutex is locked when it has already been locked by the same thread. With checking turned on, the safe mutex behaves the same way as the unsafe mutex, and any exceptions to this rule result in a warning or an error. This is useful for debugging mutexes in applications where incorrect use of an unsafe mutex would result in undefined behavior.

Member Function Documentation

count()

long IlsSafeMutex::count

(

)

const

This member function returns the number of times the mutex has been locked by the owner thread.

If the calling thread is the owner thread, then the function returns count. Otherwise, it returns -count. If the mutex is not locked, the function returns 0. Hence, it is possible to determine whether the current thread or a different thread has locked the mutex.

lock()

IlsSafeMutexLockResult IlsSafeMutex::lock

(

)

This member function locks the mutex.

It will block if the mutex is locked by another thread until this thread unlocks the mutex. This function returns ILS_LOCK_OK if the lock worked, or ILS_LOCK_FAILED if the lock failed for a system-dependent reason.

trylock()

IlsSafeMutexLockResult IlsSafeMutex::trylock

(

)

This member function tries to lock the mutex.

It returns ILS_LOCK_LOCKED if the mutex is already locked. Otherwise, it returns the same result as the lock() member function.

Note

If you wish to use this method the mutex must be created with wantTrylock set to IlsTrue in the constructor.

unlock()

IlsSafeMutexUnlockResult IlsSafeMutex::unlock

(

)

This member function unlocks the mutex.

It does not do the unlock if the current thread is not the thread that locked the mutex or if the mutex is not locked.

Friends And Related Function Documentation

operator<<

ostream& operator<< ( ostream &  , const IlsSafeMutex &    )

friend

This operator prints the name of the object to the output stream.

This uses the method getName() to get the name of the mutex. If the method returns 0 then it uses a platform dependent value.