Processes and Modules


Defines

#define PR_IDLE   5
#define PR_NORMAL   50
#define PR_RUNTIME   100

Typedefs

typedef int priority_t

Enumerations

enum  modulestate_t {
  MODULE_OK = 0,
  MODULE_BAD,
  MODULE_TIMEOUT
}

Functions

long init_module (struct module_t *ptr_module)
void exit (int exit_code)
int execute_module (char *sz_command_line, long *ptr_retcode, clock_t timeout)
bool start_module (char *command_line)
void increment_usage (void)
void decrement_usage (void)
bool has_focus (void)
bool sleep (clock_t timeout)


Compounds

     struct   ModuleThe CyOS Module
     struct   module_tThe application module structure
     struct   ProcessA kind of thread that can process messages
     struct   QueueMessages queue; messages are stored in the queue
     struct   SystemThreadBase object for all execution units (threads)
     struct   ThreadThe main thread object for the CyOS

Detailed Description

These structures and functions are used to control the application as a whole. You may want to look at cWinApp and module_t structures.

Define Documentation

#define PR_IDLE   5
 

Very low priority (for background tasks).

#define PR_NORMAL   50
 

Normal (medium) priority.

#define PR_RUNTIME   100
 

Very high priority (for runtime threads).

Typedef Documentation

typedef int priority_t
 

The thread priority.
Must be one of the following: PR_IDLE, PR_NORMAL or PR_RUNTIME.

See also:
PR_IDLE, PR_NORMAL, PR_RUNTIME.

Enumeration Type Documentation

enum modulestate_t
 

The result of the module's execution.

See also:
execute_module.
Enumeration values:
MODULE_OK   Module was successfully initialized.
MODULE_BAD   Module was bad.
MODULE_TIMEOUT   Initialization timeout.

Function Documentation

void decrement_usage ( void )
 

Decrements the reference count for the current module.

Returns:
None. 
       #include <cybiko.h>
       ...
       increment_usage();
       ...
       //  During this time, the module cannot be unloaded.
       ...
       decrement_usage();
       ...
See also:
increment_usage.

int execute_module ( char * sz_command_line,
long * ptr_retcode,
clock_t timeout )
 

Loads and executes the module, then waits for it's module_main to exits.
It blocks a timeout while module_main finishes, then stores it's returned value in the retcode parameter. Use it when you need to get returned code, and don't mind waiting till the module_main exits.

Parameters:
sz_command_line   A command string to start the module
ptr_retcode   The storage site for the module's returned code
timeout   Determines how long to wait for module_main to finish
Returns:
The result of the execution (one of the modulestate_t members) 
       #include <cybiko.h>
       ...
       long retcode;
       ...
       // Executes an application.
       execute_module( "billiard.app", &retcode, 1000*60*10 );
       if( retcode ==  MODULE_TIMEOUT)
       {
         // The game time exceeded 10 minutes.  
         ...
       }
       ...
See also:
start_module, modulestate_t

void exit ( int exit_code )
 

Exits current the thread with some code.

Parameters:
exit_code   Exit code.
Returns:
None. 
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if( MSequence_is_sane( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       else
       {
         exit( 1 );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...

bool has_focus ( void )
 

Tests whether the current process has the focus.

Returns:
TRUE if the current process has the focus, otherwise FALSE 
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       Process_request_focus( main_module.m_process );
       ...
       if( has_focus() )
       {
         //  Draws something.
         ...
       }
       ...

void increment_usage ( void )
 

Increments the reference count for the current module.

Returns:
None 
       #include <cybiko.h>
       ...
       increment_usage();
       ...
       //  During this time, the module cannot be unloaded.
       ...
       decrement_usage();
       ...
See also:
decrement_usage.

long init_module ( struct module_t * ptr_module )
 

Module initializer.
You must call this function in each application to obtain a module.

Parameters:
module   The pointer to a module_t object
Returns:
A pointer to the application's initialized module 
       #include <cybiko.h>
       ...
       //  Application's main module
       struct module_t main_module;
       ...
       long main( int argc, char* argv[], bool start )
       {
         //  Initializes the application.
         init_module( &main_module );
         ...
      }

bool sleep ( clock_t timeout )
 

Pauses execution of the current thread.

Parameters:
The   time span to sleep, measured in milliseconds
Returns:
FALSE if timeout has passed. 
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       play_tone( 30 );
       sleep( 200 );
       play_tone( -1 );
       ...

bool start_module ( char * command_line )
 

Starts execution of the designated module (do not wait until it initializes!).

Returns:
TRUE if the module was launched, otherwise FALSE 
       #include <cybiko.h>
       ...
       long retcode;
       ...
       // Executes an application.
       if( !start_module( "billiard.app" ) )
       {
         // Unable to launch the 'Billiard' application.
         ...
       }
       ...
See also:
execute_module.