Mutex Struct Reference

Inheritance diagram for Mutex

Inheritance graph


Public Methods

struct Mutex* Mutex_ctor (struct Mutex *ptr_mutex, char *name)
bool Mutex_is_locked (struct Mutex *ptr_mutex)
bool Mutex_lock (struct Mutex *ptr_mutex, clock_t timeout)
void Mutex_unlock (struct Mutex *ptr_mutex)
void Mutex_dtor (struct Mutex *ptr_mutex, int memory_flag)

Detailed Description

Mutex is a kind of a synchronization object that provides MUTually EXclusive (MUTEX) access to some part of the code (in some systems this is also known as Resource). Mutex can be locked by a Thread using the Mutex_lock method, then released. Only one thread at a time owns the lock on any given Mutex when the lock is released, the next thread (if any) waiting for the Mutex is activated.

If a thread tries to lock a Mutex that is already locked, the thread will be set to wait until a timeout expires or until the Mutex object is unlocked. Take care to prevent deadlocks: for example, when one thread owns Mutex m1 and tries to lock Mutex m2,while a second thread already owns Mutex m2 and is trying to lock Mutex m1. Deadlocks can occur not only with Mutexes, but practically with any set of synchronization objects. Since the OS can not yet detect all deadlocks, it is up to programmers to design their systems accordingly.

It doesn't matter how long you've locked a Mutex object-it unlocks the first time you call Mutex_unlock(). The system does not allow unowned Mutex objects to be unlocked.

See also:
Synchronization

Member Function Documentation

struct Mutex * Mutex_ctor ( struct Mutex * ptr_mutex,
char * name )
 

Constructs the named Mutex object.

Parameters:
ptr_mutex   A pointer to the Mutex structure
name   The name of the Mutex object
Returns:
A pointer to the initialized Mutex object 
       #include <cywin.h>
       ...
       struct Mutex data_mutex;
       ...
       Mutex_ctor( &data_mutex, "shared_data" );
       ...
       if( Mutex_lock( &data_mutex, 1000 ) )
       {
         // Uses shared data.
         ...
         Mutex_unlock( &data_mutex );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Mutex_dtor( &data_mutex, LEAVE_MEMORY );
       ...

void Mutex_dtor ( struct Mutex * ptr_mutex,
int memory_flag )
 

Destructor.

Parameters:
ptr_mutex   A pointer to the initialized Mutex object
memory_flag   Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None 
       #include <cywin.h>
       ...
       struct Mutex data_mutex;
       ...
       Mutex_ctor( &data_mutex, "shared_data" );
       ...
       if( Mutex_lock( &data_mutex, 1000 ) )
       {
         // Uses shared data.
         ...
         Mutex_unlock( &data_mutex );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Mutex_dtor( &data_mutex, LEAVE_MEMORY );
       ...

bool Mutex_is_locked ( struct Mutex * ptr_mutex )
 

Checks whether the Mutex is locked.

Parameters:
ptr_mutex   A pointer to the Mutex structure
Returns:
TRUE if the Mutex object is locked 
       #include <cywin.h>
       ...
       struct module_t main_module;
       struct Mutex data_mutex;
       ...
       Mutex_ctor( &data_mutex, "shared_data" );
       ...
       while( Mutex_is_locked( &data_mutex ) )
       {
         sleep( 250 );
       }
       Mutex_lock( &data_mutex, 0 );
       ...
       // Uses shared data.
       Mutex_unlock( &data_mutex );
       ...
       Mutex_dtor( &data_mutex, LEAVE_MEMORY );
       ...

bool Mutex_lock ( struct Mutex * ptr_mutex,
clock_t timeout )
 

Returns a lock.
Attempts to get the lock for specified time. Note that if you already locked an object, another Mutex_lock() operations does absolutely nothing, and the first Mutex_unlock() call unlocks it immediately no matter how many times you've called the Mutex_lock() method. Be careful when designing your Mutex logic!

Parameters:
ptr_mutex   A pointer to the initialized Mutex object
timeout   Determines how long wait if a lock can not be acquired (0 means forever)
Returns:
TRUE if a lock was acquired, FLASE if timeout has expired 
       #include <cywin.h>
       ...
       struct Mutex data_mutex;
       ...
       Mutex_ctor( &data_mutex, "shared_data" );
       ...
       if( Mutex_lock( &data_mutex, 1000 ) )
       {
         // Uses shared data.
         ...
         Mutex_unlock( &data_mutex );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Mutex_dtor( &data_mutex, LEAVE_MEMORY );
       ...
See also:
Mutex_unlock.

void Mutex_unlock ( struct Mutex * ptr_mutex )
 

Unlocks a Mutex object.
Note that if you did not Mutex_lock() it before, the system ignores the unlock command and prints a warning on the console. Also be warned: Mutex_unlock() releases the lock immediately. No matter how many times Mutex_lock() was called, only the first Mutex_unlock() works. any repeared commands will be ignored.

Parameters:
ptr_mutex   A pointer to the initialized Mutex object
Returns:
None 
       #include <cywin.h>
       ...
       struct Mutex data_mutex;
       ...
       Mutex_ctor( &data_mutex, "shared_data" );
       ...
       if( Mutex_lock( &data_mutex, 1000 ) )
       {
         // Uses shared data.
         ...
         Mutex_unlock( &data_mutex );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Mutex_dtor( &data_mutex, LEAVE_MEMORY );
       ...
See also:
Mutex_lock.