Made convext manual to use pplmanual.sty.
authorMilind Bhandarkar <milind@cs.uiuc.edu>
Mon, 11 Dec 2000 22:19:28 +0000 (22:19 +0000)
committerMilind Bhandarkar <milind@cs.uiuc.edu>
Mon, 11 Dec 2000 22:19:28 +0000 (22:19 +0000)
doc/convext/cldb.tex
doc/convext/cpath.tex
doc/convext/cpm.tex
doc/convext/futures.tex
doc/convext/ldb.tex
doc/convext/manual.tex
doc/convext/msgmgr.tex
doc/convext/pthreads.tex
doc/convext/random.tex

index d9d869d24efa57af2bad750c77b90d59dd080ac5..1c8bf4087812b306acef4cedb781d203832894d0 100644 (file)
@@ -1,6 +1,6 @@
 \chapter{Load Balancing}
 
-\section{Using Converse Load Balancers}
+\section{Using \converse{} Load Balancers}
 
 This module defines a function {\bf CldEnqueue} that sends a message
 to a lightly-loaded processor.  It automates the process of finding a
@@ -28,7 +28,7 @@ choose a {\sl load-balancing strategy}.  That means you link in one of
 several implementations of the load-balancer.  Most are sophisticated,
 as described above.  But some are simple and cheap, like the random
 strategy.  The process of choosing a strategy is described in the
-manual {\em Converse Installation and Usage}.
+manual {\em \converse{} Installation and Usage}.
 
 %For efficiency reasons, the load-balancing module needs to be able to
 %cache some data in the messages it manipulates.  Every message sent
@@ -125,12 +125,12 @@ number, the message is sent to the specified processor and enqueued
 with the appropriate priority.  {\bf CldEnqueue} frees the message buffer
 using {\bf CmiFree}.}
 
-The following simple example illustrates how a Converse program can
+The following simple example illustrates how a \converse{} program can
 make use of the load balancers.
 
 \noindent {\tt hello.c:}
 
-\begin{verbatim}
+\begin{alltt}
 #include <stdio.h>
 #include "converse.h"
 #define CHARES 10
@@ -139,30 +139,30 @@ void startup(int argc, char *argv[]);
 void registerAndInitialize();
 
 typedef struct pemsgstruct
-{
+\{
   char header[CmiExtHeaderSizeBytes];
   int pe, id, pfnx;
   int queuing, priobits;
   unsigned int prioptr;
-} pemsg;
+\} pemsg;
 
 CpvDeclare(int, MyHandlerIndex);
 CpvDeclare(int, InfoFnIndex);
 CpvDeclare(int, PackFnIndex);
 
 int main(int argc, char *argv[]) 
-{
+\{
   ConverseInit(argc, argv, startup, 0, 0);
   CsdScheduler(-1);
-}
+\}
 
 void startup(int argc, char *argv[])
-{
+\{
   pemsg *msg;
   int i;
   
   registerAndInitialize();
-  for (i=0; i<CHARES; i++) {
+  for (i=0; i<CHARES; i++) \{
     msg = (pemsg *)malloc(sizeof(pemsg));
     msg->pe = CmiMyPe();
     msg->id = i;
@@ -171,27 +171,27 @@ void startup(int argc, char *argv[])
     msg->priobits = 0;
     msg->prioptr = 0;
     CmiSetHandler(msg, CpvAccess(MyHandlerIndex));
-    CmiPrintf("[%d] sending message %d\n", msg->pe, msg->id);
+    CmiPrintf("[%d] sending message %d\verb+\+n", msg->pe, msg->id);
     CldEnqueue(CLD_ANYWHERE, msg, CpvAccess(InfoFnIndex));
     /*    CmiSyncSend(i, sizeof(pemsg), &msg); */
-  }
-}
+  \}
+\}
 
 void MyHandler(pemsg *msg)
