Just trying to make this whole manual make more sense.
authorJosh Yelon <jyelon@uiuc.edu>
Wed, 25 Jun 1997 06:53:46 +0000 (06:53 +0000)
committerJosh Yelon <jyelon@uiuc.edu>
Wed, 25 Jun 1997 06:53:46 +0000 (06:53 +0000)
doc/converse/cmi.tex
doc/converse/cpm.tex
doc/converse/cpvmacros.tex
doc/converse/ldb.tex
doc/converse/manual.tex
doc/converse/msgmgr.tex
doc/converse/scheduler.tex
doc/converse/threads.tex
doc/converse/usermain.tex

index 7fb0786bfc698bd3f392e029e5885a7eda3b190f..4f8a39f58379502bca4af5362896786ff4d1653d 100644 (file)
@@ -1,58 +1,36 @@
-\chapter{Converse Machine Interface}
-
-\internal{
-\section{Initialization and Wrap-Up}
-
-\function{void ConverseInit(char *argv[])}
-\index{ConverseInit}
-\desc{This function initializes the machine interface. It should be
-called prior to any other Converse functions. 
-Multiple calls to this function in a process should
-be avoided. \param{argv} is in similar format as passed to
-\param{main(argc, argv)}. 
-They would be utilized by \param{ConverseInit()} to initialize
-machine specific parameters such as number of processors.}
-
-\function{void ConverseExit(void)}
-\index{ConverseExit}
-\desc{This function frees the resources acquired by Converse and wraps up. 
-Any other Converse function should not be called after a call to this function.
-\note{It does not terminate the calling
-process. A separate call to \param{exit()} is needed after 
-\param{ConverseExit()} to achieve this.}}
-}
-
-
-\section{Converse Handlers and Handler Numbers}
-
-Prior to sending a message, the Converse user writes a {\em handler}
-function that should be called by the receiving processor.  The
-Converse user puts a reference to the {\em handler} function in the
-message, and sends it to the destination processor.  The destination
-processor automatically calls the user's {\em handler} function,
-passing it the contents of the message.
-
-Ideally, this would be achieved by putting a pointer to the
-handler-function in the message.  However, in parallel programs
-running on heterogeneous machines, sending a function pointer in a
-message doesn't work.  As a substitute, we use {\em handler numbers}.
-To this end, Converse maintains a table mapping handler numbers to
-function pointers.  Each processor has its own copy of the mapping.
-There is a caution associated with this approach: it is the user's
-responsibility to ensure that all processors have identical mappings.
-This is easy to do, nonetheless, the user must be aware that this is
-(usually) required.
-
-Note that while they may be called {\em handler numbers}, they are
-essentially function numbers, and can be used as a general substitute
-for function pointers regardless of whether those functions are handler
-functions.
+\chapter{Machine Interface and Scheduler}
+
+This chapter describes two of Converse's modules: the CMI, and the
+CSD.  Together, they serve to transmit messages and schedule the
+delivery of messages.
+
+\section{Defining Handler Numbers}
+
+When a message arrives at a processor, it triggers the execution of a
+{\em handler function}, not unlike a UNIX signal handler.  The handler
+function receives, as an argument, a pointer to a copy of the message.
+The message itself specifies which handler function is to be
+called when the message arrives.  Messages are contiguous sequences of
+bytes.  The message has two parts: the header, and the data.  The data
+may contain anything you like.  The header contains a {\em handler
+number}, which specifies which handler function is to be executed when
+the message arrives.  Before you can send a message, you have to
+define the handler numbers.
+
+Converse maintains a table mapping handler numbers to function
+pointers.  Each processor has its own copy of the mapping.  There is a
+caution associated with this approach: it is the user's responsibility
+to ensure that all processors have identical mappings.  This is easy
+to do, nonetheless, the user must be aware that this is (usually)
+required.
+
+The following functions are provided to define the handler numbers:
 
 \function{typedef void (*CmiHandler)(void *)}
 \index{CmiHandler}
 \desc{Functions that handle Converse messages must be of this type.}
 
-\function {int CmiRegisterHandler(CmiHandler h)}
+\function{int CmiRegisterHandler(CmiHandler h)}
 \index{CmiRegisterHandler}
 \desc{This represents the standard technique for associating numbers
 with functions.  To use this technique, the Converse user registers
@@ -63,7 +41,7 @@ the functions, the same numbers on all processors.  This insures
 global consistency.  CmiRegisterHandler returns the number which was
 chosen for the function being registered.}
 
-\function {void CmiRegisterHandlerGlobal(int n, CmiHandler h)}
+\function {int CmiRegisterHandlerGlobal(CmiHandler h)}
 \index{CmiRegisterHandlerLocal}
 \desc{This represents a second registration technique.   The Converse
 user registers his functions on processor zero, using
@@ -72,7 +50,7 @@ broadcasting those handler numbers to other processors, and installing
 them using CmiNumberHandler below.  The user should take care not to
 invoke those handlers until they are fully installed.}
 
