Porting C-with-Ease

 

The C-with-Ease implementation can be easily ported to various parallel architectures by providing an appropriate host interface. The host model is described in section 5.1.

Host Interface

The host interface handles all of the low level access to the host, including thread creation and switching, semaphore and mutex functionality and message sending and receiving.

Typically, a host interface consists of a small header file containing definitions of the host characteristics for the Ease library, and another defining the necessary functions. The header file specifies whether it has multiple cells, whether the host has threads, and if those threads are preemptive. It also defines the types for a cell identifier and a thread identifier.

Basic interface

 

The following functions should be supplied:

• _ec_main(argc, argv)
  • To allow for C and C++ linkage the entry point to the host interface is _ec_main. Another part of the Ease library supplies a main appropriate for the language compiled. (The main for a C++ program must be compiled with the correct compiler to allow for correct handling of global and static constructors and destructors).

• double _getTime()
  • Return the current time in seconds as a double. This is used in some debugging output.

• fatal(msg)
  • Abort the entire program.

Thread Handling Interface

A host interface must either define the macro NTHREAD (for no threads) or supply the following functions and types:

• Type: _ec_thread
  • The thread type for the host interface.

• _createThread(function, void *data, size)
  • Create a new thread, initially calling the supplied function with the supplied data and size as parameters. If the threads are non-preemptive then the new thread should be initially suspended.

• _threadsEqual(a, b)
  • Test to see whether two thread identifiers refer to the same thread. Return true if they do.

• _initThread(main, argc, argv)
  • Initialize the threads system. The arguments get passed on to the initProcess function of the Ease scheduler (section 5.5.3). This function allows for splitting the host interface into two parts: a threads component (shared memory) and a message passing component (distributed memory). A message passing library (such as PVM) and a selection of threads libraries may be available depending on the host type.

    If the macro EXT_THREADS is defined, then both distributed and shared memory systems are being used. The threads library should not supply the functions listed under the basic interface in section 5.7.1.

The interface specifies that threads are preemptive by defining the macro PREEMPT. For non-preemptive threads, the following function must be supplied:

• _runThread(thread)
  • Switch control to the specified thread.

For preemptive threads, the following types and functions must be supplied:

• Type: _ec_sem
  • The semaphore type created and used by the host interface.

• _createSem(value)
  • Create a new counting semaphore with its counter set to the value supplied.

• _deleteSem(semaphore)
  • Delete the specified semaphore.

• _waitSem(semaphore)
  • Wait on the specified semaphore.

• _signalSem(semaphore)
  • Signal the specified semaphore.

• Type: _ec_mutex
  • The mutex type created and used by the host interface.

• _createMutex()
  • Create and return a new mutex.

• _deleteMutex(mutex)
• _lockMutex(mutex)
• _unlockMutex(mutex)
• _ec_thread _currentTid()
  • Return the identifier of this thread.

• _setThreadPtr(void *ptr)
  • Associate this pointer with the current thread. This is used to store a pointer to the Ease library scheduler's thread structure to improve efficiency.

• void *_getThreadPtr()
  • Retrieve the pointer supplied to _setThreadPtr().

• _yieldThread()
  • Yield control to another runnable thread. A correct implementation may do nothing - this is a request from the Ease programmer to switch from the current thread.

Message Passing Interface

A host type that uses message passing should define the macro _EASE_MULTI. It should supply the following types and functions:

• Type: _ec_cellId
  • This is the type for a cell identifier. Each value of this type should uniquely specify a cell and be valid for all cells in the host. A bitwise copy of the value should be similarly valid on all cells (ie. a pointer to a structure is inappropriate as it is likely to be not valid in all the address spaces (cells) of the host).

• _sendMessage(Message)
  • Transmit the supplied message. The message structure contains information pertaining to the destination cell and thread.

• _localCell()
  • Returns the cell identifier of the local cell. That is, the cell that the calling thread is executing on.

• _isLocal(cell)
  • Returns true if the cell supplied is the local cell.

• _isLocalCtx(context)
  • True if the context resides on the local cell.

• _receiveMessages()
  • Receive and handle all pending messages. The message passing interface may use message types starting from TYPE_LAST_TYPE for its own purposes (such as load balancing and cell allocation). _receiveMessages() should call the scheduler function _handleMessage() (section 5.5.3) for messages it can not handle itself (ie. all message before TYPE_LAST_TYPE).

• int _waitMessages(time)
  • Block and wait for a message to arrive or until at least time seconds have elapsed. If a message arrives, then handle all messages possible (other messages may arrive while handling the first) and return 0. If the function returns due to timeout, return 1. If time is negative, then wait indefinitely. Note that an implementation need never return due to timeout since there is no minimum time to return.

• _selectProcessor()
  • Select and return a cell for the creation of a new Ease process. This may create a new cell or reuse an existing cell. The caller of this function will typically then send a process creation request to the cell which will then create a new thread or reuse an existing thread.

• _freeThread()
  • Inform the host that the current thread is free and available for re-use. This is typically used as a hint to selectProcessor to allow for allocation of processes to cells where there are existing but unused threads.