-{
-  CmiPrintf("Message %d created on %d handled by %d.\n", msg->id, msg->pe, 
+\{
+  CmiPrintf("Message %d created on %d handled by %d.\verb+\+n", msg->id, msg->pe, 
            CmiMyPe());
-}
+\}
 
 void InfoFn(pemsg *msg, CldPackFn *pfn, int *len, int *queuing, int *priobits, 
            unsigned int *prioptr)
-{
+\{
   *pfn = (CldPackFn)CmiHandlerToFunction(msg->pfnx);
   *len = sizeof(pemsg);
   *queuing = msg->queuing;
   *priobits = msg->priobits;
   prioptr = &(msg->prioptr);
-}
+\}
 
 void PackFn(pemsg **msg)
 {
@@ -206,19 +206,19 @@ void registerAndInitialize()
   CpvInitialize(int, PackFnIndex);
   CpvAccess(PackFnIndex) = CldRegisterPackFn((CldPackFn)PackFn);
 }
-\end{verbatim}
+\end{alltt}
 
-\section{How to Write a Load Balancer for Converse/Charm++}
+\section{How to Write a Load Balancer for \converse{}/\charmpp{}}
 
 \subsection{Introduction}
 
 This manual details how to write your own general-purpose
-message-based load balancer for Converse.
-A Converse load balancer can be used by any Converse program, but also
-serves as a {\sl seed} load balancer for Charm++ chare creation messages.
+message-based load balancer for \converse{}.
+A \converse{} load balancer can be used by any \converse{} program, but also
+serves as a {\sl seed} load balancer for \charmpp{} chare creation messages.
 Specifically, to use a load balancer, you would pass messages to
 CldEnqueue rather than directly to the scheduler.  This is the default
-behavior with chare creation message in Charm++.  Thus, the primary
+behavior with chare creation message in \charmpp{}.  Thus, the primary
 provision of a new load balancer is an implementation of the
 CldEnqueue function.
 
@@ -228,7 +228,7 @@ Throughout this manual, we will occasionally refer to the source code
 of two provided load balancers, the random initial placement load balancer
 ({\tt cldb.rand.c}) and the graph-based load balancer ({\tt
 cldb.graph.c}).  The functioning of these balancers is described in
-the Charm++ Extensions manual load balancing section.
+the \charmpp{} manual load balancing section.
 
 In addition, a special utility is provided that allows us to add and
 remove load-balanced messages from the scheduler's queue.  The source
@@ -249,19 +249,19 @@ approximately half of its load to (K+1)\%N, every 100 milliseconds
 The minimal requirements for a load balancer are illustrated by the
 following code.
 
-\begin{verbatim}
+\begin{alltt}
 #include <stdio.h>
 #include "converse.h"
 
 char *CldGetStrategy(void)
-{
+\{
   return "test";
-}
+\}
 
 CpvDeclare(int, CldHandlerIndex);
 
 void CldHandler(void *msg)
-{
+\{
   CldInfoFn ifn; CldPackFn pfn;
   int len, queueing, priobits; unsigned int *prioptr;
   
@@ -270,28 +270,28 @@ void CldHandler(void *msg)
   ifn = (CldInfoFn)CmiHandlerToFunction(CmiGetInfo(msg));
   ifn(msg, &pfn, &len, &queueing, &priobits, &prioptr);
   CsdEnqueueGeneral(msg, queueing, priobits, prioptr);
-}
+\}
 
 void CldEnqueue(int pe, void *msg, int infofn)
-{
+\{
   int len, queueing, priobits; unsigned int *prioptr;
   CldInfoFn ifn = (CldInfoFn)CmiHandlerToFunction(infofn);
   CldPackFn pfn;
 
-  if (pe == CLD_ANYWHERE) {
+  if (pe == CLD_ANYWHERE) \{
     /* do what you want with the message; in this case we'll just keep
        it local */
     ifn(msg, &pfn, &len, &queueing, &priobits, &prioptr);
     CmiSetInfo(msg,infofn);
     CsdEnqueueGeneral(msg, queueing, priobits, prioptr);
-  }
-  else {
+  \}
+  else \{
     /* pe contains a particular destination or broadcast */
     ifn(msg, &pfn, &len, &queueing, &priobits, &prioptr);
-    if (pfn) {
+    if (pfn) \{
       pfn(&msg);
       ifn(msg, &pfn, &len, &queueing, &priobits, &prioptr);
-    }
+    \}
     CldSwitchHandler(msg, CpvAccess(CldHandlerIndex));
     CmiSetInfo(msg,infofn);
     if (pe==CLD_BROADCAST) 
@@ -299,16 +299,16 @@ void CldEnqueue(int pe, void *msg, int infofn)
     else if (pe==CLD_BROADCAST_ALL)
       CmiSyncBroadcastAllAndFree(len, msg);
     else CmiSyncSendAndFree(pe, len, msg);
-  }
-}
+  \}
+\}
 
 void CldModuleInit()
-{
+\{
   CpvInitialize(int, CldHandlerIndex);
   CpvAccess(CldHandlerIndex) = CmiRegisterHandler(CldHandler);
   CldModuleGeneralInit();
-}
-\end{verbatim}
+\}
+\end{alltt}
 
 The primary function a load balancer must provide is the {\bf
 CldEnqueue} function, which has the following prototype:
@@ -342,9 +342,9 @@ user-provided function that allows CldEnqueue to extract information about
 Thus, an implementation of the {\bf CldEnqueue} function might have
 the following structure:
 
-\begin{verbatim}
+\begin{alltt}
 void CldEnqueue(int pe, void *msg, int infofn)
-{
+\{
   ...
   if (pe == CLD_ANYWHERE)
     /* These messages can be load balanced */
@@ -356,48 +356,51 @@ void CldEnqueue(int pe, void *msg, int infofn)
     /* Broadcast to all plus self */
   else /* Specific processor number was specified */
     /* Send to specific processor */
-}
-\end{verbatim}
+\}
+\end{alltt}
 
 In order to fill in the code above, we need to know more about the
 message before we can send it off to a scheduler's queue, either
 locally or remotely.  For this, we have the info function.  The
 prototype of an info function must be as follows:
 
-\noindent{\tt void ifn(void *msg, CldPackFn *pfn, int *len, int
-*queueing, int *priobits, unsigned int **prioptr);}
+\function{void ifn(msg, pfn, len, queueing, priobits, prioptr);}
+\args{void *msg;}
+\args{CldPackFn *pfn;}
+\args{int *len, *queueing, *priobits;}
+\args{unsigned int **prioptr;}
 
 Thus, to use the info function, we need to get the actual function via
 the handler index provided to {\bf CldEnqueue}.  Typically, {\bf
 CldEnqueue} would contain the following declarations:
 
-\begin{verbatim}
+\begin{alltt}
   int len, queueing, priobits; 
   unsigned int *prioptr;
   CldPackFn pfn;
   CldInfoFn ifn = (CldInfoFn)CmiHandlerToFunction(infofn);
-\end{verbatim}
+\end{alltt}
 
 \noindent Subsequently, a call to {\tt ifn} would look like this:
 
-\begin{verbatim}
+\begin{alltt}
   ifn(msg, &pfn, &len, &queueing, &priobits, &prioptr);
-\end{verbatim}
+\end{alltt}
 
 The info function extracts information from the message about its size,
 queuing strategy and priority, and also a pack function, which will be
 used when we need to send the message elsewhere.  For now, consider
 the case where the message is to be locally enqueued:
 
-\begin{verbatim}
+\begin{alltt}
   ...
   else if (pe == CmiMyPe())
-    {
+    \{
       ifn(msg, &pfn, &len, &queueing, &priobits, &prioptr);
       CsdEnqueueGeneral(msg, queueing, priobits, prioptr);
-    }
+    \}
   ...
-\end{verbatim}
+\end{alltt}
 
 Thus, we see the info function is used to extract info from the
 message that is necessary to pass on to {\bf CsdEnqueueGeneral}.
@@ -408,19 +411,19 @@ that it has room for extra handler information and a reference to the
 info function.  Therefore, before we handle the last three cases of
 {\bf CldEnqueue}, we have a little extra work to do:
 
-\begin{verbatim}
+\begin{alltt}
   ...
   else
-    {
+    \{
       ifn(msg, &pfn, &len, &queueing, &priobits, &prioptr);
-      if (pfn) {
+      if (pfn) \{
         pfn(&msg);
         ifn(msg, &pfn, &len, &queueing, &priobits, &prioptr);
-      }
+      \}
       CldSwitchHandler(msg, CpvAccess(CldHandlerIndex));
       CmiSetInfo(msg,infofn);
       ...
-\end{verbatim}
+\end{alltt}
 
 Calling the info function once gets the pack function we need, if
 there is one.  We then call the pack function which rearranges the
@@ -435,25 +438,25 @@ values may have changed in the packing process.
 
 Finally, we handle our last few cases:
 
-\begin{verbatim}
+\begin{alltt}
   ...
       if (pe==CLD_BROADCAST) 
         CmiSyncBroadcastAndFree(len, msg);
       else if (pe==CLD_BROADCAST_ALL)
         CmiSyncBroadcastAllAndFree(len, msg);
       else CmiSyncSendAndFree(pe, len, msg);
-    }
-}
-\end{verbatim}
+    \}
+\}
+\end{alltt}
 
 The above example also provides {\bf CldHandler} which is used to
 receive messages that {\bf CldEnqueue} forwards to other processors.
 
