IlsSafeMutex

Category

Thread utility class - API FOR ADVANCED USERS

Inheritance Path

IlsMTBase
➥ IlsSafeMutex

Description

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.

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 that would cause an unacceptable performance degradation.

Libraries

Header File

#include <ilserver/ilthread.h>

Synopsis

class IlsSafeMutex : public IlsMTBase

{

public:

IlsSafeMutex(IlsBoolean checking= IlsFalse,

IlsBoolean trylock= IlsFalse);

virtual ~IlsSafeMutex();

IlsSafeMutexLockResult lock();

IlsSafeMutexLockResult trylock();

IlsSafeMutexUnlockResult unlock();

long count()const;

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

};

Constructor

IlsSafeMutex(IlsBoolean checking= IlsFalse,

IlsBoolean trylock= IlsFalse);

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.

Destructor

virtual ~IlsSafeMutex();

This is the public virtual destructor for this class.

Member Functions

IlsSafeMutexLockResult 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.

IlsSafeMutexLockResult 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.

IlsSafeMutexUnlockResult unlock();

This member function unlocks the mutex.

long 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.

Operators

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

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