-\function {void CmiRegisterHandlerLocal(int n, CmiHandler h)}
+\function {int CmiRegisterHandlerLocal(CmiHandler h)}
 \index{CmiRegisterHandlerLocal}
 \desc{This function is used when one wishes to register functions
 in a manner that is not consistent across processors.  This function
@@ -98,74 +76,105 @@ registration techniques.  One may use all three registration methods
 in a program.  The system guarantees that no numbering conflicts will
 occur as a result of this combination.
 
+\section{Building Messages}
+
+To send a message, one first creates a buffer to hold the message.
+The buffer must be large enough to hold the header and the data.
+The buffer can be in any kind of memory: it could be a local variable,
+it could be a global, it could be allocated with {\tt malloc}, and
+finally, it could be allocated with {\tt CmiAlloc}.  The Converse user
+fills the buffer with the message data.  One puts a handler number
+in the message, thereby specifying which handler function the message
+should trigger when it arrives.  Finally, one uses a message-transmission
+function to send the message.
+
+The following functions are provided to help build message buffers:
+
+\function{void *CmiAlloc(int size)}
+\index{CmiAlloc}
+\desc{Allocates memory of size \param{size} in heap and returns pointer to 
+the usable space.  There are some message-sending functions that
+accept only message buffers that were allocated with CmiAlloc.  Thus,
+this is the preferred way to allocate message buffers.}
+
+\function{void CmiFree(void *ptr)}
+\index{CmiFree}
+\desc{This function frees the memory pointed to by \param{ptr}. \param{ptr}
+should be a pointer that was previously returned by \param{CmiAlloc}.}
+
 \function {\#define CmiMsgHeaderSizeBytes}
 \index{CmiMsgHeaderSizeBytes}
-\desc{Messages are continguous sequences of bytes.  The first few
-bytes bytes of the message is the {\em CMI header}.  The size of the
-header is defined by the preprocessor constant CmiMsgHeaderSizeBytes,
-which is found in in {\tt converse.h}.  When the user allocates a message,
-this number of bytes must be set aside at the front of the message for
-the {\em CMI header.}}
+\desc{This constant contains the size of the message header.  When one
+allocates a message buffer, one must set aside enough space for the header
+and the data.  This macro helps you to do so.}
 
 \function {void CmiSetHandler(int *MessageBuffer, int HandlerId)}
 \index{CmiSetHandler}
 \desc{This macro sets the handler number of a message to \param{HandlerId}.}
+
 \function {int CmiGetHandler(int *MessageBuffer)}
 \index{CmiGetHandler}
-\desc{This call returns the handler of a message in the form of a handler number.}
+\desc{This call returns the handler of a message in the form of a
+handler number.}
  
 \function {CmiHandler CmiGetHandlerFunction(int *MessageBuffer)}
 \index{CmiGetHandlerFunction}
-\desc{This call returns the handler of a message in the form of a function pointer.}
+\desc{This call returns the handler of a message in the form of a
+function pointer.}
+
+\function{void CmiGrabBuffer(void **pbuf)}
+\index{CmiGrabBuffer}
+\desc{A handler function receives a pointer to a message buffer
+as an argument.  Normally, it is supposed to copy the data out of the
+message buffer, and then return, at which time Converse automatically
+frees the message buffer.  However, a handler function may use
+CmiGrabBuffer to claim ownership of the message buffer (and therefore
+prevent Converse from freeing it).  Assuming, for example, that the
+handler function called its argument {\tt msg}, it would call {\tt
+CmiGrabBuffer(\&msg)}.  Afterward, {\tt msg} contains a pointer to the
+message, or a copy of it.  From that point forward, it is the user's
+responsibility to free the message using \param{CmiFree.}}
 
-\section{Point-To-Point Communication}
+\section{Sending Messages}
+
+The following functions allow you to send messages:
 
 \function{void CmiSyncSend(unsigned int destPE, unsigned int size, void *msg)}
 \index{CmiSyncSend}
+
 \desc{Sends \param{msg} of size \param{size} bytes to processor
-\param{destPE}. Message buffer for \param{msg} could be reused after
-the call returns.
-The first CmiMsgHeaderSizeBytes bytes of \param{msg} must be set aside
-for use by the system.  (This applies to all the calls below that send
-or broadcast a message.)}
+\param{destPE}.  The call does not return until the data has been
+copied from the user-provided message buffer into system buffers.
+Therefore, once this call returns, you are free to reuse the
+message buffer immediately.}
 
 \function{void CmiSyncSendAndFree(unsigned int destPE, unsigned int size, void *msg)}
 \index{CmiSyncSendAndFree}
 \desc{Sends \param{msg} of size \param{size} bytes to processor
-\param{destPE} and frees the message buffer for \param{msg}.}
+\param{destPE} and then {\tt CmiFree}s the message buffer \param{msg}.
+Caution: the message buffer {\em must} have been allocated using {\tt
+CmiAlloc}.}
 
 \function{CmiCommHandle CmiAsyncSend(unsigned int destPE, unsigned int size, void *msg)}
 \index{CmiAsyncSend}
-\desc{Initiates an asynchronous send of \param{msg} of length
-\param{size} bytes to processor \param{destPE} and returns a
-communication handle which could be used to enquire the status of this
-communication. Message buffer for \param{mesg} should not be reused or freed
-until communication is complete.}
+\desc{Sends a message of size \param{size} bytes to processor
+\param{destPE}.  This function returns before the data has even been
+copied out of the user's message buffer.  Therefore, the Converse
+user must leave the message buffer alone for a time after calling
+this function.  This function returns a communication handle which
+can be tested to determine whether or not the buffer can be reused
+yet.}
 
 \function{int CmiAsyncMsgSent(CmiCommHandle handle)}
 \index{CmiAsyncMsgSent}