-\begin{verbatim}
+\begin{alltt}
 CpvDeclare(int, CldHandlerIndex);
 
 void CldHandler(void *msg)
-{
+\{
   CldInfoFn ifn; CldPackFn pfn;
   int len, queueing, priobits; unsigned int *prioptr;
   
@@ -462,39 +465,39 @@ void CldHandler(void *msg)
   ifn = (CldInfoFn)CmiHandlerToFunction(CmiGetInfo(msg));
   ifn(msg, &pfn, &len, &queueing, &priobits, &prioptr);
   CsdEnqueueGeneral(msg, queueing, priobits, prioptr);
-}
-\end{verbatim}
+\}
+\end{alltt}
 
 Note that the {\bf CldHandler} properly restores the message's original
 handler using {\bf CldRestoreHandler}, and calls the info function to obtain
 the proper parameters to pass on to the scheduler.  We talk about this
 more below. 
 
-Finally, Converse initialization functions call {\bf CldModuleInit} to
+Finally, \converse{} initialization functions call {\bf CldModuleInit} to
 initialize the load balancer module.
 
-\begin{verbatim}
+\begin{alltt}
 void CldModuleInit()
-{
+\{
   CpvInitialize(int, CldHandlerIndex);
   CpvAccess(CldHandlerIndex) = CmiRegisterHandler(CldHandler);
   CldModuleGeneralInit();
 
   /* call other init processes here */
   CldBalance();
-}
-\end{verbatim}
+\}
+\end{alltt}
 
 
 \subsection{Provided Load Balancing Facilities}
 
-Converse provides a number of structures and functions to aid in load
+\converse{} provides a number of structures and functions to aid in load
 balancing (see cldb.c).  Foremost amongst these is a method for
 queuing tokens of messages in a processor's scheduler in a way that
 they can be removed and relocated to a different processor at any
 time. The interface for this module is as follows:
 
-\begin{verbatim}
+\begin{alltt}
 void CldSwitchHandler(char *cmsg, int handler)
 void CldRestoreHandler(char *cmsg)
 int CldCountTokens()
@@ -502,7 +505,7 @@ int CldLoad()
 void CldPutToken(char *msg)
 void CldGetToken(char **msg)
 void CldModuleGeneralInit()
-\end{verbatim}
+\end{alltt}
 
 Messages normally have a handler index associated with them, but in addition
 they have extra space for an additional handler.  This is used by the
@@ -528,11 +531,11 @@ CldModuleInit} function.
 
 The helper module also provides the following functions:
 
-\begin{verbatim}
+\begin{alltt}
 void CldMultipleSend(int pe, int numToSend)
 int CldRegisterInfoFn(CldInfoFn fn)
 int CldRegisterPackFn(CldPackFn fn)
-\end{verbatim}
+\end{alltt}
 
 {\bf CldMultipleSend} is generally useful for any load balancer that
 sends multiple messages to one processor.  It works with the token
@@ -547,11 +550,11 @@ You may want to use the three status variables.  These can be used to
 keep track of what your LB is doing (see usage in cldb.graph.c and
 itc++queens program).
 
-\begin{verbatim}
+\begin{alltt}
 CpvDeclare(int, CldRelocatedMessages);
 CpvDeclare(int, CldLoadBalanceMessages);
 CpvDeclare(int, CldMessageChunks);
-\end{verbatim}
+\end{alltt}
 
 The two register functions register {\sl info} and {\sl pack}
 functions, returning an index for the functions.  Info functions are
@@ -560,7 +563,7 @@ message.  Amongst these components is the pack function index.  If
 necessary, the pack function can be used to pack a message that is
 about to be relocated to another processor.  Information on how
 to write info and pack functions is available in the load balancing
-section of the Converse Extensions manual. 
+section of the \converse{} Extensions manual. 
 
 \subsection{Finishing the {\tt Test} Balancer}
 
@@ -573,7 +576,7 @@ important!
 The {\tt test} load balancer is available in
 charm/src/Common/conv-ldb/cldb.test.c.  To try out your own load
 balancer you can use this filename and SUPER\_INSTALL will compile it
