Finalize example program and write corresponding text for it in the tutorial.
[charm.git] / doc / converse / tutorial.tex
1 \documentclass[10pt]{report}
2 \usepackage{../pplmanual}
3 \input{../pplmanual}
4
5 \title{\converse{}\\Programming\\Tutorial}
6 \version{1.0}
7 \credits{
8 \converse{} Parallel Programming Environment was developed as a group
9 effort at Parallel Programming Laboratory, University of Illinois at
10 Urbana-Champaign.
11 }
12 \begin{document}
13 \maketitle
14
15 \chapter{Introduction}
16 \lstdefinelanguage{pseudo}{
17 morekeywords={if, else, for, in, remove, from, case, do, forever, to, False, True},
18 sensitive=true,%
19 morecomment=[l]\#,%
20 morestring=[b]',%
21 }
22
23 \section{CthThreads}
24
25 The CthThread package, like most thread packages, provides basic functionality
26 for creating threads, destroying threads, yielding, suspending, and awakening a
27 suspended thread. In addition, it provides facilities whereby you can write
28 your own thread schedulers.
29
30 Figure~\ref{fig:converse-cth} demonstrates how to write a simple program that
31 creates CthThreads. The \texttt{CthCreateMigratable} is used and it takes a
32 handler, an argument pointer, and the stack size for the thread. This is
33 demonstrated in the \texttt{initThreads} function on line number 43. Once the
34 threads are created, they are pushed on the scheduler queue with the
35 \texttt{CthAwaken} call, which only takes the \texttt{CthThread} as an
36 argument. On being scheduled, the handler function is called.
37
38 In the example, each thread then calls \texttt{CthYield}, which directs control
39 back to the scheduler and pushes the thread back onto the queue. Then in a
40 loop, each thread calls \texttt{CthYieldPrio} \texttt{NUM\_YIELD} times, with
41 the queuing strategy and necessary parameters. The threads call this with
42 priority $0$ and $1$, lower integers (but non-negative) indicating higher
43 priority. The effect of yielding with priority is that the higher priority
44 thread on the queue has precedence over the other threads and hence will be
45 scheduled first, based on the greedy decision the scheduler makes.
46
47 After this loop completes, the \texttt{threadDone} is called by each
48 thread, which increments a counter and quits the program when all threads are
49 done.
50
51 \begin{figure}
52 \lstinputlisting[language=pseudo,basicstyle=\footnotesize,numbers=left,escapechar=\%]{code/pingpong.pseudo}
53 \caption{A Pingpong Example using Converse Handler}
54 \label{fig:converse-pingpong}
55 \end{figure}
56
57 \begin{figure}
58  \VerbatimInput[numbers=left,frame=single,firstline=1,lastline=53]{code/cth-tutorial/pgm.C}
59  \caption{CthThread Example}
60  \label{fig:converse-cth}
61 \end{figure}
62
63
64 \end{document}