-\desc{Returns the status of asynchronous send specified by
-communication handle \param{handle}.}
+\desc{Returns true if the communication specified by the given
+CmiCommHandle has proceeded to the point where the message buffer can
+be reused.}
 
 \function{void CmiReleaseCommHandle(CmiCommHandle handle)}
 \index{CmiReleaseCommHandle}
 \desc{Releases the communication handle \param{handle} and
-associated resources. It does not free the message buffer.
-\param{handle} could be reused by CMI for another communication after
-this call succeeds.}
-
-\function{CmiCommHandle CmiAsyncVectorSend(int destPE, int len, int sizes[], char *msgComps[])}
-\desc{Initiates an asynchronous send of data to processor
-\param{destPE}.  The data consists of \param{len} pieces residing in
-different areas of memory, which are logically concatenated.  The
-\param{msgComps} array contains pointers to the pieces; the size of
-\param{msgComps[i]} is taken from \param{sizes[i]}. 
-This function returns a communication handle which could be used to enquire
-about the status of communication using \param{CmiAsyncMsgSent()}.
-Individual pieces of data as well as the arrays \param{sizes} and
-\param{msgComps} should not be overwritten or freed before the
-communication is complete.}
+associated resources. It does not free the message buffer.}
 
 \function{void CmiSyncVectorSend(int destPE, int len, int sizes[], char *msgComps[])}
 \desc{Synchronous send of data to processor
@@ -183,22 +192,157 @@ different areas of memory, which are logically concatenated.  The
 different areas of memory, which are logically concatenated.  The
 \param{msgComps} array contains pointers to the pieces; the size of
 \param{msgComps[i]} is taken from \param{sizes[i]}. 
-The message components specified in \param{msgComps} are freed by this function
-therefore, they should be dynamically allocated using \param{CmiAlloc()}.
-However, the \param{sizes} and \param{msgComps} array themselves are not
-freed. 
-}
+The message components specified in \param{msgComps} are {\tt
+CmiFree}d by this function therefore, they should be dynamically
+allocated using \param{CmiAlloc()}.  However, the \param{sizes} and
+\param{msgComps} array themselves are not freed.}
 