-and you can link it into your Charm++ programs with -balance test.
+and you can link it into your \charmpp{} programs with -balance test.
 (To add your own new balancers permanently and give them another name
 other than "test" you will need to change the Makefile used by
 SUPER\_INSTALL. Don't worry about this for now.)  The cldb.test.c
@@ -590,16 +593,16 @@ scheduler, we make use of the token queue.  This means that messages
 can later be removed for relocation.  {\bf CldPutToken} adds the
 message to the token queue on the local processor.
 
-\begin{verbatim}
+\begin{alltt}
 #include <stdio.h>
 #include "converse.h"
 #define PERIOD 100
 #define MAXMSGBFRSIZE 100000
 
 char *CldGetStrategy(void)
-{
+\{
   return "test";
-}
+\}
 
 CpvDeclare(int, CldHandlerIndex);
 CpvDeclare(int, CldBalanceHandlerIndex);
@@ -685,7 +688,7 @@ void CldModuleInit()
   if (CmiNumPes() > 1)
     CldDistributeTokens();
 }
-\end{verbatim}
+\end{alltt}
 
 Now look two functions up from {\bf CldEnqueue}.  We have an additional
 handler besides the {\bf CldHandler}: the {\bf CldBalanceHandler}.  The
@@ -699,7 +702,7 @@ places messages irretrievably in the scheduler queue.
 
 Next we look at our initialization functions to see how the process
 gets started.  The {\bf CldModuleInit} function gets called by the
-common Converse initialization code and starts off the periodic load
+common \converse{} initialization code and starts off the periodic load
 distribution process by making a call to {\bf
 CldDistributeTokens}. The entirety of the balancing is handled by the
 periodic invocation of this function.  It computes an
index 72cdb4632d4a5f629f4916f5e37fa6a66a68b4eb..5eb5f27a0ef7bb2f448736b2d824ee309c3601d0 100644 (file)
@@ -1,6 +1,6 @@
 \chapter{Parallel Arrays of Threads}
 
-This module is CPath: Converse Parallel Array of Threads.  It makes it
+This module is CPath: \converse{} Parallel Array of Threads.  It makes it
 simple to create arrays of threads, where the threads are distributed
 across the processors.  It provides simple operations like sending a
 message to a thread, as well as group operations like multicasting to
@@ -77,14 +77,14 @@ described by a context-free grammar:
 \function{void CPathSend(dest-clause, tag-clause, data-clause, end-clause)}
 Where:
 
-\begin{verbatim}
+\begin{alltt}
     dest-clause :== CPATH_DEST ',' pathptr ',' index ',' index ',' ...
     tag-clause  :== CPATH_TAG ',' tag
     tag-clause  :== CPATH_TAGS ',' tag ',' tag ',' ... ',' 0
     tag-clause  :== CPATH_TAGVEC ',' numtags ',' tagvector
     data-clause :== CPATH_BYTES ',' numbytes ',' bufptr
     end-clause  :== CPATH_END
-\end{verbatim}
+\end{alltt}
 
 The symbols {\tt CPATH\_DEST}, {\tt CPATH\_TAG}, {\tt CPATH\_TAGS},
 {\tt CPATH\_TAGVEC}, {\tt CPATH\_BYTES}, {\tt CPATH\_END}, and the
@@ -107,7 +107,7 @@ using CPathMsgDecodeBytes, and finally discarded with CPathMsgFree:
 \function{void *CPathRecv(tag-clause, end-clause)}
 \desc{The tag-clause and end-clause match the grammar for CPathSend.
 The function will wait until a message with the same tags shows up (it
-waits using the thread-blocking primitives, see Converse threads).  If
+waits using the thread-blocking primitives, see \converse{} threads).  If
 any position in the CPathRecv tag-vector is {\tt CPATH\_WILD}, then
 that one position is ignored.  CPathRecv returns an ``opaque CPath
 message''.  The message contains the data somewhere inside it.  The
@@ -134,7 +134,7 @@ CPathReduce are most easily described by a context-free grammar:
 \function{void CPathReduce(over-clause, tag-clause, red-clause, data-clause, dest-clause, end-clause)}
 Where:
 
-\begin{verbatim}
+\begin{alltt}
     over-clause :== CPATH_OVER ',' pathptr ',' index ',' index ',' ...
     dest-clause :== CPATH_DEST ',' pathptr ',' index ',' index ',' ...
     tag-clause  :== CPATH_TAG ',' tag
@@ -143,7 +143,7 @@ Where:
     data-clause :== CPATH_BYTES ',' vecsize ',' eltsize ',' data
     red-clause  :== CPATH_REDUCER ',' redfn
     end-clause  :== CPATH_END
-\end{verbatim}
+\end{alltt}
 
 The over-clause specifies the set of threads participating in the
 reduction.  One or more of the indices should be {\tt CPATH\_ALL}, the
index 27a329bcabcbaff2bff36415ef83339058d893e9..698604b5e8301e7a97644b9d065c4e6ab05dedf8 100644 (file)
@@ -24,22 +24,22 @@ function is called.
 For example, if the CPM scanner sees the following function
 declaration
 
-\begin{verbatim}
-    CpmInvokable myfunc(int x, int y) { ... }
-\end{verbatim}
+\begin{alltt}
+    CpmInvokable myfunc(int x, int y) \{ ... \}
+\end{alltt}
 
 The scanner will generate a launcher named {\tt Cpm\_myfunc}.
 The launcher has this prototype:
 
-\begin{verbatim}
+\begin{alltt}
     void Cpm_myfunc(CpmDestination destination, int x, int y);
-\end{verbatim}
+\end{alltt}
 
 If one were to call {\tt Cpm\_myfunc} as follows:
 
