To start a thread manager, supply an opThreadMgr with four parameters:

This is the sequence of events to specify and perform tasks managed by an opThreadMgr:

To design effective MP programs that keep processors occupied, you have to know when tasks finish and you need tools to manage the order of their execution. For example, you are likely to have process interdependencies such as “do A after B,” “wait for C,” and so on. The opThreadMgr methods waitForRequests() and markRequests() allow you to manage interprocess dependencies.

---

Note: When you use multiple processors, you cannot know in advance the order in which tasks finish. opThreadMgr provides queueing and coordination tools, but be cautious with programming assumptions about completion times when you write MP programs.

---

Three action objects define tasks scheduled by opThreadMgr's three methods, which distribute one task to one process, one task to many processes, and many tasks to many processes. Table 14-1 summarizes the processing features of the three scheduling functions and their action objects.

The callbacks for action objects are discussed after the class opThreadMgr and its scheduling functions.

The class has the following main methods:

class opThreadMgr {
public:
// Constructor/Destructor
opThreadMgr( int initialNThreads     = 2, 
             int prioritiesPerThread = 1, 
             opQDiscipline qd        = opPreEmptive, 
             int maxNumberOfThreads  = opThreadMgr::defaultMaxThreads);
~opThreadMgr( void );

/* Managing Threads */
// Thread parameter query and set
opTID addThread( int numberOfPriorities = 1, 
                      opQDiscipline qd  = opRoundRobin );
int getThreadCount( void ) const;

 // The number of queues associated with a given thread.
int  getPriorityCount( opTID tid ) const;

// Queue-discipline query and set.
void          setQDiscipline( opTID tid, opQDiscipline qd );
opQDiscipline getQDiscipline( opTID tid ) const;

/*  Scheduling Tasks */
// Enqueue a user function.
void schedMPFunList( opMPFunListAction* actions, 
                     const opTIDSet& tids = opAllTIDs, 
                     opPriority p = opDefaultPriority);
void schedMPFun( opMPFunAction* action,
                 const opTIDSet& tids = opAllTIDs,
                 opPriority p = opDefaultPriority);
void schedSPFun( opFunctionAction *action, 
                 opTID tid = opDefaultTID, 
                 opPriority priority = opDefaultPriority);
static void executeSPFun (opFunctionAction* action);

// Blocking calls that wait for queued requests to finish.
void waitForRequests(const opTIDSet& tids = opAllTIDs, 
                     opPriority p = opAllLevels);
opBlockingCounter *markRequests(const opTIDSet& tids = opAllTIDs,  
                                opPriority p = opAllLevels);
};

The main methods of opThreadMgr form two groups:

The opActionInfo class is used as an argument for any action-object callback. It provides information about the callback's opThreadMgr, the thread on which the callback is running, and the execution priority of the callback.

Class Declaration for opActionInfo

The class has the following main methods:

class opActionInfo
{
public:
// Creating and destroying
opActionInfo(opThreadMgr *threadMgr, opTID tid, opPriority priority);
~opActionInfo() ;

// Accessors
opThreadMgr *getThreadManager() const;
opTID getTID() const;
opPriority getPriority() const;
};

opFunctionAction is the class for running one task on one thread in a multi-threaded environment. To schedule an opFunctionAction, pass it to schedSPFunction().

The class has the following main methods:
class opFunctionAction : public opAction
{
public:
opFunctionAction() ;
virtual ~opFunctionAction() ;

virtual opActionDisp function(const opActionInfo&);
};

opMPFunAction is the class for running one task on a set of threads. For example, you might submit a rendering action to four processes and divide the screen into four areas. You could submit one function to four processes and encode the portion of the screen actually drawn by the function by using the thread identification number. To schedule an opMPFunAction, pass it to schedMPFunction().

The thread manager processes an opMPFunAction in three steps:

Class Declaration for opMPFunAction

The class has the following main methods:

class opMPFunAction : public opAction
{
public:
opMPFunAction() ;
virtual ~opMPFunAction() ;

virtual void begin(const opActionInfo&);
virtual void perThread(const opActionInfo&);
virtual opActionDisp end(const opActionInfo&);
};

The opMPFunListAction class runs several tasks on several threads. To schedule an opMPFunListAction, pass it to an schedMPFunctionList().

The tasks of an opMPFunListAction are defined by a list of opFunctionActions. The thread manager processes the list in three step:

You may not always know the set of tasks you wish to implement when you construct an opMPFunListAction. For example, you might want to render only visible surfaces, for which you have an occlusion culling traverser. The methods setActionArray() and addAction() allow you to build the list of functions before you begin the action.