-\function{void CmiGrabBuffer(void **pbuf)}
-\index{CmiGrabBuffer}
-\desc{Transfers the ownership of the buffer pointed to by
-\param{*pbuf} to the calling procedure. On machines where 
-\param{*pbuf} points to a
-system buffer which cannot be allocated to the user, 
-CMI copies the buffer contents to newly allocated user
-space and updates \param{*pbuf} to point to the new buffer.
-In either case, the user should eventually free the buffer by calling
-\param{CmiFree}.}
+\function{CmiCommHandle CmiAsyncVectorSend(int destPE, int len, int sizes[], char *msgComps[])}
+\desc{Initiates an asynchronous send of data to processor
+\param{destPE}.  The data consists of \param{len} pieces residing in
+different areas of memory, which are logically concatenated.  The
+\param{msgComps} array contains pointers to the pieces; the size of
+\param{msgComps[i]} is taken from \param{sizes[i]}. 
+This function returns a communication handle which could be used to enquire
+about the status of communication using \param{CmiAsyncMsgSent()}.
+Individual pieces of data as well as the arrays \param{sizes} and
+\param{msgComps} should not be overwritten or freed before the
+communication is complete.}
+
+\section{Broadcasting Messages}
+
+\function{void CmiSyncBroadcast(unsigned int size, void *msg)}
+\index{CmiSyncBroadcast}
+\desc{Sends \param{msg} of length \param{size} bytes to all processors
+excluding the processor on which the caller resides. }
+
+\function{void CmiSyncBroadcastAndFree(unsigned int size, void *msg)}
+\index{CmiSyncBroadcastAndFree}
+\desc{Sends \param{msg} of length \param{size} bytes to all processors
+excluding the processor on which the caller resides.  Uses {\tt
+CmiFree} to deallocate the message buffer for \param{msg} when the
+broadcast completes. Therefore \param{msg} must point to a buffer
+allocated with {\tt CmiAlloc}.}
+
+\function{void CmiSyncBroadcastAll(unsigned int size, void *msg)}
+\index{CmiSyncBroadcastAll}
+\desc{Sends \param{msg} of length \param{size} bytes to all processors
+including the processor on which the caller resides. This function
+does not free the message buffer for \param{msg}.}
+
+\function{void CmiSyncBroadcastAllAndFree(unsigned int size, void *msg)}
+\index{CmiSyncBroadcastAllAndFree}
+\desc{Sends \param{msg} of length \param{size} bytes to all processors
+including the processor on which the caller resides. This function
+frees the message buffer for \param{msg} before returning, so
+\param{msg} must point to a dynamically allocated buffer.}
+
+\function{CmiCommHandle CmiAsyncBroadcast(unsigned int size, void *msg)}
+\index{CmiAsyncBroadcast}
+\desc{Initiates asynchronous broadcast of message \param{msg} of
+length \param{size} bytes to all processors excluding the processor on
+which the caller resides. It returns a communication handle which
+could be used to check the status of this send using
+\param{CmiAsyncMsgSent()}. \param{msg} should not be overwritten or
+freed before the communication is complete.}
+
+\function{CmiCommHandle CmiAsyncBroadcastAll(unsigned int size, void *msg)}
+\index{CmiAsyncBroadcastAll}
+\desc{Initiates asynchronous broadcast of message \param{msg} of
+length \param{size} bytes to all processors including the processor on
+which the caller resides. It returns a communication handle which
+could be used to check the status of this send using
+\param{CmiAsyncMsgSent()}. \param{msg} should not be overwritten or
+freed before the communication is complete.}
+
+\section{Scheduling Messages}
+
+The scheduler queue is a powerful priority queue.  The following
+functions can be used to place messages into the scheduler queue.
+These messages are treated very much like newly-arrived messages: when
+they reach the front of the queue, they trigger handler functions,
+just like messages transmitted with Cmi functions.  Note that unlike
+the Cmi send functions, these cannot move messages across processors.
+
+\function{void CsdEnqueueGeneral(void *Message, int strategy, int priobits, int *prioptr)}
+\index{CsdEnqueueGeneral}
+\desc{This call enqueues a message to the scheduler's queue, to be processed in 
+accordance with the queueing \param{strategy}. \param{priobits} and
+\param{prioptr} specify information about priority associated with the message
+if prioritized queueing strategies are used. \param{strategy} can take values 
+defined in {\tt converse.h} depending upon the queueing strategy (FIFO or LIFO)
+and the nature of priority information used (none, integer or bit-vector).
+These predefined constants are: 
+{\tt CQS\_QUEUEING\_FIFO}, {\tt CQS\_QUEUEING\_LIFO},
+{\tt CQS\_QUEUEING\_IFIFO}, {\tt CQS\_QUEUEING\_ILIFO},
+{\tt CQS\_QUEUEING\_BFIFO}, and\\  {\tt CQS\_QUEUEING\_BLIFO}.
+This call is usually made from
+a message handler when the message is not to be processed immediately,
+but may be processed later (e.g. depending on the message's priority).
+Also, it is used to enqueue local ready entities, such as threads.
+\note{It is necessary to grab the ownership of the message buffer before queuing
+because on returning from the handler, the system can reuse the buffer.}}
+
+\function {void CsdEnqueue(void *Message)}
+\index{CsdEnqueue}
+\desc{This macro is a shorthand for 
+{\tt CsdEnqueueGeneral(Message, CQS\_QUEUEING\_FIFO,0, NULL)} 
+provided here for backward compatibility.}
+
+\function{void CsdEnqueueFifo(void *Message)}
+\index{CsdEnqueueFifo}
+\desc{This macro is a shorthand for 
+{\tt CsdEnqueueGeneral(Message, CQS\_QUEUEING\_FIFO,0, NULL)} 
+provided here for backward compatibility.}
+
+
+\function{void CsdEnqueueLifo(void *Message)}
+\index{CsdEnqueueLifo}
+\desc{This macro is a shorthand for
+{\tt CsdEnqueueGeneral(Message, CQS\_QUEUEING\_LIFO,0, NULL)} 
+provided here for backward compatibility.}
+
+\function{int CsdEmpty()}
+\index{CsdEmpty}
+\desc{This function returns non-zero integer when the scheduler's queue
+is empty, zero otherwise.}
+
+\section{Polling for Messages}
+
+As we stated earlier, Converse messages trigger handler functions when
+they arrive.  In fact, for this to work, the processor must
+occasionally poll for messages.  When the user starts Converse, he can
+put it into one of several modes.  In the normal mode, the message
+polling happens automatically.  However {\em user-calls-scheduler}
+mode is designed to let the user poll manually.  To do this, the user
+must use one of two polling functions: CmiDeliverMsgs, or
+CsdScheduler.  CsdScheduler is more general, it will notice any
+Converse event.  CmiDeliverMsgs is a lower-level function that ignores
+all events except for recently-arrived messages.  (In particular, it
+ignores messages in the scheduler queue).  You can save a tiny amount
+of overhead by using the lower-level function.  We recommend the use
+of CsdScheduler for all applications except those that are using only
+the lowest level of Converse, the Cmi.  A third polling function,
+CmiDeliverSpecificMsg, is used when you know the exact event you want
+to wait for: it does not allow any other event to occur.
+
+\function {void CsdScheduler(int NumberOfMessages)}
+\index{CsdScheduler}
+\desc{This call invokes the Converse scheduler, which repeatedly
+delivers messages to their handlers (i.e. invokes the handler for each
+message it selects).  Each message header encodes a pointer to its
+handler as described in the next chapter. 
+In each iteration, the scheduler first looks for any
+message that  has arrived from another processor, and delivers it.
+If there isn't any, it selects a message from the locally enqueued
+messages (see below), and delivers it.
+The {\tt NumberOfMessages}
+parameter specifies how many messages should be processed (i.e. delivered
+to their handlers). If set to -1, the scheduler continues delivering
+messages until CsdExitScheduler() is called from a message handler.
+if {\tt NumberOfMessages} is 0, the scheduler continues delivering messages
+until it exhausts its supply of messages (i.e. becomes idle) or some 
+handler calls CsdExitScheduler().}
 
 \function{int CmiDeliverMsgs(int MaxMsgs)}
 \index{CmiDeliverMsgs}
@@ -222,6 +366,12 @@ with its handler field equal to \param{HandlerId}. This functions queues
 the remaining messages retrieved from the network. It returns after the 
 invoked handler function returns.}
 