-\begin{verbatim}
+\begin{alltt}
     Cpm_myfunc(CpmSend(3), 8, 9);
-\end{verbatim}
+\end{alltt}
 
 a message would be sent to processor 3 ordering it to call {\tt
 myfunc(8,9)}.  Notice that the {\it destination} argument isn't just an
@@ -71,29 +71,29 @@ mechanisms.
 We demonstrate the use of the CPM mechanisms using the following
 short program {\tt myprog.c}:
 
-\begin{verbatim}
+\begin{alltt}
  1:    #include "myprog.cpm.h"
  2:   
  3:    CpmInvokable print_integer(int n)
- 4:    {
- 5:      CmiPrintf("%d\n", n);
- 6:    }
+ 4:    \{
+ 5:      CmiPrintf("%d\verb+\+n", n);
+ 6:    \}
  7:    
  8:    user_main(int argc, char **argv)
- 9:    {
+ 9:    \{
 10:      int i;
 11:      CpmModuleInit();
 12:      CpmInitializeThisModule();
 13:      if (CmiMyPe()==0)
 14:        for (i=1; i<CmiNumPes(); i++)
 15:          Cpm_print_integer(CpmSend(i), rand());
-16:    }
+16:    \}
 17:    
 18:    main(int argc, char **argv)
-19:    {
+19:    \{
 20:      ConverseInit(argc, argv, user_main, 0, 0);
-21:    }
-\end{verbatim}
+21:    \}
+\end{alltt}
 
 Lines 3-6 of this program contain a simple C function that prints an
 integer.  The function is marked with the word {\tt CpmInvokable}.
@@ -167,9 +167,9 @@ Instead of supplying a processor number, one can also supply the
 special symbols CPM\_ALL or CPM\_OTHERS, causing a broadcast.  For
 example,
 
-\begin{verbatim}
+\begin{alltt}
 Cpm_print_integer(CpmMakeThread(CPM_ALL), 5);
-\end{verbatim}
+\end{alltt}
 
 would broadcast a message to all the processors causing each processor
 to create a thread, which would in turn invoke {\tt print\_integer}
@@ -182,10 +182,10 @@ argument lists.  In particular, the argument list of a CpmInvokable
 function can only contain cpm-single-arguments and cpm-array-arguments,
 as defined by this grammar:
 
-\begin{verbatim}
+\begin{alltt}
     cpm-single-argument :== typeword varname
     cpm-array-argument  :== typeword '*' varname
-\end{verbatim}
+\end{alltt}
 
 When CPM sees the cpm-array-argument notation, CPM interprets it as
 being a pointer to an array.  In this case, CPM attempts to pack an
@@ -202,37 +202,37 @@ array values as automatically as it handles single values.
 
 A second program, {\tt example2.c}, uses array arguments:
 
-\begin{verbatim}
+\begin{alltt}
  1:    #include "example2.cpm.h"
  2:   
  3:    CpmInvokable print_program_arguments(CpmDim argc, CpmStr *argv)
- 4:    {
+ 4:    \{
  5:      int i;
  6:      CmiPrintf("The program's arguments are: ");
  7:      for (i=0; i<argc; i++) CmiPrintf("%s ", argv[i]);
- 8:      CmiPrintf("\n");
- 9:    }
+ 8:      CmiPrintf("\verb+\+n");
+ 9:    \}
 10:
 11:    user_main(int argc, char **argv)
-12:    {
+12:    \{
 13:      CpmModuleInit();
 14:      CpmInitializeThisModule();
 15:      if (CmiMyPe()==0)
 16:        Cpm_print_program_arguments(CpmSend(1), argc, argv);
-17:    }
+17:    \}
 18:
 19:    main(int argc, char **argv)
-20:    {
+20:    \{
 21:      ConverseInit(argc, argv, user_main, 0, 0);
-22:    }
-\end{verbatim}
+22:    \}
+\end{alltt}
 
 The word {\tt CpmStr} is a CPM built-in type, it represents a
 null-terminated string:
 
-\begin{verbatim}
+\begin{alltt}
        typedef char *CpmStr;
-\end{verbatim}
+\end{alltt}
 
 Therefore, the function {\tt print\_program\_arguments} takes exactly
 the same arguments as {\tt user\_main}.  In this example, the main
@@ -254,10 +254,10 @@ handle such types.
 
 CPM knows which type is which only through the following declarations:
 
-\begin{verbatim}
+\begin{alltt}
     CpmDeclareSimple(typeword);
     CpmDeclarePointer(typeword);
-\end{verbatim}
+\end{alltt}
 
 The user must supply such declarations for each type that must be sent
 via CPM.
@@ -289,22 +289,22 @@ routines.
 The following program fragment shows the declaration of two
 user-defined types:
 
-\begin{verbatim}
+\begin{alltt}
  1:
- 2:    typedef struct { double x,y; } coordinate;    
+ 2:    typedef struct \{ double x,y; \} coordinate;    
  3:    CpmDeclareSimple(coordinate);
  4:    
  5:    void CpmPack_coordinate(coordinate *p)
- 6:    {
+ 6:    \{
  7:      CpmPack_double(&(p->x));
  8:      CpmPack_double(&(p->y));
- 9:    }
+ 9:    \}
 10:
 11:    void CpmPack_coordinate(coordinate *p)
-12:    {
+12:    \{
 13:      CpmUnpack_double(&(p->x));
 14:      CpmUnpack_double(&(p->y));
-15:    }
+15:    \}
 16:
 17:    typedef int *intptr;
 18:    CpmDeclarePointer(intptr);
@@ -312,22 +312,22 @@ user-defined types:
 20:    #define CpmPtrSize_intptr(p) sizeof(int)
 21:    
 22:    void CpmPtrPack_intptr(void *p, intptr v)
