Added stuff.
authorJosh Yelon <jyelon@uiuc.edu>
Sat, 26 Jul 1997 16:04:45 +0000 (16:04 +0000)
committerJosh Yelon <jyelon@uiuc.edu>
Sat, 26 Jul 1997 16:04:45 +0000 (16:04 +0000)
doc/convext/Makefile
doc/convext/futures.tex
doc/convext/manual.tex
doc/convext/pthreads.tex [new file with mode: 0644]

index dd3b544fbab24053da5dc99cb4ef0a5c5a800783..c3569e62ad3120c7bc1db13c35909fb2fb437fda 100644 (file)
@@ -8,51 +8,22 @@
 ############################################################################
 # DESCRIPTION:
 #
+# This is a makefile.  It is used when you type ``make''.
+#
 ############################################################################
 # REVISION HISTORY:
 #
 # $Log$
-# Revision 1.1  1997-07-22 19:00:35  jyelon
-# *** empty log message ***
-#
-# Revision 1.9  1996/11/18 16:55:50  milind
-# Made changes to the scheduler section to reflect the semantics of
-# CsdScheduler(0). Also, changed the Makefile to have targets ps, html,
-# install and all.
-#
-# Revision 1.8  1996/06/14 21:38:25  jyelon
-# This thing doesn't work at all.  Restructured.
-#
-# Revision 1.7  1995/11/15 18:01:22  brunner
-# Added cpvmacros.tex to Makefile so make co works.
-#
-# Revision 1.6  1995/11/01  22:04:21  milind
-# Added automatic generation of index.
-#
-# Revision 1.5  1995/10/30  16:06:49  milind
-# Added one more latex stage to remove undefined references.
-#
-# Revision 1.4  1995/10/10  21:40:41  jyelon
-# *** empty log message ***
-#
-# Revision 1.3  1995/09/21  21:42:21  milind
-# Added latex2html
-#
-# Revision 1.2  1995/09/21  15:37:33  milind
-# Added other tex files
-#
-# Revision 1.2  1995/09/21  15:37:33  milind
-# Added other tex files
-#
-# Revision 1.1  1995/09/20  16:34:32  brunner
-# Initial revision
+# Revision 1.2  1997-07-26 16:04:45  jyelon
+# Added stuff.
 #
 #
 ############################################################################
 
 TEXFILES=cmi.tex cpm.tex cpvmacros.tex index.tex ldb.tex manual.tex\
 msgmgr.tex queue.tex scheduler.tex simulator.tex threads.tex\
-thsync.tex
+thsync.tex pthreads.tex
+
 
 ps:
        latex manual.tex
index a65b3b51bd1694072777d387681f46cf3b359176..3cf2cdc89e489fbfa1be5bb7b273fb733ca2ce84 100644 (file)
@@ -1,65 +1,61 @@
 \chapter{Futures}
 
 This library supports the {\em future} abstraction, defined and used by
-Halstead and other researchers. The library itself provides only
-local (sequential) functions. If necessary, the user (or a language
-implementor who wishes to use futures) can send converse messages
-across processors, and have their handlers set the future's values.
+Halstead and other researchers.
 
-\verb#futuresInitialize()#
 
-This function initializes the futures module. It can deal with
-repeated (redundant) initializations, without losing information
-entered after the previous initialization. Currently, 100 distinct
-future values may be alive at any moment on each processor. This
-number will be made a parameter to the futuresInitialize function in
-future versions.
+{\bf Cfuture CfutureCreate()}
 
-{\large \bf createFuture}
+Returns the handle of an empty future.  The future is said to reside
+on the processor that created it.  The handle is a {\em global}
+reference to the future, in other words, it may be copied freely
+across processors.  However, while the handle may be moved across
+processors freely, some operations can only be performed on the
+processor where the future resides.
 
-\verb#int createFuture()#
+{\bf Cfuture CfutureSet(Cfuture future, void *value, int nbytes)}
 
-Returns an integer key designating the future-value-holder just
-created.
+Makes a copy of the value and stores it in the future.  CfutureSet
+may be performed on processors other than the one where the future
+resides.  If done remotely, the copy of the value is created on the
+processor where the future resides.
 
+{\bf void *CfutureWait(Cfuture fut)}
 
-{\large \bf setFuture}
+Waits until the future has been filled, then returns a pointer to the
+contents of the future.  If the future has already been filled, this
+happens immediately (without blocking).  If the destroy flag is set,
+the future is destroyed (freed) in the process.  The pointer returned
+by CfutureWait must eventually be freed using CfutureDestroyValue
+below.  Caution: CfutureWait can only be done on the processor where
+the Cfuture resides.  A second caution: blocking operations (such as
+this one) can only be done in user-created threads.
 