+\function {void CsdExitScheduler(void)}
+\index{CsdExitScheduler}
+\desc{This call causes the scheduler
+to stop processing messages when control has returned back to it.
+The scheduler then returns to its calling routine.}
+
 \internal{
 \section{Global Pointer}
 
@@ -259,52 +409,7 @@ pointer \param{gptr}.  This function returns a  communication handle
 which could be used to  enquire about the status of this operation.}
 }
 
-\section{Broadcast}
-
-\function{void CmiSyncBroadcast(unsigned int size, void *msg)}
-\index{CmiSyncBroadcast}
-\desc{Sends \param{msg} of length \param{size} bytes to all processors
-excluding the processor on which the caller resides. }
-
-\function{void CmiSyncBroadcastAndFree(unsigned int size, void *msg)}
-\index{CmiSyncBroadcastAndFree}
-\desc{Sends \param{msg} of length \param{size} bytes to all processors
-excluding the processor on which the caller resides. Frees the message buffer
-for \param{msg} when the broadcast completes. Therefore \param{msg} must
-point to a dynamically allocated buffer.}
-
-\function{void CmiSyncBroadcastAll(unsigned int size, void *msg)}
-\index{CmiSyncBroadcastAll}
-\desc{Sends \param{msg} of length \param{size} bytes to all processors
-including the processor on which the caller resides. This function
-does not free the message buffer for \param{msg}.}
-
-\function{void CmiSyncBroadcastAllAndFree(unsigned int size, void *msg)}
-\index{CmiSyncBroadcastAllAndFree}
-\desc{Sends \param{msg} of length \param{size} bytes to all processors
-including the processor on which the caller resides. This function
-frees the message buffer for \param{msg} before returning, so
-\param{msg} must point to a dynamically allocated buffer.}
-
-\function{CmiCommHandle CmiAsyncBroadcast(unsigned int size, void *msg)}
-\index{CmiAsyncBroadcast}
-\desc{Initiates asynchronous broadcast of message \param{msg} of
-length \param{size} bytes to all processors excluding the processor on
-which the caller resides. It returns a communication handle which
-could be used to check the status of this send using
-\param{CmiAsyncMsgSent()}. \param{msg} should not be overwritten or
-freed before the communication is complete.}
-
-\function{CmiCommHandle CmiAsyncBroadcastAll(unsigned int size, void *msg)}
-\index{CmiAsyncBroadcastAll}
-\desc{Initiates asynchronous broadcast of message \param{msg} of
-length \param{size} bytes to all processors including the processor on
-which the caller resides. It returns a communication handle which
-could be used to check the status of this send using
-\param{CmiAsyncMsgSent()}. \param{msg} should not be overwritten or
-freed before the communication is complete.}
-
-\section{Timer}
+\section{The Timer}
 
 \function{double CmiTimer(void)}
 \index{CmiTimer}
@@ -327,30 +432,6 @@ caller resides. A processor Id is between \param{0} and \param{CmiNumPe()-1}.}
 
 Also see the calls in Section~\ref{utility}.  % put a ref here..??
 
-\section{Memory Management}
-
-\function{void *CmiAlloc(int size)}
-\index{CmiAlloc}
-\desc{Allocates memory of size \param{size} in heap and returns pointer to 
-the usable space. All the converse entities (e.g. messages) should be 
-allocated with \param{CmiAlloc} and not with standard C library 
-functions such as \param{malloc} because converse uses \param{CmiFree} to free 
-these entities internally. \note{Currently this function is a simple wrapper
-around \param{malloc}. However, in future, sophisticated memory allocation
-strategies will be incorporated into converse.}}
-
-\function{int CmiSize(void *ptr)}
-\index{CmiSize}
-\desc{This function returns the allocated size of memory pointed to by 
-\param{ptr}. \param{ptr} should be returned by an earlier call to 
-\param{CmiAlloc}.}
-
-\function{void CmiFree(void *ptr)}
-\index{CmiFree}
-\desc{This function frees the memory pointed to by \param{ptr}. \param{ptr}
-should be returned by an earlier call to \param{CmiAlloc}.}
-
-
 \section{Input/Output}
 
 \function{void CmiPrintf(char *format, arg1, arg2, ...)}
index 7b0bdb09defbe12c510374bf951dd19d7b723776..2add5f7298656ee774f9c378bea71dddfa3dc069 100644 (file)
@@ -1,12 +1,12 @@
-\chapter{Converse Parameter Marshalling}
+\chapter{Automatic Parameter Marshalling}
 
-The Converse Parameter Marshalling module's provides a concise means
-of invoking functions on remote processors.  The CPM module handles
-all the details of packing, transmitting, translating, and
-unpacking the arguments.  It also takes care of converting function
-pointers into function handles.  With all these details out of the
-way, it is possible to perform remote function invocation in a single
-line of code.
+Automatic Parameter Marshalling is a concise means of invoking
+functions on remote processors.  The CPM module handles all the
+details of packing, transmitting, translating, and unpacking the
+arguments.  It also takes care of converting function pointers into
+handler numbers.  With all these details out of the way, it is
+possible to perform remote function invocation in a single line of
+code.
 
 \section{CPM Basics}
 