-23:    {
+23:    \{
 24:      *(int *)p = *v;
 25:      CpmPack_int((int *)p);
-26:    }
+26:    \}
 27:
 28:    intptr CpmPtrUnpack_intptr(void *p)
-29:    {
+29:    \{
 30:      CpmUnpack_int((int *)p);
 31:      return (int *)p;
-32:    }
+32:    \}
 33:
 34:    #define CpmPtrFree_intptr(p) (0)
 35:
 36:    #include "example3.cpm.h"
 37:    ...
-\end{verbatim}
+\end{alltt}
 
 The first type declared in this file is the coordinate.  Line 2
 contains the C type declaration, and line 3 notifies CPM that it is a
@@ -385,7 +385,7 @@ launcher, there is a matching function called an {\it invoker}.  The
 launcher's job is to put the argument data in the message and send the
 message.  The {\it invoker}'s job is to extract the argument data from
 the message and call the user's function.  The launcher uses {\tt
-CmiSetHandler} to tell Converse to handle the message by calling the
+CmiSetHandler} to tell \converse{} to handle the message by calling the
 appropriate {\it invoker}.}
 
 \item[]{{\bf 5. The message is sent, received, and handled}. 
@@ -416,9 +416,9 @@ We now show an example CPM command, and describe the steps that are
 taken when the command is executed.  The command we will consider is
 this one:
 
-\begin{verbatim}
+\begin{alltt}
 Cpm_print_integer(CpmEnqueueFIFO(3), 12);
-\end{verbatim}
+\end{alltt}
 
 Which sends a message to processor 3, ordering it to call {\tt
 print\_integer(12)}.
@@ -428,24 +428,24 @@ CpmDestination.  The following is the code for CpmEnqueueFIFO:
 
 \pagebreak
 
-\begin{verbatim}
+\begin{alltt}
 typedef struct CpmDestinationSend
-{
+\{
   void *(*sendfn)();
   int envsize;
   int pe;
-}
+\}
 *CpmDestinationSend;
 
 CpmDestination CpmEnqueueFIFO(int pe)
-{
+\{
   static struct CpmDestinationSend ctrl;
   ctrl.envsize = sizeof(int);
   ctrl.sendfn  = CpmEnqueueFIFO1;
   ctrl.pe = pe;
   return (CpmDestination)&ctrl;
-}
-\end{verbatim}
+\}
+\end{alltt}
 
 Notice that the CpmDestination structure varies, depending upon which
 kind of destination is being used.  In this case, the destination
@@ -476,15 +476,15 @@ print\_integer.}
 
 The code for the send-function is here:
 
-\begin{verbatim}
+\begin{alltt}
 void *CpmEnqueueFIFO1(CpmDestinationSend dest, int len, void *msg)
-{
+\{
   int *env = (int *)CpmEnv(msg);
   env[0] = CmiGetHandler(msg);
   CmiSetHandler(msg, CpvAccess(CpmEnqueueFIFO2_Index));
   CmiSyncSendAndFree(dest->pe,len,msg);
-}
-\end{verbatim}
+\}
+\end{alltt}
 
 The send-function CpmEnqueueFIFO1 starts by switching the handler.
 The original handler is removed using using {\tt CmiGetHandler}.  It
@@ -504,18 +504,18 @@ its handler will be called.  The result will be that {\tt
 CpmEnqueueFIFO2} will be called on the destination processor.  Here is
 the code for {\tt CpmEnqueueFIFO2}:
 
-\begin{verbatim}
+\begin{alltt}
 void CpmEnqueueFIFO2(void *msg)
-{
+\{
   int *env;
   CmiGrabBuffer(&msg);
   env = (int *)CpmEnv(msg);
   CmiSetHandler(msg, env[0]);
   CsdEnqueueFIFO(msg);
-}
-\end{verbatim}
+\}
+\end{alltt}
 
-This function takes ownership of the message-buffer from Converse
+This function takes ownership of the message-buffer from \converse{}
 using {\tt CmiGrabBuffer}.  It extracts the original handler from the
 envelope (the handler that calls {\tt print\_integer}), and restores it
 using {\tt CmiSetHandler}.  Having done so, it enqueues the message
@@ -525,7 +525,7 @@ message from the queue, and {\tt print\_integer} is invoked.
 In summary, the procedure for implementing new kinds of destinations
 is to write one send-function, one function returning a CpmDestination
 (which contains a reference to the send-function), and one or more
-Converse handlers to manipulate the message.
+\converse{} handlers to manipulate the message.
 
 The destination-function must return a pointer to a
 ``destination-structure'', which can in fact be any structure matching
@@ -540,15 +540,15 @@ This pointer must be coerced to type CpmDestination.
 
 The send-function must have the following prototype:
 
-\begin{verbatim}
+\begin{alltt}
     void sendfunction(CpmDestination dest, int msglen, void *msgptr)
-\end{verbatim}
+\end{alltt}
 
 It can access the envelope of the message using CpmEnv:
 
-\begin{verbatim}
+\begin{alltt}
     int *CpmEnv(void *msg);
-\end{verbatim}
+\end{alltt}
 
 It can also access the data stored in the destination-structure
 by the destination-function.
index c737583b79d533b360ef1d69d6aff9074db396b1..09ed2cdcd7b82cd0cb018195bfd5b20741c6e538 100644 (file)
@@ -55,5 +55,5 @@ CfutureCreateValue.
 
 This function initializes the futures module.  It must be called once
 on each processor, during the handler-registration process (see the
-Converse manual regarding CmiRegisterHandler).
+\converse{} manual regarding CmiRegisterHandler).
 
index c49d5e588e2d9430cff9a9504571781ed1d6a2a9..1817ddb0cb28f60622a76ccb0fad28b8cb7e72b4 100644 (file)
@@ -1,13 +1,13 @@
 \chapter{Load Balancing}
 
