Class IloFastMutex

The class IloFastMutex provides synchronization primitives adapted to the needs of Concert Technology. In particular, an instance of the class IloFastMutex is a non-recursive mutex that implements mutual exclusion from critical sections of code in multithreaded applications. The purpose of a mutex is to guarantee that concurrent calls to a critical section of code in a multithreaded application are serialized. If a critical section of code is protected by a mutex, then two (or more) threads cannot execute the critical section simultaneously. That is, an instance of this class makes it possible for you to serialize potentially concurrent calls.

Concert Technology implements a mutex by using a single resource that you lock when your application enters the critical section and that you unlock when you leave. Only one thread can own that resource at a given time.

See ILOUSEMT for details about the compilation macro to use with instances of this class.

Protection by a Mutex

A critical section of code in a multithreaded application is protected by a mutex when that section of code is encapsulated by a pair of calls to the member functions IloFastMutex::lock and IloFastMutex::unlock.

In fact, we say that a pair of calls to the member functions lock and unlock defines a critical section. The conventional way of defining a critical section looks like this:

 mutex.lock();
 while (conditionC does not hold)
        condition.wait(&mutex);
 doTreatmentT();
 mutex.unlock();
 

The class IloCondition provides synchronization primitives to express conditions in critical sections of code.

State of a Mutex

A mutex (an instance of IloFastMutex) has a state; the state may be locked or unlocked. You can inquire about the state of a mutex to determine whether it is locked or unlocked by using the member function IloFastMutex::isLocked. When a thread enters a critical section of code in a multithreaded application and then locks the mutex defining that critical section, we say that the thread owns that lock and that lock belongs to the thread until the thread unlocks the mutex.

Exceptions

The member functions IloFastMutex::lock and IloFastMutex::unlock can throw C++ exceptions when exceptions are enabled on platforms that support them. These are the possible exceptions:

• IloMutexDeadlock: Instances of IloFastMutex are not recursive. Consequently, if a thread locks a mutex and then attempts to lock that mutex again, the member function lock throws the exception MutexDeadlock. On platforms that do not support exceptions, it causes the application to exit.
• IloMutexNotOwner: The thread that releases a given lock (that is, the thread that unlocks a mutex) must be the same thread that locked the mutex in the first place. For example, if a thread A takes lock L and thread B attempts to unlock L, then the member function unlock throws the exception MutexNotOwner. On platforms that do not support exceptions, it causes the application to exit.
• IloMutexNotOwner: The member function unlock throws this exception whenever a thread attempts to unlock an instance of IloFastMutex that is not already locked. On platforms that do not support exceptions, it causes the application to exit.

System Class: Memory Management

IloFastMutex is a system class.

Most Concert Technology classes are actually handle classes whose instances point to objects of a corresponding implementation class. For example, instances of the Concert Technology class IloNumVar are handles pointing to instances of the implementation class IloNumVarI. Their allocation and de-allocation in internal data structures of Concert Technology are managed by an instance of IloEnv.

However, system classes, such as IloFastMutex, differ from that pattern. IloFastMutex is an ordinary C++ class. Its instances are allocated on the C++ heap.

Instances of IloFastMutex are not automatically de-allocated by a call to IloEnv::end. You must explicitly destroy instances of IloFastMutex by means of a call to the delete operator (which calls the appropriate destructor) when your application no longer needs instances of this class.

Furthermore, you should not allocate—neither directly nor indirectly—any instance of IloFastMutex in the Concert Technology environment because the destructor for that instance of IloFastMutex will never be called automatically by IloEnv::end when it cleans up other Concert Technology objects in the Concert Technology environment. In other words, allocation of any instance of IloFastMutex in the Concert Technology environment will produce memory leaks.

For example, it is not a good idea to make an instance of IloFastMutex part of a conventional Concert Technology model allocated in the Concert Technology environment because that instance will not automatically be de-allocated from the Concert Technology environment along with the other Concert Technology objects.

De-allocating Instances of IloFastMutex

Instances of IloFastMutex differ from the usual Concert Technology objects because they are not allocated in the Concert Technology environment, and their de-allocation is not managed automatically for you by IloEnv::end. Instead, you must explicitly destroy instances of IloFastMutex by calling the delete operator when your application no longer needs those objects.

This constructor creates an instance of IloFastMutex and allocates it on the C++ heap (not in the Concert Technology environment). This mutex contains operating system-specific resources to represent a lock. You may use this mutex for purposes that are private to a process. Its behavior is undefined for inter-process locking.

The delete operator calls this destructor to de-allocate an instance of IloFastMutex. This destructor is called automatically by the runtime system. The destructor releases operating system-specific resources of the invoking mutex.

This member function returns a Boolean value that indicates the state of the invoking mutex. That is, it tells you whether the mutex is locked by the calling thread (0) or unlocked (1) or locked by a thread other than the calling thread (also 1).

This member function acquires a lock for the invoking mutex on behalf of the calling thread. That lock belongs to the calling thread until the member function unlock is called.

If you call this member function and the invoking mutex has already been locked, then the calling thread is suspended until the first lock is released.

This member function releases the lock on the invoking mutex, if there is such a lock.

If you call this member function on a mutex that has not been locked, then this member function throws an exception if C++ exceptions have been enabled on a platform that supports exceptions. Otherwise, it causes the application to exit.