*** empty log message ***
authorJosh Yelon <jyelon@uiuc.edu>
Sat, 26 Jul 1997 17:26:52 +0000 (17:26 +0000)
committerJosh Yelon <jyelon@uiuc.edu>
Sat, 26 Jul 1997 17:26:52 +0000 (17:26 +0000)
doc/converse/cmi.tex
doc/converse/scheduler.tex [deleted file]
doc/converse/threads.tex
doc/converse/usermain.tex
doc/convext/pthreads.tex

index 228d7b1d0043f19014ca213f54608b45b692c030..aeb24b7b096510f6599ee10645f5d78dbc27308c 100644 (file)
@@ -5,6 +5,7 @@ CSD.  Together, they serve to transmit messages and schedule the
 delivery of messages.
 
 \section{Defining Handler Numbers}
+\label{handler1}
 
 When a message arrives at a processor, it triggers the execution of a
 {\em handler function}, not unlike a UNIX signal handler.  The handler
@@ -77,6 +78,7 @@ in a program.  The system guarantees that no numbering conflicts will
 occur as a result of this combination.
 
 \section{Writing Handler Functions}
+\label{handler2}
 
 A message handler function is just a C function that accepts a void
 pointer (to a message buffer) as an argument, and returns nothing.  The
@@ -412,6 +414,7 @@ provided here for backward compatibility.}
 is empty, zero otherwise.}
 
 \section{Polling for Messages}
+\label{polling}
 
 As we stated earlier, Converse messages trigger handler functions when
 they arrive.  In fact, for this to work, the processor must
@@ -590,11 +593,11 @@ array should at least be of size \param{CmiNumChildren()}.}
 
 \section{Spanning Tree Calls}
 
-Converse defines a spanning tree organization of the processor procNums along
-with routines for accessing elements of that tree.  The spanning tree
-routines come in handy when writing programs with collective communication
-because message communication patterns can be made to proceed along the
-spanning tree arcs to avoid bottlenecks at a single procNum.
+Sometimes, it is convenient to view the nodes of the machine as a
+tree.  For this purpose, Converse defines a tree over the nodes.  We
+provide functions to obtain the parent and children of each node.  On
+those machines where the communication topology is relevant, we
+arrange the tree to optimize communication performance.
 
 \function{int CmiSpanTreeRoot()}
 \index{CmiSpanTreeRoot}
diff --git a/doc/converse/scheduler.tex b/doc/converse/scheduler.tex
deleted file mode 100644 (file)
index e69de29..0000000
index d9eee4ec8ec3951d9f91dbd8c18d13862b0cf91f..f2d1091c0f7dbf25fed564695d56253cd68ac04a 100644 (file)
@@ -10,10 +10,6 @@ schedulers.
 
 \section{Basic Thread Calls}
 
-In this section, we refer to the ``scheduler queue''.  By this, we mean
-the priority queue described in section \ref{schedqueue}.
-
-
 \function{typedef struct CthThreadStruct *CthThread;}
 \index{CthThread}
 \desc{This is an opaque type defined in {\tt converse.h}.  It represents
@@ -22,12 +18,12 @@ contents of a CthThreadStruct.}
 
 \function{typedef void (CthVoidFn)();}
 \index{CthVoidFn}
-\desc{This is a type defined in {\tt threads.h}.  It represents
+\desc{This is a type defined in {\tt converse.h}.  It represents
 a function that returns nothing.}
 
 \function{typedef CthThread (CthThFn)();}
 \index{CthThFn}
-\desc{This is a type defined in {\tt threads.h}.  It represents
+\desc{This is a type defined in {\tt converse.h}.  It represents
 a function that returns a CthThread.}
 
 \function{CthThread CthSelf()}
@@ -65,9 +61,7 @@ thread suspends.  To terminate itself, a thread calls
 \desc{Causes the current thread to stop executing.
 The suspended thread will not start executing again until somebody
 pushes it into the scheduler queue again, using CthAwaken below.  Control
-transfers to the thread running CsdScheduler.  This has the effect of
-polling for messages, and possibly transferring control to a
-thread in the scheduler queue.}
+transfers to the next task in the scheduler queue.}
 
 \function{void CthAwaken(CthThread t)}
 \index{CthAwaken}
@@ -98,6 +92,39 @@ This field is typically used by the implementors of mutexes, condition
 variables, and other synchronization abstractions to link threads
 together into queues.  This function sets the contents of the next field.}
 
+\section{Thread Scheduling and Blocking Restrictions}
+
+Converse threads use a scheduler queue, like any other threads
+package.  We chose to use the same queue as the one used for Converse
+messages (see section \ref{schedqueue}).  Because of this, thread
+context-switching will not work unless there is a thread polling for
+messages.  A rule of thumb, with Converse, it is best to have a thread
+polling for messages at all times.  In Converse's normal mode (see
+section \ref{initial}), this happens automatically.  However, in
+user-calls-scheduler mode, you must be aware of it.
+
+There is a second caution associated with this design.  There is a
+thread polling for messages (even in normal mode, it's just hidden in
+normal mode).  The continuation of your computation depends on that
+thread --- you must not block it.  In particular, you must not call
+blocking operations in these places:
+
+\begin{itemize}
+
+\item{In the code of a Converse handler (see sections \ref{handler1}
+and \ref{handler2}).}
+
+\item{In the code of the Converse start-function (see section
+\ref{initial}).}
+
+\end{itemize}
+
+These restrictions are usually easy to avoid.  For example, if you
+wanted to use a blocking operation inside a Converse handler, you
+would restructure the code so that the handler just creates a new
+thread and returns.  The newly-created thread would then do the work
+that the handler originally did.
+
 \section{Thread Scheduling Hooks}
 
 Normally, when you CthAwaken a thread, it goes into the primary
index 497c53783aaea96dda9f4c99fb46f781ec58e613..4a480d5cda5ff4b6ce8597baad48e9734ce968b5 100644 (file)
@@ -1,4 +1,5 @@
 \chapter{Initialization and Completion}
+\label{initial}
 
 The program utilizing Converse begins executing at {\tt main}, like
 any other C program.  The initialization process is somewhat
index 8d0adb70f0f33ecc5b07caa7423bfc1949a153dc..0539cdb0360f6faef4b6dd2a17565b5e59c29354 100644 (file)
@@ -51,7 +51,7 @@ give up control at two points:
 
 \begin{itemize}
 \item{If they block (eg, at a mutex).}
-\item{If they call pthread_yield().}
+\item{If they call pthread\_yield().}
 \end{itemize}
 
 Usually, the first rule is sufficient to make most programs work.