-Converse provides the programmer with a number of Load Balancing
+\converse{} provides the programmer with a number of Load Balancing
 strategies in order to distribute work among the processors in the
 system. The load balancing strategy to be used in the program can be
 specified at the link time. \note{In future versions, we will
 provide users with the ability to write their own load balancing
 strategies. However, in this version, the choice is limited to certain
 predefined load balancing strategies.} The following functions are provided
-for interfacing a Converse program with the load balancing module.
+for interfacing a \converse{} program with the load balancing module.
 
 \function{void CldNewSeedFromLocal(void *msg, void *ldb, void (*sendfn)(),int queueing, int priolen, int *prioptr)}
 \index{CldNewSeedFromLocal}
@@ -42,11 +42,11 @@ different use of the parameter \param{ldb}. Some of the currently
 implemented language specific load balancing strategies use this area
 in the message for sending the load information on local processor
 piggy-backed onto the message periodically; some of them may not need
-this area at all. \note{The only ldb strategy available to Converse
+this area at all. \note{The only ldb strategy available to \converse{}
 users currently, i.e. random, does not use this area and the user could
 specify \param{void * (0))} there.}
 
-Some of the parallel languages or libraries built on top of Converse
+Some of the parallel languages or libraries built on top of \converse{}
 may have the message packing mechanisms which have to be called before
 any message crosses address boundaries. Therefore the load balancing
 module cannot use built-in functions such as \param{CmiAsyncSend()}
index 77ce8d6a64d8fb0ec3463092370103815a9a3438..a18af18168546dd609e8db096e26a5cd3736ee5d 100644 (file)
@@ -1,92 +1,27 @@
-\documentclass[11pt]{report}
+\documentclass[10pt]{report}
+\usepackage{pplmanual}
+\input{../pplmanual}
 