-\verb#setFuture(int key, void*pointer)#
+{\bf void CfutureDestroy(Cfuture f)}
 
-Sets the value of the future indicate by the key to the given pointer.
-All the threads waiting for the future specified by the key are
-awakened. (Each such thread, when it resumes, will return from the
-waitFuture function with the \verb#pointer# as its return value.)
+Frees the space used by the specified Cfuture.  This also frees the
+value stored in the future.  Caution: this operation can only be done
+on the processor where the Cfuture resides.
 
-{\large \bf sendToFuture}
+{\bf void* CfutureCreateValue(int nbytes)}
 
-\verb#sendToFuture(void *m, int key)#
+Allocates the specified amount of memory and returns a pointer to it.
+The memory can be freed by CfutureDestroyValue, just as if it had been
+extracted from a future.  It can also be filled with data and stored
+into a future, using CfutureStoreBuffer below.
 
-Makes an entry in the scheduler's queue that will (when scheduled) set
-the future value, and awaken the waiting threads. This is an
-asynchronous version of \verb#setFuture#. 
+{\bf void CfutureStoreValue(Cfuture fut, void *value)}
 
+Make a copy of the value and stores it in the future, destroying the
+original copy of the value.  This may be significantly faster than the
+more general function, CfutureSet (it may avoid copying).  This
+function can {\em only} used to store values that were previously
+extracted from other futures, or values that were allocated using
+CfutureCreateValue.
 
-{\large \bf  waitFuture}
+{\bf void CfutureModuleInit()}
 
-\verb#void* waitFuture (int key, int free)#
-
-The caller for this function must be a thread. If the future value is
-ready (i.e. set by \verb#setFuture# or \verb#sendToFuture#), the
-function returns immediately with a pointer to the value. Otherwise,
-the calling thread suspends, and the call returns after another thread
-has set the future value. This call can be made before or after the future
-is set.
-
-destroyFuture(int key)
-
-Allows  the key to be used for other futures.
-
-{\large \bf Bugs:} Currently, the number of futures is limited to 100.
-Although you can reuse a key with destroyFuture, this limits the
-number of futures alive at a time to 100. With a hash table
-implementation this could be completely eliminated in a future
-release, or at least an ability to change the number of available keys
-at the initialization time will be added.
+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).
 
index 25094f8989dd670194f794ac55b6e00b9089cb58..a64d78b2e03dc52b809a0bbb108ce3fef76f6b2c 100644 (file)
@@ -76,5 +76,7 @@ need to read any part of this manual to use Converse.}
 \input{msgmgr}
 \input{cpm}
 \input{ldb}
+\input{futures}
+\input{pthreads}
 
 \end{document}
diff --git a/doc/convext/pthreads.tex b/doc/convext/pthreads.tex
new file mode 100644 (file)
index 0000000..8d0adb7
--- /dev/null
@@ -0,0 +1,99 @@
+\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:
+
+\verb/#include <cpthreads.h>/
+
+Refer to the POSIX threads documentation for the documentation on the
+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}
+
+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.
+
+\section{Suppressing Name Conflicts}
+
+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
+the preprocessor symbol SUPPRESS\_PTHREADS:
+
+\begin{verbatim}
+#define SUPPRESS_PTHREADS
+#include <cpthreads.h>
+\end{verbatim}
+
+\section{Interoperating with Other Thread Packages}
+
+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
+threads created with pthread\_create.  Threads created by other thread
+packages (for example, the CthThread package) may not use the pthreads
+functions.
+
+\section{Preemptive Context Switching}
+
+Most implementations of POSIX threads perform time-slicing: when a thread
+has run for a while, it automatically gives up the CPU to another thread.
+Our implementation is currently nonpreemptive (no time-slicing).  Threads
+give up control at two points:
+
+\begin{itemize}
+\item{If they block (eg, at a mutex).}
+\item{If they call pthread_yield().}
+\end{itemize}
+
+Usually, the first rule is sufficient to make most programs work.
+However, a few programs (particularly, those that busy-wait) may need
+explicit insertion of yields.
+
+\section{Limits on Blocking Operations in main}
+
+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
+startup function (see ConverseInit) may not block.  You must be aware
+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
+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
+mymain}.  We provide a convenience function to do this, called
+Cpthreads\_start\_main.  The startup code will be much like this:
+
+\begin{verbatim}
+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}
+
+This creates the first POSIX thread on each processor, which runs the
+function mymain.  The mymain function is executing in a POSIX thread,
+and it may use any pthread function it wishes.
+
+\section{CpthreadModuleInit}
+
+On each processor, the function CpthreadModuleInit must be called
+before any other pthread function is called.  This is shown in the
+example in the previous section.