Flag Struct Reference


Public Methods

struct Flag* Flag_ctor (struct Flag *ptr_flag, char *name, bool set)
void Flag_set (struct Flag *ptr_flag)
void Flag_set_Ex (struct Flag *ptr_flag, bool state)
void Flag_clear (struct Flag *ptr_flag)
bool Flag_is_set (struct Flag *ptr_flag)
void Flag_flip (struct Flag *ptr_flag)
bool Flag_wait_set (struct Flag *ptr_flag, clock_t timeout)
bool Flag_wait_clear (struct Flag *ptr_flag, clock_t timeout)
bool Flag_wait (struct Flag *ptr_flag, bool set, clock_t timeout)
void Flag_dtor (struct Flag *ptr_flag, int memory_flag)

Detailed Description

This synchronization object has two states: set and clear. Threads may wait for the flag be in the specific state and change it.

See also:
Synchronization

Member Function Documentation

void Flag_clear ( struct Flag * ptr_flag )
 

Sets a flag in a clear state, or changes the flag's state to clear.
If there are threads waiting for the flag object's state to become clear, all of them will become active. If there were higher priority threads already waiting before this one, the context switch may happen immediately.

Parameters:
ptr_flag   A pointer to the initialized Flag object
Returns:
None 
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_clear( &data_busy, 1000 ) )
       {
         Flag_set( &data_busy );
         ...
         // Uses shared data.
         ...
         Flag_clear( &data_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...

struct Flag * Flag_ctor ( struct Flag * ptr_flag,
char * name,
bool set )
 

Creates a named flag.

Parameters:
ptr_flag   A pointer to the Flag structure
name   The name of the flag
set   if TRUE, then flag state will be set; otherwise it will clear
Returns:
A pointer to the initialized Flag object 
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_clear( &data_busy, 1000 ) )
       {
         Flag_set( &data_busy );
         ...
         // Uses shared data.
         ...
         Flag_clear( &data_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...

void Flag_dtor ( struct Flag * ptr_flag,
int memory_flag )
 

Destructor.

Parameters:
ptr_flag   A pointer to the initialized Flag 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 Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_clear( &data_busy, 1000 ) )
       {
         Flag_set( &data_busy );
         ...
         // Uses shared data.
         ...
         Flag_clear( &data_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...

void Flag_flip ( struct Flag * ptr_flag )
 

Flips a flag's state from set to clear or vice-versa.

Parameters:
ptr_flag   A pointer to the initialized Flag object
Returns:
None 
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_clear( &data_busy, 1000 ) )
       {
         Flag_set( &data_busy );
         ...
         // Uses shared data.
         ...
         Flag_flip( &data_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...

bool Flag_is_set ( struct Flag * ptr_flag )
 

Returns TRUE if a flag is in the set state.

Parameters:
ptr_flag   A pointer to the initialized Flag object
Returns:
TRUE if a flag is in the set state 
       #include <cywin.h>
       ...
       struct module_t main_module;
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       while( Flag_is_set( &data_busy ) )
       {
         sleep( 250 );
       }
       Flag_set( &data_busy );
       ...
       // Uses shared data.
       ...
       Flag_clear( &data_busy );
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...

void Flag_set ( struct Flag * ptr_flag )
 

Sets a flag, or changes the flag to the set state.
If there are threads waiting for the flag object's state to become set, all of them will become active. If there were higher priority threads already waiting before this one, the context switch may happen immediately. Does nothing if the flag is already set.

Parameters:
ptr_flag   A pointer to the Flag structure
Returns:
None 
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_clear( &data_busy, 1000 ) )
       {
         Flag_set( &data_busy );
         ...
         // Uses shared data.
         ...
         Flag_clear( &data_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...
See also:
Flag_set_Ex.

void Flag_set_Ex ( struct Flag * ptr_flag,
bool state )
 

Sets the flag to a specified state, or changes the flag's state to set or clear.
If there are threads waiting for the flag object's state to change this way, all of them will become active. If there were higher priority threads already waiting before this one, the context switch may happen immediately.

Parameters:
ptr_flag   A pointer to the initialized Flag object
state   The desired state; "TRUE" for set, "FALSE" for clear
Returns:
None 
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_clear( &data_busy, 1000 ) )
       {
         Flag_set_Ex( &data_busy, TRUE );
         ...
         // Uses shared data.
         ...
         Flag_set_Ex( &data_busy, FALSE );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...
See also:
Flag_set.

bool Flag_wait ( struct Flag * ptr_flag,
bool set,
clock_t timeout )
 

Waits for a specified state.
If the flag is already in the desired state, it returns; otherwise it waits for a specified timeout.

Parameters:
ptr_flag   A pointer to the initialized Flag object
set   'true' if you need to wait for the set state, 'false' for the clear state
timeout   Time to wait, in milliseconds. (0 means forever)
Returns:
TRUE on success, FALSE on timeout 
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait( &data_busy, FALSE, 1000 ) )
       {
         Flag_set( &data_busy );
         ...
         // Uses shared data.
         ...
         Flag_flip( &data_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...

bool Flag_wait_clear ( struct Flag * ptr_flag,
clock_t timeout )
 

Waits for the flag's state to become clear.
If the flag is already clear, it returns immediately. If the flag is set, it waits until the timeout expires or the flag state changes.

Parameters:
ptr_flag   A pointer to the initialized Flag object
timeout   Time to wait, in milliseconds. (0 means forever)
Returns:
TRUE on success, FALSE on timeout 
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_clear( &data_busy, 1000 ) )
       {
         Flag_set( &data_busy );
         ...
         // Uses shared data.
         ...
         Flag_flip( &data_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...

bool Flag_wait_set ( struct Flag * ptr_flag,
clock_t timeout )
 

Wait the flag's state to change to set.
If flag is already set, it returns immediately. If the flag is clear, it waits until the timeout expires or flag's state changes.

Parameters:
ptr_flag   A pointer to the initialized Flag object
timeout   Time to wait, in milliseconds (0 means forever)
Returns:
TRUE on success, FALSE on timeout 
       #include <cywin.h>
       ...
       struct Flag data_not_busy;
       ...
       Flag_ctor( &data_not_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_set( &data_not_busy, 1000 ) )
       {
         Flag_clear( &data_not_busy );
         ...
         // Uses shared data.
         ...
         Flag_flip( &data_not_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_not_busy, LEAVE_MEMORY );
       ...