Class Declaration for opMPFunListAction

The class has the following main methods:

class opMPFunListAction : public opAction
{
public:
opMPFunListAction(int nActions,opFunctionAction **actions);
virtual ~opMPFunListAction();

virtual void begin(const opActionInfo&);
virtual opActionDisp end(const opActionInfo&);

void setNumberOfActions(int numberOfActions);
int  getNumberOfActions(void) ;

void setActionArray(opFunctionAction **actions);
opFunctionAction **getActionArray(void) ;

void addAction(opFunctionAction *action);
};

The class has the following main methods:

class opTransactionMgr
{
public:
opTransactionMgr();
~opTransactionMgr();

void commit(opTransaction* transaction);
void blockingCommit(opTransaction *transaction);

void processTransactions(void);
// Sets the amount of time per frame that the main thread
// may spend processing pending transactions.
void setMergeTimeLimit(float seconds);
float getMergeTimeLimit(void);

void setMaxPending(int n);
int getMaxPending(void);
};

The opTransaction class holds Cosmo3D functions that you can submit to the transaction manager. Each of the opTransaction methods appends a token representing a Cosmo3D function to the list to be submitted to the transaction manager.

class opTransaction : public MPQElement
{
public:
opTransaction();
~opTransaction();

// csObject operations
void setUserData(csContainer *container, csData *data );
void unrefDelete(csObject    *object);

// csGroup operations
void addChild    (csGroup *parent,csNode *child);
void insertChild(csGroup *parent,int idx,csNode *child);
void removeChild (csGroup *parent,csNode *child);
void replaceChild(csGroup *parent,csNode *oldChild,
                                     csNode *newChild);

// csShape operations
void setGeometry(csShape *shape, int i, csGeometry *geometry);
void setAppearance(csShape *shape,csAppearance *appearance);

// csMaterial operations
void setDiffuseColor(csMaterial *material,float r,float g,float b);
};

These functions correspond to the most commonly used opTransactionMgr methods. They are defined so that you can use them without referring to a specific opTransactionMgr scope; they are executed by the default instance of opTransactionMgr, _opTransactionMgr, which is initialized by opInit.

The functions opCommit() and opBlockingCommit() have actions that correspond to the like-named opTransactionMgr methods. The function opSync() calls an opTransactionMgr::processTransactions() and returns a value of 1.

This class implements a simple locking mechanism.

The class has the following main methods: 
class opLock
{
public:
// Allocates the lock from the arena that the opLock structure was
// allocated from.
opLock();
~opLock();

bool lock(void);
bool unlock();
};

The opMutex class provides a mechanism to simplify the control of mutual exclusion within a block of code. An opMutex acquires and holds the lock passed to its constructor until control exits the current scope. The lock is released when the destructor is called.

A typical use for opMutex is in conjunction with normal C++ scoping to make sure that a lock is released when control leaves a block. This is particularly useful when an exception could be thrown from within a block, or to guard against returning from the middle of a locked block. See the reference page opLock(3in) for more details and a code example. The file opMutex.h also contains a code example.

---

Note: The maximum number of locks in the system is 4096. No more than 65 processes may share a single lock.

---

To be compatible with the OpenGL Optimizer library, use the class opSemaphore to control semaphores.

class opSemaphore
{
public:
// Allocates the lock from the arena that the opLock structure was  
//  allocated from.
opSemaphore(int count);
~opSemaphore();
opBool p(void);
opBool v(void);
void init(int count);
};

The class opTaskBlock controls interprocess dependencies by making any number of processes wait for the completion of a task.

These are the steps involved when an opTaskBlock is used:

class opTaskBlock 
{
public:
opTaskBlock();
~opTaskBlock();
void start();
void finish();
void waitUntilFinished();
};

This class implements the basic operation of opThreadMgr::markRequests(). It uses opMutex and opSemaphore to implement a condition variable and to provide more refined control over execution dependency between processes than you have with opTaskBlock.

The application creates an opBlockingCounter initialized to count down from x: opBlockingCounter C(x). After that, a process will block on a call to C.waitForZero() until C.decrement() has been called x times. Naturally, calls to C.decrement() should correspond to the completion of tasks the application wants to wait for.

Class Declaration for opBlockingCounter

The class has the following main methods:

class opBlockingCounter
{
public:
opBlockingCounter(int count);
~opBlockingCounter();

void decrement(void);
void waitForZero(void);
};