Flagex Struct Reference

Inheritance diagram for Flagex

Inheritance graph

Collaboration diagram for Flagex:

Collaboration graph


Public Methods

struct Flagex* Flagex_ctor (struct Flagex *ptr_flagex, char *name)
bool Flagex_wait (struct Flagex *ptr_flagex, clock_t timeout)
void Flagex_notify (struct Flagex *ptr_flagex)
bool Flagex_is_locked (struct Flagex *ptr_flagex)
bool Flagex_lock (struct Flagex *ptr_flagex, clock_t timeout)
void Flagex_unlock (struct Flagex *ptr_flagex)
void Flagex_dtor (struct Flagex *ptr_flagex, int memory_flag)

Detailed Description

A Flag with Exclusion. Flagex is a son of Mutex that contains a Flag. Hence the name, a combination of FLAG and mutEX. It is a sort of synchronization object you can use when your object needs both to implement a wait-for-notification function as well as to lock and unlock like Mutex objects can. It works on the same principle as Java's "monitor lock." The main difference is that Flagex cannot notify a single thread; Flagex_notify is the equivalent of Java's Object.notifyAll().

Flagex offers three main functions:

The key is that Flagex_wait and Flagex_notify only function when the object is Flagex_locked. When your object wakes after Flagex_wait, the system regains the lock on the Flagex for your thread. After you call Flagex_wait, the thread is released so another thread can Flagex_lock it and then Flagex_notify it.

Use this method when you need to synchronize exclusive access to a specific object until another process concludes on the same object. This allows the accessing thread both to wait and to synchronize its action with the other thread.
See also:
Synchronization

Member Function Documentation

struct Flagex * Flagex_ctor ( struct Flagex * ptr_flagex,
char * name )
 

Constructs a named Flagex object.

Parameters:
ptr_flagex   A pointer to the Flagex structure
name   The name of the Flagex object
Returns:
A pointer to the initialized Flagex object 
       #include <cywin.h>
       ...
       struct Flagex wait_for_data;
       ...
       Flagex_ctor( &wait_for_data, "data_ready" );
       ...
       if( Flagex_wait( &wait_for_data, 1000 ) )
       {
         // Uses shared data.
         ...
       }
       else
       {
         TRACE( "Timeout while waiting for data." );
       }
       ...
       Flagex_dtor( &wait_for_data, LEAVE_MEMORY );
       ...

void Flagex_dtor ( struct Flagex * ptr_flagex,
int memory_flag )
 

Destructor.

Parameters:
ptr_flagex   A pointer to the initialized Flagex 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 Flagex wait_for_data;
       ...
       Flagex_ctor( &wait_for_data, "data_ready" );
       ...
       if( Flagex_wait( &wait_for_data, 1000 ) )
       {
         // Uses shared data.
         ...
       }
       else
       {
         TRACE( "Timeout while waiting for data." );
       }
       ...
       Flagex_dtor( &wait_for_data, LEAVE_MEMORY );
       ...

bool Flagex_is_locked ( struct Flagex * ptr_flagex )
 

Checks whether Mutex is locked.

Parameters:
ptr_flagex   A pointer to the initialized Flagex object
Returns:
TRUE if Mutex is locked 
       #include <cywin.h>
       ...
       struct module_t main_module;
       struct Flagex wait_for_data;
       ...
       Flagex_ctor( &wait_for_data, "data_ready" );
       while( Flagex_is_locked( &wait_for_data ) )
       {
          sleep( 250 );
       }
       Flagex_lock( &wait_for_data, 0 );
       ...
       // Uses shared data.
       ...
       Flagex_unlock( &wait_for_data); 
       ...
       Flagex_dtor( &wait_for_data, LEAVE_MEMORY );
       ...

bool Flagex_lock ( struct Flagex * ptr_flagex,
clock_t timeout )
 

Returns a lock.
It attempts to get the lock for specified time. Note that if you already locked it, another Flagex_lock() operation has no additive effect. The first Flagex_unlock() call unlocks it immediately no matter how many times you've called the Flagex_lock() method. Be careful when designing your Flagexes logic!

Parameters:
ptr_flagex   A pointer to the initialized Flagex object
timeout   Determines how long to wait if a lock can not be acquired; (0 means forever)
Returns:
TRUE if a lock was acquired, FALSE if timeout expired 
       #include <cywin.h>
       ...
       struct module_t main_module;
       struct Flagex wait_for_data;
       ...
       Flagex_ctor( &wait_for_data, "data_ready" );
       while( Flagex_is_locked( &wait_for_data ) )
       {
          sleep( 250 );
       }
       Flagex_lock( &wait_for_data, 0 );
       ...
       // Uses shared data.
       ...
       Flagex_unlock( &wait_for_data); 
       ...
       Flagex_dtor( &wait_for_data, LEAVE_MEMORY );
       ...
See also:
Flagex_unlock.

void Flagex_notify ( struct Flagex * ptr_flagex )
 

Notifies all waiting threads.
All threads that called Flagex_wait() for this object will be waked up. Note that they won't start until you will unlock the object, and that most priority one (and, though not guaranteed, first called wait() from top priority threads) will get the lock and actually start. You must have a lock on the object to call this method.

Parameters:
ptr_flagex   A pointer to the initialized Flagex object
Returns:
None 
       #include <cywin.h>
       ...
       struct Flagex wait_for_data;
       ...
       Flagex_ctor( &wait_for_data, "data_ready" );
       ...
       // Prepares data.
       ...
       Flagex_notify( &wait_for_data );
       ...
       Flagex_dtor( &wait_for_data, LEAVE_MEMORY );
       ...

void Flagex_unlock ( struct Flagex * ptr_flagex )
 

Unlocks Flagex.
Note that if you did not lock it before, the system ignores the unlock command and prints warning on the console. Also be warned: Flagex_unlock() releases the lock immediately, no matter how many times Flagex_lock() was called. Only the first Flagex_unlock() works; any repeared calls will be ignored.

Parameters:
ptr_flagex   A pointer to the initialized Flagex object
Returns:
None 
       #include <cywin.h>
       ...
       struct module_t main_module;
       struct Flagex wait_for_data;
       ...
       Flagex_ctor( &wait_for_data, "data_ready" );
       while( Flagex_is_locked( &wait_for_data ) )
       {
          sleep( 250 );
       }
       Flagex_lock( &wait_for_data, 0 );
       ...
       // Uses shared data.
       ...
       Flagex_unlock( &wait_for_data); 
       ...
       Flagex_dtor( &wait_for_data, LEAVE_MEMORY );
       ...
See also:
Flagex_lock.

bool Flagex_wait ( struct Flagex * ptr_flagex,
clock_t timeout )
 

Waits for notification.
Puts the calling thread to sleep until some other thread calls Flagex_notify(). You must have a lock on this object to call it.

Parameters:
ptr_flagex   A pointer to the initialized Flagex object
timeout   Determines how long to wait, in milliseconds ( 0 means forever)
Returns:
TRUE on notification and FALSE on timeout 
       #include <cywin.h>
       ...
       struct Flagex wait_for_data;
       ...
       Flagex_ctor( &wait_for_data, "data_ready" );
       ...
       if( Flagex_wait( &wait_for_data, 1000 ) )
       {
         // Uses shared data.
         ...
       }
       else
       {
         TRACE( "Timeout while waiting for data." );
       }
       ...
       Flagex_dtor( &wait_for_data, LEAVE_MEMORY );
       ...