appCORE - coreMultiCoreStart()

NAME

coreMultiCoreStart() -- start a multicore processing element.

SYNOPSIS

include "appcore.h"

int coreMultiCoreStart( coreMultiCoreSPEC_t* s, corehMCORE_t* h )

DESCRIPTION

The coreMultiCoreStart() function creates and starts a multicore processing element. The multicore processing element is the extension of the standard appCORE thread to multiple processor cores. The multicore Specification Data Type (SDT) contains a thread SDT. Internally the coreThreadStart() function is used to start the threads. The number of threads started depends on the NumCores element. If NumCores is zero (0), the system is queried to determine the number of cores available, via the utility function coreNumCores().

The SelectCore() function is provided to map messages to specific threads. The user is able to specify, by message type, which thread should process a given message. This function enables the message context to order message processing by thread. If this function is not specified, then round-robin thread scheduling occurs by message.

All threads must start successfully for this function to succeed. Always zero the coreMCoreSPEC_t record before setting the desired parameters to insure reliable operation, default behavior, and compatibility with future releases.

The coreMultiCoreStop() function is used to shutdown the multicore processing element.

PARAMETERS

s
    typedef struct _core_multi_core_spec_
    {
      void* Context;
  	
        User context. This context is passed to the SelectCore() function.
      
      size_t NumCores;
  	
        Specifies the number of threads to start. If 0, the function coreNumCores() 
        is used to determine the number of cores in the system.
      
      size_t (*SelectCore)( void* Context, size_t Cores, coreMsg_t* );
      
  		The SelectCore() function is used to map a message to a processor core.
  		The Context is specified above. The Cores element specifies the number
  		of threads running in this multicore element. 
  	
      coreThreadSPEC_t ThreadSpec;
  	
  		See coreThreadStart() function.
    }
    coreMultiCoreSPEC_t;

h
    pointer to returned multicore handle.

RETURN VALUE

If successful, coreMultiCoreStart() returns 0. 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.