-\newif\ifpdf
-\ifx\pdfoutput\undefined
-  \pdffalse
-\else
-  \pdfoutput=1
-  \pdftrue
-\fi
-
-\ifpdf
-  \pdfcompresslevel=9
-  \usepackage[pdftex,colorlinks=true,plainpages=false]{hyperref}
-\else
-\fi
-
-\setcounter{topnumber}{2}
-\def\topfraction{1}
-\setcounter{bottomnumber}{1}
-\def\bottomfraction{1}
-\setcounter{totalnumber}{3}
-\def\textfraction{0.2}
-\def\floatpagefraction{0.8}
-\setlength{\parindent}{0.0in}
-\setlength{\parskip}{0.1in}
-\setlength{\textwidth}{6.5in}
-\setlength{\itemindent}{1in}
-\setlength{\textheight}{9.5in}
-\addtolength{\oddsidemargin}{0in}
-\addtolength{\topmargin}{-0.4in}
-\parskip 0.05in
-\newcommand{\internal}[1]{}
-\newcommand{\function}[1]{{\noindent{\bf {#1}}\\}}
-\newcommand{\param}[1]{{\tt {#1}}}
-\newcommand{\note}[1]{\noindent{(Note: {\em {#1}})}}
-\newcommand{\desc}[1]{{#1}}
-
-\newcommand{\basea}{\renewcommand{\baselinestretch}{1.0}}
-\newcommand{\baseb}{\renewcommand{\baselinestretch}{1.8}}
-\newcommand{\mycomment}[1]{} 
-\basea
-\textwidth 6.4in
-\textheight 8.9in
-\topmargin -.4in
-\oddsidemargin 0.25in
-\evensidemargin 0.25in
-\parskip 0.1in
-
-\makeindex
-
-\begin{document}
-
-\begin{titlepage}
-\vspace*{2in}
-\Huge
-\begin{center}
-Converse\\
-Extensions\\
-Library\\
-\vspace*{0.7in}
-\today
-\end{center}
-\normalsize
-
-\vspace*{2.5in}
-\Large
-
-Converse Parallel Programming Environment was developed as a group
+\title{\converse{} Extenstions\\Library Manual}
+\credits{
+\converse{} Parallel Programming Environment was developed as a group
 effort at Parallel Programming Laboratory, University of Illinois at
 Urbana-Champaign.  The team consisted of Attila Gursoy, Sanjeev
 Krishnan, Joshua Yelon, Milind Bhandarkar, Narain Jagathesan, Robert
 Brunner and Laxmikant Kale.
+}
+\version{5.5}
 
-\normalsize
-\end{titlepage}
-
-\tableofcontents
+\begin{document}
+\maketitle
 
 \chapter{Introduction}
 
-The Converse Extensions Library is a collection of modules that have
-been implemented on top of the Converse API.  Each of these modules was
-deemed potentially useful to other Converse users, thus, we distribute
-these modules along with Converse as a convenience.  {\em You don't
-need to read any part of this manual to use Converse.}
+The \converse{} Extensions Library is a collection of modules that have
+been implemented on top of the \converse{} API.  Each of these modules was
+deemed potentially useful to other \converse{} users, thus, we distribute
+these modules along with \converse{} as a convenience.  {\em You don't
+need to read any part of this manual to use \converse{}.}
 
 \input{msgmgr}
 \input{random}
index d48dd64ffd6b0ad400f3ca5c3efcc5faafee40af..be2fc9659f73282112a302108e9da3336073889c 100644 (file)
@@ -13,12 +13,12 @@ both storage and retrieval.
 
 
 To use the message manager, you must include {\tt converse.h} and
-link with the converse library.
+link with the \converse{} library.
 
 In actuality, the term ``message manager'' is unnecessarily specific.
 The message manager can store and retrieve arbitrary pointers
 according to a set of tags.  The pointers do {\em not} necessarily
-need to be pointers to converse messages.  They can be pointers to
+need to be pointers to \converse{} messages.  They can be pointers to
 anything.
 
 \function{typedef struct CmmTableStruct *CmmTable}
index 0539cdb0360f6faef4b6dd2a17565b5e59c29354..53d5c578fc57d03578462d6179fe9961584b82d5 100644 (file)
@@ -1,40 +1,40 @@
-\chapter{Converse-POSIX threads}
+\chapter{\converse{}-POSIX threads}
 
-We have implemented the POSIX threads API on top of Converse threads.
-To use the Converse-pthreads, you must include the header file:
+We have implemented the POSIX threads API on top of \converse{} threads.
+To use the \converse{}-pthreads, you must include the header file:
 
 \verb/#include <cpthreads.h>/
 
 Refer to the POSIX threads documentation for the documentation on the
-pthreads functions and types.  Although Converse-pthreads threads are
+pthreads functions and types.  Although \converse{}-pthreads threads are
 POSIX-compliant in most ways, there are some specific things one needs
 to know to use our implementation.
 
-\section{Pthreads and Converse}
+\section{Pthreads and \converse{}}
 
-Our pthreads implementation is designed to exist within a Converse
+Our pthreads implementation is designed to exist within a \converse{}
 environment.  For example, to send messages inside a POSIX program,
-you would still use the usual Converse messaging primitives.
+you would still use the usual \converse{} messaging primitives.
 
 \section{Suppressing Name Conflicts}
 
-Some people may wish to use Converse pthreads on machines that already
+Some people may wish to use \converse{} pthreads on machines that already
 have a pthreads implementation in the standard library.  This may
 cause some name-conflicts as we define the pthreads functions, and the
 system include files do too.  To avoid such conflicts, we provide an
 alternative set of names beginning with the word Cpthread.  These
 names are interchangable with their pthread equivalents.  In addition,
-you may prevent Converse from defining the pthread names at all with
+you may prevent \converse{} from defining the pthread names at all with
 the preprocessor symbol SUPPRESS\_PTHREADS:
 
-\begin{verbatim}
+\begin{alltt}
 #define SUPPRESS_PTHREADS
 #include <cpthreads.h>
-\end{verbatim}
+\end{alltt}
 
 \section{Interoperating with Other Thread Packages}
 
-Converse programs are typically multilingual programs.  There may be
+\converse{} programs are typically multilingual programs.  There may be
 modules written using POSIX threads, but other modules may use other
 thread APIs.  The POSIX threads implementation has the following
 restriction: you may only call the pthreads functions from inside
@@ -60,33 +60,33 @@ explicit insertion of yields.
 
 \section{Limits on Blocking Operations in main}
 
-Converse has a rule about blocking operations --- there are certain
+\converse{} has a rule about blocking operations --- there are certain
 pieces of code that may not block.  This was an efficiency decision.
-In particular, the main function, Converse handlers, and the converse
+In particular, the main function, \converse{} handlers, and the \converse{}
 startup function (see ConverseInit) may not block.  You must be aware
-of this when using the POSIX threads functions with Converse.
+of this when using the POSIX threads functions with \converse{}.
 
 There is a contradition here --- the POSIX standard requires that the
 pthreads functions work from inside {\tt main}.  However, many of them
-block, and Converse forbids blocking inside {\tt main}.  This
+block, and \converse{} forbids blocking inside {\tt main}.  This
 contradition can be resolved by renaming your posix-compliant {\tt
 main} to something else: for example, {\tt mymain}.  Then, through the
-normal Converse startup procedure, create a POSIX thread to run {\tt
+normal \converse{} startup procedure, create a POSIX thread to run {\tt
 mymain}.  We provide a convenience function to do this, called
 Cpthreads\_start\_main.  The startup code will be much like this:
 
-\begin{verbatim}
+\begin{alltt}
 void mystartup(int argc, char **argv)
-{
+\{
   CpthreadModuleInit();
   Cpthreads_start_main(mymain, argc, argv);
-}
+\}
 
 int main(int argc, char **argv)
-{
+\{
   ConverseInit(mystartup, argc, argv, 0, 0);
-}
-\end{verbatim}
+\}
+\end{alltt}
 
 This creates the first POSIX thread on each processor, which runs the
 function mymain.  The mymain function is executing in a POSIX thread,
index c4836a1b0760f2961b8664d6aef31c3c3fad6f2d..17ef0ea175d230792c3c1d8e5d42ca1a12898309 100644 (file)
@@ -1,6 +1,6 @@
-\chapter{Converse Pseudorandom Number Generator}
+\chapter{\converse{} Pseudorandom Number Generator}
 
-Converse provides three different Linear Congruential Random Number Generators.
+\converse{} provides three different Linear Congruential Random Number Generators.
 Each random number stream has a cycle length of $2^{64}$ as opposed to
 ANSI C standard's $2^{48}$.
 Also, each of the three random number streams can be split into a number of
@@ -10,16 +10,16 @@ section in the random number generator,and yet, this functionality is
 thread-safe, because all the state information is stored in the structure
 allocated by the programmer. Further, this state information is stored in a
 first class object, and can be passed to other processors through messages.
-This module of Converse is based on the public-domain 
+This module of \converse{} is based on the public-domain 
 SPRNG\footnote{URL:{\tt http://www.ncsa.uiuc.edu/Apps/SPRNG/www/}} 
 package developed
 by Ashok Srinivasan\footnote{Email:{\tt ashoks@ncsa.uiuc.edu}} at NCSA.
 
 For minimal change to programs already using C functions {\tt rand()},
-{\tt srand()}, and {\tt drand48()}, Converse also maintains a ``default''
+{\tt srand()}, and {\tt drand48()}, \converse{} also maintains a ``default''
 random number stream.
 
-Interface to the Converse Pseudorandom Number Generator module is as follows:
+Interface to the \converse{} Pseudorandom Number Generator module is as follows:
 
 \function{typedef ... CrnStream;}
 \index{CrnStream}