appCORE - coreAppStart()

NAME

coreAppStart() -- start the application's main dispatch thread.

SYNOPSIS

include "appcore.h"

int coreAppStart( coreAppSPEC_t* s )

DESCRIPTION

The coreAppStart() function creates appCORE's main serial dispatching thread and implements appCORE's standard "Startup/Run/Shutdown" design pattern. The user configures the operation via the coreAppSPEC_t data type defined below. Always zero the coreAppSPEC_t record before setting the desired parameters to insure reliable operation, default behavior, and compatibility with future releases.

The coreAppStart() function creates the new dispatch thread and waits for the result of the user's startup function. The dispatch thread executes the startup function and returns the status to the caller. This allows the caller to determine if the application's startup function has been successful. If the startup function fails, indicated via a negative (<0) return value, the function has failed and the new thread exits. If a startup function was not specified, the return status will always be successful (0) and appCORE will enter the 'RUN' state. If a startup function was specified and is successful, appCORE will enter the 'RUN' state and the main dispatching thread is ready to process messages.

The coreAppStop() function is used to terminate the main dispatching thread.

PARAMETERS

s   
    typedef struct _core_app_spec_
    {
    void* ParamBlock;
    
        The parameter block is passed to the StartUp function as the first argument.
        This is how an arbitrary number of parameters can be passed to the thread's 
        startup function. This parameter is optional. It's use is up to the user.
		
    int (*StartUp)( void* ParamBlock, void** ppCntxt );
    	
        The startup function. This function is called by the dispatch thread. This
        function should not block. This function should perform whatever startup
        processing is required. The first argument is the ParamBlock discussed above.
        This is used to pass any parameters to the thread's startup function. The 
        second argument is a pointer to the thread's context pointer. The startup 
        function can create a context and return it to appCORE via this element. 
        This context is then passed to functions below. This parameter is optional. 
    	
    int (*MsgHandler)( void* pCntxt, coreMsg_t* );
    
        The main message processing, or dispatching, function. This function is called 
        with the thread context and a message. Normally this function is a simple switch 
        statement based on message type. This function should not block. This function 
        does not free the message pointer. appCORE manages message resources. This 
		parameter is required. 
    	
    int (*ShutDown)( void* pCntxt );
    
    	The shutdown function. This function is called by the dispatch thread before the
    	dispatch thread exits. This function should perform whatever shutdown processing
    	is required. This parameter is optional.
            
    int (*SignalHandler)( void* pCntxt, int Signal );
    
    	The signal handler function. This function is called in response to a signal. 
    	This parameter is optional. If this function returns a non-zero value, the 
    	appCORE shut down process is initiated. If the handler is NULL, normal appCORE
    	signal handling occurs.
    		
    void (*LogHandler)( const char* );
    
        The custom log handler. If defined, this function is called with a null 
        terminated string containing the final output of appCORE log output. This 
        parameter can be NULL, in which case appCORE will display output to a console, 
        if requested, or to a syslog interface.
    	
    void (*ThreadBegin)( void* pCntxt );
    
    	If defined, this function is called by each thread when starting.
    	
    void (*ThreadEnd)( void* pCntxt );
    
    	If defined, this function is called before each thread exits.
    	
    unsigned char LogLevel[ LZ_START ];
    
        The LogLevel array provides a way to specify any application defined log zone 
        setting before the main dispatcher is started. The specified trace zone levels 
        are copied into the main control block. The default range is 0 to 
        CORE_LOG_ZONE_START. The default value of CORE_LOG_ZONE_START is 100, allowing 
        100 user defined log zones. The function coreAppLogZoneInit() should be used to 
        initialize this array. 
    }
    coreAppSPEC_t;

RETURN VALUE

The function returns -1 on failure. The function returns the user function's return code, if specified. If the value is less then zero (<0), the function failed and appCORE remains in the INIT state.

errno Value	Condition
EINVAL	Argument NULL or message handler function not defined.
ECANCELED	appCORE not in the initialized (INIT) state, or startup function failed.

MULTI-THREAD SAFETY LEVEL

MT-safe.