@@ -83,15 +83,17 @@ short program {\tt myprog.c}:
  8:    user_main(int argc, char **argv)
  9:    {
 10:      int i;
-11:      ConverseInit(argv);
-12:      CpmModuleInit();
-13:      CpmInitializeThisModule();
-14:      if (CmiMyPe()==0)
-15:        for (i=1; i<CmiNumPes(); i++)
-16:          Cpm_print_integer(CpmSend(i), rand());
-17:      CsdScheduler(-1);
-18:      ConverseExit(0);
-19:    }
+11:      CpmModuleInit();
+12:      CpmInitializeThisModule();
+13:      if (CmiMyPe()==0)
+14:        for (i=1; i<CmiNumPes(); i++)
+15:          Cpm_print_integer(CpmSend(i), rand());
+16:    }
+17:    
+18:    main(int argc, char **argv)
+19:    {
+20:      ConverseInit(argc, argv, user_main, 0, 0);
+21:    }
 \end{verbatim}
 
 Lines 3-6 of this program contain a simple C function that prints an
@@ -99,19 +101,17 @@ integer.  The function is marked with the word {\tt CpmInvokable}.
 When the CPM scanner sees this word, it adds the function {\tt
 Cpm\_print\_integer} to the file {\tt myprog.cpm.h}.  The program
 includes {\tt myprog.cpm.h} on line 1, and initializes the code in
-there on line 13.  Each call to {\tt Cpm\_print\_integer} on line 16
+there on line 12.  Each call to {\tt Cpm\_print\_integer} on line 15
 builds a message that invokes {\tt print\_integer}.  The
 destination-argument {\tt CpmSend(i)} causes the message to be sent to
-the {\it i}'th processor.  Note the presence of {\tt CsdScheduler} on
-line 17: messages that are sent by the CPM mechanism are received and
-handled by the scheduler, like any other Converse message.
+the {\it i}'th processor.
 
 The effect of this program is that the first processor orders each of
 the other processors to print a random number.  Note that the example
 is somewhat minimalist, for example, it doesn't contain any code for
 terminating itself.  Also note that it would have been more efficient
 to use an explicit broadcast.  Broadcasts are described later.
-\pagebreak
+
 All launchers accept a {\it CpmDestination} as their first argument.  A
 {\it CpmDestination} is actually a pointer to a small C structure
 containing routing and handling information.  The CPM module has many
@@ -216,14 +216,16 @@ Here is a second program, {\tt example2.c}, which uses array arguments:
 10:
 11:    user_main(int argc, char **argv)
 12:    {
-13:      ConverseInit(argv);
-14:      CpmModuleInit();
-15:      CpmInitializeThisModule();
-16:      if (CmiMyPe()==0)
-17:        Cpm_print_program_arguments(CpmSend(1), argc, argv);
-19:      CsdScheduler(-1);
-20:      ConverseExit(0);
-21:    }
+13:      CpmModuleInit();
+14:      CpmInitializeThisModule();
+15:      if (CmiMyPe()==0)
+16:        Cpm_print_program_arguments(CpmSend(1), argc, argv);
+17:    }
+18:
+19:    main(int argc, char **argv)
+20:    {
+21:      ConverseInit(argc, argv, user_main, 0, 0);
+22:    }
 \end{verbatim}
 
 The word {\tt CpmStr} is a CPM built-in type, it represents a
@@ -361,7 +363,6 @@ Cpm message is sent.  This knowledge is only necessary to those
 wishing to invent new kinds of destinations.  Others can skip this
 section.
 
-\pagebreak
 The basic steps taken when sending a CPM message are:
 
 \begin{itemize}
index 5ac0b95d59c87801d9b460226186a4dade1ad9f1..c83f1988c67dcc208486d594a7d1d5246b7c9fa3 100644 (file)
 % REVISION HISTORY:
 %
 % $Log$
-% Revision 1.5  1995-11-16 22:11:11  milind
+% Revision 1.6  1997-06-25 06:53:48  jyelon
+% Just trying to make this whole manual make more sense.
+%
+% Revision 1.5  1995/11/16 22:11:11  milind
 % removed hardwired reference.
 %
 % Revision 1.4  1995/11/01  21:16:23  milind
@@ -32,7 +35,6 @@
 
 \chapter{Machine Model and Global Variables}
 
-
 The machine model assumed by Converse consists of a collection of
 nodes, where each node comprises of a number of processors that
 share memory. In addition, each of the processors could have multiple
@@ -116,8 +118,6 @@ CtvAccess(variable)
 \index{CtvAccess}
 
 
-\subsection{Example of Usage}
-
     A sample code to illustrate the usage of the macros is provided
     in Figure~\ref{fig:cpv}.
     There are a few rules that user must pay attention: The
index 1120f289f5b1e1d1718fdc5de84b7aec87c62575..acb5c93f7d3e7ad3459b74763e4f5e07b2278e6b 100644 (file)
@@ -1,5 +1,4 @@
-\chapter{Load Balancer Calls}
-
+\chapter{Load Balancer}
 
 Converse provides the programmer with a number of Load Balancing
 strategies in order to distribute work among the processors in the
