appCORE - coreThreadStart()

NAME

coreThreadStart() -- start a serial dispatch thread.

SYNOPSIS

include "appcore.h"

int coreThreadStart( coreThreadSPEC_t* s, corehTHR_t* h )

DESCRIPTION

The coreThreadStart() function creates a new serial dispatch thread. Internally, the thread is created via the standard pthread_create() function. The returned thread handle is used to either send the thread an appCORE message (coreMsg_t) or to stop the thread. The handle does not point to memory and cannot be de-referenced. Handle only access avoids exceptions due to stale thread issues in applications with dynamic threads.

The coreThreadStart() function supports two (2) basic thread structures, selected by which elements are set in the coreThreadSPEC_t structure. The preferred method is to follow the standard appCORE design pattern of "StartUp/Run/ShutDown." This mode is selected by insuring the ThrFunc() element is NULL. Then, thread structure is defined by the three functions Startup(), MsgHandler(), and Shutdown(). If IO handling is needed, then add the IOHandler() function. If socket only IO is performed, select the built-in appCORE IOWaitHandler() by leaving the IOWaitHandler() function NULL. If special processing is required, then specify your own IOWaitHandler() function.

A basic message handling thread need only specify the MsgHandler() function. Normally, the MsgHandler() function is a simple switch statement based on appCORE message type. If thread startup or shutdown processing is required, then set those functions and they will be called before and after the MsgHandler() function, respectively. Normally, the startup function may allocate thread context, initialize variables, etc. If the Startup function is specified, the coreThreadStart() function waits for the Startup function to complete and passes its return value back to the caller. If the user's startup function returns less then zero (an error), the new thread will exit. This approach allows the caller to know precisely the status of the new thread and also be assured the new thread has completed it's startup function.

The thread shutdown function should clean up the thread's context and release any resources before the thread exits. The thread "Startup/Run/Shutdown" structure is a simple, predictable, yet powerful design pattern that enables a thread to be an encapsulated, self contained, processing element.

If the ThrFunc() element is specified, this function takes precedence, and is run after the standard appCORE thread initialization. In this mode, the caller is responsible for thread startup, run-time processing and shutdown. This method is provided to support a custom thread structure, if needed.

Always zero the coreThreadSPEC_t record before setting the desired parameters to insure reliable operation, default behavior, and compatibility with future releases.

PARAMETERS

s
    typedef struct _core_thr_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.
    
    char Name[ CORE_THREAD_NAME_LEN+1 ];
    
      Specifies the thread's name. This is displayed in thread aware log output.
      CORE_THREAD_NAME_LEN is 16 characters. This parameter is optional, but greatly
      improves readability of log output for debugging.
    
    char Info[ CORE_THREAD_INFO_LEN+1 ];
    
      Specifies information about the thread. This is displayed by the built-in 
      'threads' command available via the command session component. This parameter
      is optional. CORE_THREAD_INFO_LEN is 128 characters.
    
    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 does not free the message pointer. 
      appCORE manages message resources. This parameter can be NULL if no user specific 
      messages are to be handled.
    
    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. 
    
    coreIOWaitStatus_t (*IOWaitHandler)( void* );
    
      Specifies the function that waits on IO for the thread. If this parameter
      is NULL, then the standard appCORE function is used. The standard appCORE
      function handles waiting on socket IO.
    
    int (*IOHandler)( void*, int, coreIOWaitStatus_t );
    
      Specifies the function that handles IO for the thread. If this thread 
      performs IO, then this function must be specified to handle the IO.
    
    void* (*ThrFunc)( void* );
    
      Specifies the main function for the thread. The thread begins execution 
      at this address. If this function is specified, then this function is 
      executed, overriding the Startup, MsgHandler, ShutDown handlers.
      
    coreMsgChanSPEC_t ChanSpec;
    
      Specifies the type of input channel this thread supports. See definitions 
      below.
    
    pthread_attr_t Attr;
    
      Specifies the thread attribute object for the new thread. If Attr is NULL, 
      the thread is created with default attributes. This attribute object is
      passed directly to the underlying pthread_create() function.
    }
    coreThreadSPEC_t;
    
h
    Pointer to an appCORE thread handle.

RETURN VALUE

If successful, coreThreadStart() returns the value of the user's Startup function. If no startup function is specified, or if the ThrFunc() element was specified, then zero is returned to indicate the thread has started successfully. If an error occurs during startup, the return value is less then zero (<0) and the handle value is set to CORE_INVALID_HANDLE. The value of errno is set to one of the following values. appCORE supports multiple platforms. Consult your platform documentation for further errno values pthread_create() may set on your platform.

errno Value	Condition
EINVAL	Invalid argument.
ENOMEM	Insufficient memory to complete operation.
EAGAIN	System lacks necessary resources.
EFAULT	Thread function or Attr is an invalid pointer.

MULTI-THREAD SAFETY LEVEL

MT-safe.