\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{alltt}
#define SUPPRESS_PTHREADS
#include <cpthreads.h>
\end{alltt}

\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{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{alltt}

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.
