doc/charm++: startup text revisions
[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 \section{Interprocessor Messaging}
65
66 Figure~\ref{fig:converse-msg} illustrates how to write a simple program that sends a message from one processor to other. In the example program, function \textttP{sendData} shows how to send a message. First, one must create a buffer to hold the message. The buffer must be large enough to hold the header and the data. This is done by \texttt{CmiAlloc} call. \texttt{CmiMsgHeaderSizeBytes} is a constant which contains the size of the header. Next, the handler method should be set for the outgoing message using \texttt{CmiSetHandler} call. User data can be set after the header. In this example, we use \texttt{CmiSyncSendAndFree} call to send the message. This function sends the message and frees the buffer. There are various alternatives. The first argument of this function call is the processor number where we want to send the message, second argument is the size of the message (including header) and the last argument is a pointer to the message.
67 \begin{itemize}
68 \item
69 sync: a version that is as simple as possible, pushing the data into the network and not returning until the data is ``in the network''. As soon as a sync function returns, you can reuse the message buffer.
70
71 \item
72 async: a version that returns almost instantaneously, and then continues working in the background. The background job transfers the data from the message buffer into the network. Since the background job is still using the message buffer when the function returns, you can't reuse the message buffer immediately. The background job sets a flag when it is done and you can then reuse the message buffer.
73
74 \item
75 send and free: a version that returns almost instantaneously, and then continues working in the background. The background job transfers the data from the message buffer into the network. When the background job finishes, it CmiFrees the message buffer. In this situation, you can't reuse the message buffer at all. To use a function of this type, you must allocate the message buffer using CmiAlloc.
76
77 \item
78 node: a version that send a message to a node instead of a specific processor. This means that when the message is received, any ``free'' processor within than node can handle it. 
79 \end{itemize}
80
81 On the receiver, appropiate handler function is called and a pointer to the message (starting from the header) is provided to the user. User must free the message after using the data using \texttt{CmiFree} call. Finally we also illustrate a broadcast message using \texttt{CmiSyncBroadcastAllAndFree}
82
83 TODO: Examples of other modes
84
85 \begin{figure}
86 \lstinputlisting[language=pseudo,basicstyle=\footnotesize,numbers=left,escapechar=\%]{code/interNodeMsg.C}
87 \caption{Sending Message across Converse Processes}
88 \label{fig:converse-pingpong}
89 \end{figure}
90
91 \end{document}