index 728004a534f4b982938a6580a4b2b9c3ac1d5cc5..d21add14388bc7242531f05444cc282d1cf10aaa 100644 (file)
@@ -18,7 +18,7 @@
 \parskip 0.05in
  
 \newcommand{\internal}[1]{}
-\newcommand{\function}[1]{{\noindent{\sf {#1}}\\}}
+\newcommand{\function}[1]{{\noindent{\bf {#1}}\\}}
 \newcommand{\param}[1]{{\tt {#1}}}
 \newcommand{\note}[1]{\noindent{(Note: {\em {#1}})}}
 \newcommand{\desc}[1]{{#1}}
@@ -67,17 +67,9 @@ Brunner and Laxmikant Kale.
 
 \input{usermain}
 \input{cmi}
-\input{scheduler}
 \input{queue}
-
-\chapter{Message storage/retrieval and Threads}
-
-The calls in this chapter can be used to put together runtime systems
-for languages that support threads and tag-based message retrieval.
-
 \input{msgmgr}
 \input{threads}
-%\input{thsync}
 \input{cpvmacros}
 \input{cpm}
 \input{ldb}
index f758d65c1ed2b1fed228f0a8f2cb30e910ca165c..5af884af5a8ea5804bd003548e3db9b7dadfbe90 100644 (file)
@@ -1,3 +1,8 @@
+\chapter{Tag Matching and Message Storage}
+
+The calls in this chapter can be used to put together runtime systems
+for languages that support tag-based message retrieval.
+
 \section{Message Manager Calls}
 
 To use the message manager, you must include {\tt converse.h} and
index 05762aebd3406e6b70de042c7d8e7e972f4c04d8..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 100644 (file)
@@ -1,80 +0,0 @@
-
-\chapter{Scheduler Calls}
-
-%These are the calls/macros provided by the Converse scheduler.
-%All declarations are in converse.h.
-
-\internal{
-\function {void CsdInit(void)}
-This call initializes the Converse scheduler, it is called from
-ConverseInit().
-}
-
-\function {void CsdScheduler(int NumberOfMessages)}
-\index{CsdScheduler}
-\desc{This call invokes the Converse scheduler, which repeatedly
-delivers messages to their handlers (i.e. invokes the handler for each
-message it selects).  Each message header encodes a pointer to its
-handler as described in the next chapter. 
-In each iteration, the scheduler first looks for any
-message that  has arrived from another processor, and delivers it.
-If there isn't any, it selects a message from the locally enqueued
-messages (see below), and delivers it.
-The {\tt NumberOfMessages}
-parameter specifies how many messages should be processed (i.e. delivered
-to their handlers). If set to -1, the scheduler continues delivering
-messages until CsdExitScheduler() is called from a message handler.
-if {\tt NumberOfMessages} is 0, the scheduler continues delivering messages
-until it exhausts its supply of messages (i.e. becomes idle) or some 
-handler calls CsdExitScheduler().}
-
-\function {void CsdExitScheduler(void)}
-\index{CsdExitScheduler}
-\desc{This call causes the scheduler
-to stop processing messages when control has returned back to it.
-The scheduler then returns to its calling routine.}
-
-\function{void CsdEnqueueGeneral(void *Message, int strategy, int priobits, int *prioptr)}
-\index{CsdEnqueueGeneral}
-\desc{This call enqueues a message to the scheduler's queue, to be processed in 
-accordance with the queueing \param{strategy}. \param{priobits} and
-\param{prioptr} specify information about priority associated with the message
-if prioritized queueing strategies are used. \param{strategy} can take values 
-defined in {\tt converse.h} depending upon the queueing strategy (FIFO or LIFO)
-and the nature of priority information used (none, integer or bit-vector).
-These predefined constants are: 
-{\tt CQS\_QUEUEING\_FIFO}, {\tt CQS\_QUEUEING\_LIFO},
-{\tt CQS\_QUEUEING\_IFIFO}, {\tt CQS\_QUEUEING\_ILIFO},
-{\tt CQS\_QUEUEING\_BFIFO}, and\\  {\tt CQS\_QUEUEING\_BLIFO}.
-This call is usually made from
-a message handler when the message is not to be processed immediately,
-but may be processed later (e.g. depending on the message's priority).
-Also, it is used to enqueue local ready entities, such as threads.
-\note{It is necessary to grab the ownership of the message buffer before queuing
-because on returning from the handler, the system can reuse the buffer.}}
-
-\function {void CsdEnqueue(void *Message)}
-\index{CsdEnqueue}
-\function{void CsdEnqueueFifo(void *Message)}
-\index{CsdEnqueueFifo}
-\desc{
-       This macro is a shorthand for 
-       {\tt CsdEnqueueGeneral(Message, CQS\_QUEUEING\_FIFO,0, NULL)} 
-       provided here for backward compatibility.
-}
-
-
-\function{void CsdEnqueueLifo(void *Message)}
-\index{CsdEnqueueLifo}
-\desc{
-       This macro is a shorthand for
-       {\tt CsdEnqueueGeneral(Message, CQS\_QUEUEING\_LIFO,0, NULL)} 
-       provided here for backward compatibility.
-}
-
-\function{int CsdEmpty()}
-\index{CsdEmpty}
-\desc{
-       This function returns non-zero integer when the scheduler's queue
-       is empty, zero otherwise.
-}
index 0843cdef4da23fb42d2b363c90d6ee0bd67be571..d6ddf3e395593ea332672226eec4a779d82a8148 100644 (file)
@@ -1,4 +1,7 @@
-\section{Thread Calls}
+\chapter{Threads}
+
+The calls in this chapter can be used to put together runtime systems
+for languages that support threads.
 
 To use the threads package, you must include {\tt converse.h} and link
 with the converse library.  Note: threads are not implemented on all
@@ -103,10 +106,11 @@ CthThread}.}
 
 \function{void CthFree(CthThread t)}
 \index{CthFree}
-\desc{Frees thread {\tt t}.  You may even free the currently-executing
-thread, although the free will actually be postponed until the thread
-suspends.  This is how a thread terminates itself: it calls {\tt
-CthFree(CthSelf())}, then gives up control to another thread.}
+\desc{Frees thread {\tt t}.  You may ONLY free the
+currently-executing thread (yes, this sounds strange, it's
+historical).  Naturally, the free will actually be postponed until the
+thread suspends.  This is how a thread terminates itself: it calls
+{\tt CthFree(CthSelf())}, then gives up control to another thread.}
 
 \function{void CthSuspend()}
 \index{CthSuspend}
index 394dd3f842de5526217f08e43f1e412b5314a1bd..bcbb635595c9c643e14eca9bf1ae734e59a6a6e4 100644 (file)
@@ -22,40 +22,42 @@ When you run your program, some of the processors automatically invoke
 invoked {\tt main} must must call ConverseInit.  This initializes the
 entire Converse system.  Converse then initiates, on {\em all}
 processors, the execution of the user-supplied start-function {\tt
-fn(argc, argv)} followed by the Converse scheduler.  Once the
-scheduler exits on all processors, the Converse system shuts down, and
-your program terminates.  Note that in this case, ConverseInit never
-returns.  The user is not allowed to call the Converse scheduler
-manually.
+fn(argc, argv)}.  When this function returns, Converse automatically
+calls {\tt CsdScheduler}, a function that polls for messages and
+executes their handlers (see chapter 2).  Once {\tt CsdScheduler}
+exits on all processors, the Converse system shuts down, and your
+program terminates.  Note that in this case, ConverseInit never
+returns.  The user is not allowed to poll for messages manually.
 
-ConverseInit-returns Mode: {\tt initret=1}
+User-calls-scheduler Mode: {\tt usched=1, initret=0}
+
+This is how the user initializes Converse if he wants to poll for
+messages and other events manually.  In normal mode, it is assumed
+that the user-supplied start-function {\tt fn(argc, argv)} is just for
+initialization, and that the remainder of the lifespan of the program
+is spent in the (automatically-invoked) function {\tt CsdScheduler},
+polling for messages.  In user-calls-scheduler mode, however, it is
+assumed that the user-supplied start-function will perform the {\em
+entire computation}, including polling for messages.  Thus,
+ConverseInit will not automatically call {\tt CsdScheduler} for you.
+When the user-supplied start-function ends, Converse shuts down.  This
+mode is not supported on the sim version.  This mode can be combined
+with ConverseInit returns mode below.}
+
+ConverseInit-returns Mode: {\tt usched=1, initret=1}
 
 This option is used when you want ConverseInit to return.  All
 processors which automatically invoked {\tt main} must call
 ConverseInit.  This initializes the entire Converse System.  On all
-processors which {\em did not} automatically invoke {\tt main}, Converse
-initiates the user-supplied initialization function {\tt fn(argc,
-argv)} followed by the Converse scheduler.  Meanwhile, on those
-processors which {\em did} automatically invoke {\tt main}, ConverseInit
-returns.  Shutdown is initiated when the processors that {\em did}
-automatically invoke {\tt main} call ConverseExit, and when the other
-processors exit the scheduler.  This option is not supported
-by the sim version.
-
-User-calls-scheduler Mode: {\tt usched=1}
-
-This is how the user initializes Converse if he wants to perform all
-the scheduling manually.  In normal mode, it is assumed that the
-user-supplied start-function {\tt fn(argc, argv)} is just for
-initialization, and that the remainder of the lifespan of the program
-is spent in the (automatically-invoked) Converse scheduler.  In
-user-calls-scheduler mode, however, it is assumed that the
-user-supplied start-function will perform the {\em entire
-computation}, including scheduling.  Thus, ConverseInit will not
-automatically execute the scheduler for you.  When the user-supplied
-start-function ends, Converse shuts down.  This mode is not supported
-on the sim version.  This mode can be combined with ConverseInit
-returns mode.}
+processors which {\em did not} automatically invoke {\tt main},
+Converse initiates the user-supplied initialization function {\tt
+fn(argc, argv)}.  Meanwhile, on those processors which {\em did}
+automatically invoke {\tt main}, ConverseInit returns.  Shutdown is
+initiated when the processors that {\em did} automatically invoke {\tt
+main} call ConverseExit, and when the other processors return from
+{\tt fn}.  In this mode, all polling for messages must be done
+manually (probably using CsdScheduler explicitly).  This option is not
+supported by the sim version.
 
 \function{void ConverseExit(void)}
 \index{ConverseExit}