Debian Codegraph @

texmf-dist/source/latex/messagepassing/messagepassing.dtx

raw
1 % \iffalse meta-comment
2 % Copyright (C) 2022 by Martin Vassor
3 % This file may be distributed and/or modified under the
4 % conditions of the LaTeX Project Public License, either
5 % version 1.3 of this license or (at your option) any later
6 % version. The latest version of this license is in:
7 %
8 % http://www.latex-project.org/lppl.txt
9 %
10 % and version 1.3 or later is part of all distributions of
11 % LaTeX version 2005/12/01 or later.
12 %
13 % \fi
14
15 % \iffalse
16 %<package> \NeedsTeXFormat{LaTeX2e}
17 %<package> \ProvidesPackage{messagepassing}[2023/12/13 v1.2 A package to draw message passing diagrams]
18 %<package> \RequirePackage{tikz}
19 %<package> \usetikzlibrary{quotes, calc, arrows.meta}
20 %<package> \RequirePackage{xparse}
21 %<package> \RequirePackage{float}
22 %
23
24 %<*driver>
25 \documentclass{ltxdoc}
26 \usepackage{messagepassing}
27 \usepackage[hidelinks]{hyperref}
28 \usepackage{xspace}
29 \usepackage[super]{nth}
30 \usepackage{subcaption}
31 \usepackage{listings}
32 \lstset{
33 language=[LaTeX]{TeX},
34 }
35 \EnableCrossrefs
36 \CodelineIndex
37 \RecordChanges
38 \begin{document}
39 \DocInput{messagepassing.dtx}
40 \end{document}
41 %</driver>
42 % \fi
43
44 % \CheckSum{0}
45 %
46 % \CharacterTable
47 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
48 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
49 % Digits \0\1\2\3\4\5\6\7\8\9
50 % Exclamation \! Double quote \" Hash (number) \#
51 % Dollar \$ Percent \% Ampersand \&
52 % Acute accent \' Left paren \( Right paren \)
53 % Asterisk \* Plus \+ Comma \,
54 % Minus \- Point \. Solidus \/
55 % Colon \: Semicolon \; Less than \<
56 % Equals \= Greater than \> Question mark \?
57 % Commercial at \@ Left bracket \[ Backslash \\
58 % Right bracket \] Circumflex \^ Underscore \_
59 % Grave accent \` Left brace \{ Vertical bar \|
60 % Right brace \} Tilde \~}
61 %
62 %
63 % \changes{v1.2}{2023/12/13}{Add optional display names in processes and message node options}
64 % \changes{v1.1}{2022/07/20}{Consistent spelling of "colour"}
65 % \changes{v1.0}{2022/02/18}{Initial version for publication}
66 %
67 % \GetFileInfo{messagepassing.sty}
68 %
69 % \title{The \textsf{messagepassing} package\thanks{This document
70 % corresponds to \textsf{messagepassing}~\fileversion,
71 % dated \filedate.}}
72 % \author{Martin Vassor\\ \texttt{[email protected]}}
73 %
74 %
75 % \maketitle
76 % \tableofcontents
77 % \newcommand{\TikZ}{Ti\textit{k}Z\xspace}
78
79 % \section{Introduction}
80 % This package provides an environment and associated macros to easily draw
81 % message passing diagrams. For instance, Execution.~\ref{mp:ex1} shows the capabilities offered
82 % by the package.
83 %
84 % \begin{messagepassing}[][An example of message passing][h][mp:ex1]
85 % \newprocesswithlength{p}{9}
86 % \newprocesswithlength{q}{9}
87 % \newprocesswithlength{r}{5}
88 % \crash{r}{5}{k}
89 %
90 % \checkpoint{p}{0}{c_p^0}
91 % \checkpoint{q}{0}{c_q^0}
92 % \checkpoint{r}{0}{c_r^0}
93 % \checkpoint{p}{4}{c_p^1}
94 %
95 % \stateinterval{p}{0}{si_p^0}
96 % \stateinterval{q}{0}{si_q^0}
97 % \stateinterval{r}{0}{si_r^0}
98 %
99 % \sendwithstateinterval{p}{1}{q}{2}{si_q^1}
100 % \sendwithstateinterval{r}{3}{q}{4}{si_q^2}
101 % \sendwithstateintervalandname{q}{5}{p}{6}{si_p^1}{\(m\)}
102 % \sendoutofband{q}{5}{r}{6}{\(m_\mathrm{copy}\)}
103 % \stateinterval{r}{6}{si_r^0}
104 % \restart{r}{6}{3}
105 %
106 % \annotate{r}{8}{restart}
107 % \annotatexplicit{p}{8}{\(1+1=2\)}{note}
108 %
109 % \colouredbox{p}{q}{7}{9}{Protocol}
110 %
111 % \drawtimeline{9}
112 % \end{messagepassing}
113
114 %
115 % \section{Usage}
116 % \subsection{Loading the package}
117 % The package accepts two options: \verb+vertical+ and \verb+annotatevertical+.
118 % If the former is set, executions will be drawn with time going from top to
119 % bottom, instead of from left to right. Doing so, almost all
120 % labels\footnote{Annotations are not rotated, unless explicitly asked.} are
121 % rotated as well. If, \emph{in addition}, \verb+annotatevertical+ is set, then
122 % annotations (including names of colouredboxes) are rotated as well.
123
124 % \subsection{Basic usage}
125 % \subsubsection{Creating a diagram.}
126
127 % \DescribeEnv{messagepassing} A diagram can easily be created using the
128 % |messagepassing| environment. The syntax is:
129 % |\begin{messagepassing}| \oarg{tikz} \oarg{caption} \oarg{placement}
130 % \oarg{label}.
131 % The first optional argument (\emph{tikz}) contains arguments that are passed
132 % to the underlying tikz environment. The second argument (\emph{caption}) has
133 % two effect: if set, it turns the diagram into a floating figure, and the
134 % content of the argument is the caption of the floating figure. The third
135 % argument (\emph{placement}) is the placement option of the figure, the default
136 % is |p|. Finally, the fourth option (\emph{label}) is the label used to
137 % reference the figure.
138 %
139 % For instance, the diagram in Figure~\ref{mp:ex1} is created with the following
140 % commands:
141 % \begin{verbatim}
142 % \begin{messagepassing}[][An example of message passing][h][mp:ex1]
143 % % ...
144 % \end{messagepassing}
145 % \end{verbatim}
146
147 % \paragraph{Setting up the diagram.}
148 % When created, the diagram is empty. Before actually writing the message
149 % exchanges, we have to set up a few things: set whether we want a timeline (and
150 % if it is the case, of which length), and set the number of processes with
151 % their names, etc.
152 % \subparagraph{Creating a new process.}
153 % Each process is characterised by its name.
154 % \DescribeMacro{\newprocess} The simplest macro to create a new process is then
155 % |\newprocess| \marg{name} \oarg{display name}, where \marg{name} is the name
156 % of the process (resp. \(p\), \(q\), and \(r\) in Figure~\ref{mp:ex1}). If
157 % \oarg{display name} is provided, it is used as the name when rendering the
158 % figure, while \marg{name} is used internally to refer to the process. This
159 % allows you to use names that can not be used internally (e.g.\ with maths or
160 % things like that).
161 %
162 % In addition, we often draw a horizontal\footnote{By default, the line is vertical if
163 % the option |vertical| is used.} line that represent the running process.
164 % Although this line can be manually
165 % added\footnote{|processlength|\marg{process}\marg{length}
166 % creates a line of length \emph{length} for process \emph{process}.}, we also
167 % provide a simple macro that performs both actions:
168 % \DescribeMacro{\newprocesswithlength}
169 % |\newprocesswithlength|\marg{name}\oarg{display name}\marg{length}.
170 %
171 % An other alternative is to name the state in which the process starts (in
172 % Fig~\ref{mp:ex1}, we call those states \(si\) as \emph{state intervals}).
173 % Again, this can be achieved using individual commands, but we also provide
174 % \DescribeMacro{\newprocesswithstateinterval}
175 % |\newprocesswithstateinterval|\marg{name}\oarg{display name}\marg{state name}.
176 %
177 % Finally, an other way to create a process is to create a process that
178 % (eventually) fails, which is represented by the process' line terminating
179 % early with a cross. For that, we provide \DescribeMacro{\newprocesswithcrash}
180 % |\newprocesswithcrash|\marg{name}\oarg{display name}\marg{length}\marg{crash coordinate name}.
181 % The first arguments are similar to |\newprocesswithlength|, and the last one
182 % is used to provide a name for the coordinate where the crash occurs. This name
183 % can later be used to place nodes.
184 %
185 % Of course, we can imagine other combinations (e.g. a process with a length and
186 % a state interval). We do not provide individual commands for each combination,
187 % but the can be easily achieved using separate commands.
188 %
189 % As an example, the processes of Fig.~\ref{mp:ex1} are created as follows.
190 % \begin{verbatim}
191 % \newprocesswithlength{p}{9}
192 % \newprocesswithlength{q}{9}
193 % \newprocesswithlength{r}{5}
194 % \end{verbatim}
195 %
196 % \subparagraph{Setting up a timeline.}
197 % An other setup action consists in setting up (if wanted) the timeline. Notice
198 % that this can be done \emph{at any place} in the diagram. To do so, simply use
199 % the command \DescribeMacro{\drawtimeline}|\drawtimeline|\marg{length}, where
200 % \emph{length} is the length of the desired timeline.
201
202 % \subsubsection{Populating the run.}
203 % Now that we have some processes, we have to populate the diagram with some
204 % actions.
205 %
206 % \paragraph{Basic message.}
207 % The most basic action is to send a message. For that, we provide the command
208 % \DescribeMacro{\send} |\send|\marg{sender}\marg{send
209 % time}\marg{receiver}\marg{receive time}. The sender and receiver are
210 % identified with their names, and the sending and receiving times are given
211 % according to their timestamp\footnote{Notice that nothing prevents sending
212 % messages in the past, simply set a receiving time before the sending time.}.
213 %
214 % For instance, in Figure~\ref{fig:ex_msg}, we use |\send{p}{1}{q}{2}|.
215 %
216 % In addition, we can label the arrow with the message that is sent with
217 % \DescribeMacro{\sendwithname}
218 % |\sendwithname|\marg{sender}\marg{send time}\marg{receiver}\marg{receive
219 % time}\marg{label}\oarg{label options}. The \marg{label} contains the label
220 % that should be displayed. The package provides default positioning options for
221 % the label, which should be acceptable for most cases. Those positioning
222 % options can be overridden by \oarg{label options}, which should be \TikZ node
223 % options.
224 %
225 % Finally, we sometimes distinguish \emph{out-of-band} messages, e.g. messages
226 % that do not carry informations, but that are for instance used for metadata,
227 % etc.. We provide the macro
228 % \DescribeMacro{\sendoutofband}|\sendoutofband|\marg{sender}\marg{send time}\marg{receiver}\marg{receive
229 % time}\marg{label}\oarg{label options}, which behaves similarly to |\sendwithname|, but prints the
230 % message in an other colour.
231 %
232 % \begin{figure}
233 % \centering
234 % \begin{minipage}{.35\textwidth}
235 % \begin{messagepassing}
236 % \newprocesswithlength{p}{4}
237 % \newprocesswithlength{q}{4}
238 % \send{p}{1}{q}{2}
239 % \sendwithname{p}{2}{q}{3}{msg}
240 % \end{messagepassing}
241 % \end{minipage}
242 % ~
243 % \begin{minipage}{.60\textwidth}
244 % \iffalse
245 %<*example>
246 % \fi
247 % \begin{lstlisting}
248 \begin{messagepassing}
249 \newprocesswithlength{p}{4}
250 \newprocesswithlength{q}{4}
251 \send{p}{1}{q}{2}
252 \sendwithname{p}{2}{q}{3}{msg}
253 \end{messagepassing}
254 \end{lstlisting}
255 % \iffalse
256 %</example>
257 % \fi
258 % \end{minipage}
259 % \caption{A very simple protocol with a single message exchanged.}
260 % \label{fig:ex_msg}
261 % \end{figure}
262 %
263 %
264
265 % \paragraph{Process crash and restore.}
266 % The crash of a process can be represented using
267 % \DescribeMacro{\crash}
268 % |\crash|\marg{process name}\marg{time}\marg{crash name}. The argument \emph{process name}
269 % is the name of the process that crashes, and \emph{crash name} is used to give
270 % a name to the crash. Naming the crash is useful for coordinates (see below).
271 % Finally, \emph{time} specifies when the crash occurs. Notice that this does
272 % not modify the timeline: it simply adds a crash token at the specified
273 % coordinate. This means that (i) then timeline has to stop at the crash's time;
274 % and (ii) it has to be restarted after. To stop the timeline, simply take the
275 % crash into account when setting the initial timeline. To restart the timeline,
276 % we provide the command
277 % \DescribeMacro{\restart}|\restart|\marg{name}\marg{date}\marg{duration}.
278 % \emph{name} specifies which process is to be restarted; \emph{date} specifies
279 % when the process should be restarted, and \emph{duration} specifies how long
280 % the process shoud be alive (i.e. what is the length of the timeline) after the
281 % restart.
282 % \begin{figure}
283 % \centering
284 % \begin{minipage}{.35\textwidth}
285 % \begin{messagepassing}
286 % \newprocesswithlength{p}{4}
287 % \newprocesswithlength{q}{2}
288 % \send{p}{1}{q}{2}
289 % \crash{q}{2}{crash}
290 % \restart{q}{3}{1}
291 % \end{messagepassing}
292 % \end{minipage}
293 % ~
294 % \begin{minipage}{.60\textwidth}
295 % \iffalse
296 %<*example>
297 % \fi
298 % \begin{lstlisting}
299 \begin{messagepassing}
300 \newprocesswithlength{p}{4}
301 \newprocesswithlength{q}{2}
302 \send{p}{1}{q}{2}
303 \crash{q}{2}{crash}
304 \restart{q}{3}{1}
305 \end{messagepassing}
306 \end{lstlisting}
307 % \iffalse
308 %</example>
309 % \fi
310 % \end{minipage}
311 % \caption{A protocol with a crashed process.}
312 % \end{figure}
313 %
314
315 % \paragraph{Tokens on the run}
316 %
317 % The package also proposes two kinds of tokens that can be added on protocols'
318 % lines. The first one is a \emph{checkpoint} (i.e. a state that is saved
319 % somewhere) and the second is used to denote the begining of a \emph{state
320 % interval} (a state interval denotes a period in which a process only performs
321 % deterministic events). The former are denoted with a small black rectangle,
322 % while the later is denoted with a vertical line. Although those two tokens are
323 % intended for the usage mentionned above, we encourage users to use them for
324 % other usages if need be.
325 %
326 % A checkpoint can be added with
327 % \DescribeMacro{\checkpoint}|\checkpoint|\marg{process}\marg{time}\marg{name},
328 % where \emph{process} is the name of the process which takes a checkpoint,
329 % \emph{time} is the time at which the checkpoint is taken, and \emph{name}
330 % is the name of the checkpoint, that is printed next to it, and can be used as
331 % a coordinate. Notice that the name is printed in a math environment, as we
332 % expect most checkpoints names to be indexed, e.g.\(c_1\), \(c_2\), etc.
333 % To have more control on the printed name, or if the proposed name is not a
334 % valid coordinate name, we offer a variant
335 % \DescribeMacro{\checkpointspecial}|\checkpointspecial|\marg{process}\marg{time}\marg{name}\marg{label},
336 % where \emph{name} is the name of the coordinate of the checkpoint, and
337 % \emph{label} is the label to be printed. Notice that, in that case, the label
338 % is printed as is, i.e. not typeset as maths.
339
340 %
341 % A state interval can be added similarly with the command
342 % \DescribeMacro{\stateinterval}|\stateinterval|
343 % \marg{process}\marg{time}\marg{name}.
344 %
345 % For the sake of completeness, if you need the name of the coordinate and the
346 % displayed label to be different (e.g. if the label can not be the name of a
347 % coordinate, for whatever reason), we also provide the command
348 % \DescribeMacro{\stateintervalspecial}
349 % |\stateintervalspecial|\marg{process}\marg{time}\marg{name}\marg{label}, in
350 % which \emph{name} is the name of the created coordinate, and \emph{label} is
351 % the label attached to the state interval.
352
353 % \begin{figure}
354 % \centering
355 % \begin{minipage}{.35\textwidth}
356 % \begin{messagepassing}
357 % \newprocesswithlength{q}{2}
358 % \checkpoint{q}{1}{c_1}
359 % \crash{q}{2}{crash}
360 % \restart{q}{3}{1}
361 % \end{messagepassing}
362 % \end{minipage}
363 % ~
364 % \begin{minipage}{.60\textwidth}
365 % \iffalse
366 %<*example>
367 % \fi
368 % \begin{lstlisting}
369 \begin{messagepassing}
370 \newprocesswithlength{q}{2}
371 \checkpoint{q}{1}{c_1}
372 \crash{q}{2}{crash}
373 \restart{q}{3}{1}
374 \end{messagepassing}
375 \end{lstlisting}
376 % \iffalse
377 %</example>
378 % \fi
379 % \end{minipage}
380 % \caption{A protocol with a checkpoint.}
381 % \end{figure}
382
383 % \paragraph{Grey boxes}
384 %
385 % In Execution~\ref{mp:ex1}, we created a light-red box between processes \(p\)
386 % and \(q\), from time \(7\) to \(9\), to indicate that they perform a given
387 % protocol that we don't detail further. We call such boxes (which can be used for a lot
388 % of other purposes) \emph{colouredboxes}, and they
389 % can be added with \DescribeMacro{\colouredbox} |\colouredbox|\marg{first
390 % process}\marg{second process}\marg{start time}\marg{end time}\marg{label}.
391 % This creates a box that spans between \emph{first process} and \emph{second
392 % process}, from \emph{start time} to \emph{end time}, with the label
393 % \emph{label} printed.
394 %
395 % Notice that there are no technical restrictions to adding messages on top of a
396 % box, typically to highlight a specific part of a larger execution.
397
398 % \paragraph{Annotations}
399 % Finally, it is possible to add annotations on the diagram. To do so, we
400 % provide the macro
401 % \DescribeMacro{\annotate}|\annotate|\marg{process}\marg{time}\marg{text} which
402 % adds an annotation with \emph{text} over the timeline of the given
403 % \emph{process} at time \emph{time}. This also creates a coordinate at the
404 % annotation time, which name is the content of the annotation (i.e.\
405 % \emph{text}). If \emph{text} is not a valid coordinate name, then the
406 % alternative \DescribeMacro{\annotatexplicit}
407 % |\annotatexplicit|\marg{process}\marg{time}\marg{text}\marg{name} behaves
408 % similarly, except that the coordinate name is explicitly given in argument
409 % \emph{name}.
410
411 % \subsubsection{Combined commands}
412 % The above commands are sufficient to use all primitives offered by the
413 % package. In addition, we provide a lot of \emph{combined commands}, which, as
414 % the name suggest, have the effect of multiple \emph{simple} commands.
415 %
416 % \begin{itemize}
417 % \item |\newprocesswithlength|\marg{name}\marg{lifetime}: combination of
418 % |\newprocess|\marg{name} and |\processlength|\marg{name}\marg{lifetime}
419 % \item |\newprocesswithstateinterval|\marg{process name}\marg{state interval
420 % name}: combination of |\newprocess|\marg{process name} and
421 % |\stateinterval|\marg{process name}\marg{0}\marg{state interval name}
422 % \item |\newprocesswithcrash|\marg{process name}\marg{crash time}\marg{crash
423 % name}: creates a process \emph{process name} that runs until \emph{crash
424 % time}. The crash is named \emph{crash name}.
425 % \item |\sendwithstateinterval|\marg{sender}\marg{send
426 % time}\marg{receiver}\marg{receive time}\marg{si name}: combines |\send| and
427 % |\stateinterval|.
428 % \item |\sendwithstateintervalandname|\marg{sender}\marg{send
429 % time}\marg{receiver}\marg{receive time}\marg{si name}\marg{message name}:
430 % combines |\sendwithname| and |\stateinterval|
431 % \end{itemize}
432
433 % \subsection{Advanced usage}
434 % \subsubsection{Customising colours}
435 %
436 % Two parts of the package use colours: colouredboxes and out-of-band messages. By
437 % default both are shades of red. We provide commands to change that if desired.
438 %
439 % \DescribeMacro{\colouredboxcolour}|\colouredboxcolour|\marg{colour} changes the colour
440 % used for colouredboxes. Notice that this sets both the background colour (which is
441 % a light variant of the provided colour) and the text colour (which uses the
442 % provided colour).
443 %
444 % \DescribeMacro{\oobcolour}|\oobcolour|\marg{colour} changes the colour used for
445 % out-of-band messages.
446 %
447 % \subsubsection{Coordinates}
448 %
449 % \paragraph{\TikZ coordinates.}
450 % Message passing diagrams are drawn using \TikZ, which means that one can add
451 % arbitrary commands to a diagram. In addition, the package defines useful
452 % coordinates to refer to. Execution~\ref{mp:ex2} shows the \TikZ coordinate plan
453 % overlayed on top of Execution~\ref{mp:ex1}.
454 %
455 % On \TikZ \(y\)-axis processes are instanciated one unit apart from each other,
456 % in their declaration order.
457 % To keep the coordinate system simple, processes expand in the negative (e.g.
458 % the first process declared is at coordinate \((0, -1)\), the second at \((0,
459 % -2)\), etc.).
460 %
461 % The \TikZ \(x\)-axis corresponds to the time axis of the diagram. Therefore,
462 % e.g. coordinate \((3, -4)\) corresponds to the \nth{3} time step of the
463 % \nth{4} process.
464 %
465 % \paragraph{Named coordinates.}
466 % In addition to explicit coordinates explained above, the package names most of
467 % the points of interest in the diagram.
468 %
469 % \subparagraph{Coordinates of processes.}
470 % At each process declaration, a coordinate named after the name of the process
471 % is created. The coordinate corresponds to the beginning of the corresponding
472 % process' timeline (for instance, in Execution~\ref{mp:ex2}, we show coordinate
473 % \((\texttt{q})\), that corresponds to the process \(q\)).
474 %
475 % \subparagraph{Coordinate of states intervals (resp. checkpoints, resp. crashes).}
476 % Similarly to processes, each state interval (resp. checkpoint, resp. crashes) creates a
477 % coordinate, named after the name of the state interval (resp. checkpoint,
478 % resp. crashes), is created. The coordinates refers to the place of the state
479 % interval (resp. checkpoint, resp. crashes). For instance, in
480 % Execution~\ref{mp:ex2}, we show the coordinates \((\texttt{si\_q\^{}1})\),
481 % \((\texttt{c\_p\^{}1})\) and \((\texttt{k})\), that respectively correspond to the state interval
482 % \(si_q^1\), the checkpoint \(c_p^1\) and the crash\footnote{The names of
483 % crashes are not printed on the figure, although they are internally defined.} \(k\).
484 %
485 % \subparagraph{Coordinates of annotations.}
486 % When an annotation is created, a coordinate is created at the same place, on
487 % the process' timeline\footnote{Notice that, using the explicit variant of |annotate|
488 % (|annotatexplicit|), the name of the annotation has to be explicitly given.}
489 % For instance, in Execution~\ref{mp:ex1}, the annotation \(1+1=2\) is created
490 % with the explicit name ``\texttt{note}''. We show the corresponding coordinate in
491 % Execution~\ref{mp:ex2}.
492 %
493 %
494 % \begin{messagepassing}[][Showing \TikZ coordinates][h][mp:ex2]
495 % \newprocesswithlength{p}{9}
496 % \newprocesswithlength{q}{9}
497 % \newprocesswithlength{r}{5}
498 % \crash{r}{5}{k}
499 %
500 % \checkpoint{p}{0}{c_p^0}
501 % \checkpoint{q}{0}{c_q^0}
502 % \checkpoint{r}{0}{c_r^0}
503 % \checkpoint{p}{4}{c_p^1}
504 %
505 % \stateinterval{p}{0}{si_p^0}
506 % \stateinterval{q}{0}{si_q^0}
507 % \stateinterval{r}{0}{si_r^0}
508 %
509 % \sendwithstateinterval{p}{1}{q}{2}{si_q^1}
510 % \sendwithstateinterval{r}{3}{q}{4}{si_q^2}
511 % \sendwithstateintervalandname{q}{5}{p}{6}{si_p^1}{\(m\)}
512 % \sendoutofband{q}{5}{r}{6}{\(m_\mathrm{copy}\)}
513 % \stateinterval{r}{6}{si_r^0}
514 % \restart{r}{6}{3}
515 %
516 % \annotate{r}{8}{restart}
517 % \annotatexplicit{p}{8}{\(1+1=2\)}{note}
518 %
519 % \colouredbox{p}{q}{7}{9}{Protocol}
520 % \drawtimeline{9}
521 %
522 %
523 % \fill[fill=white, opacity=0.8] (-1, 0) rectangle (10, -5);
524 %
525 % \draw[dotted, gray] (-1,0) grid (10,-5);
526 % \draw[->, thick, red] (0, 0) -- (1, 0) node [anchor=south, text=black] {\((1, 0)\)};
527 % \draw[->, thick, red] (0, 0) -- (0, -1) node [anchor=east, text=black] {\((0, -1)\)};
528 %
529 % \draw[fill] (q) circle [radius=.5mm];
530 % \node[anchor=east] at (q) {\((\texttt{q})\)};
531 %
532 % \draw[fill] (si_q^1) circle [radius=.5mm];
533 % \node[anchor=east] at (si_q^1) {\((\texttt{si\_q\^{}1})\)};
534 %
535 % \draw[fill] (c_p^1) circle [radius=.5mm];
536 % \node[anchor=east] at (c_p^1) {\((\texttt{c\_p\^{}1})\)};
537 %
538 % \draw[fill] (k) circle [radius=.5mm];
539 % \node[anchor=east] at (k) {\((\texttt{k})\)};
540 %
541 % \draw[fill] (note) circle [radius=.5mm];
542 % \node[anchor=east] at (note) {\((\texttt{note})\)};
543 %
544 % \end{messagepassing}
545
546 % \StopEventually{}
547 %
548 % \section{Implementation}
549
550 % \begin{macrocode}
551 \newcounter{processnb}
552 \setcounter{processnb}{0}
553 \newcounter{maxtime}
554
555 \pgfdeclarelayer{background}
556 \pgfsetlayers{background,main}
557
558 \newfloat{float_messagepassing}{t b h p}{.mp}
559 \floatname{float_messagepassing}{Execution}
560
561 \newif\ifmp@vertical\mp@verticalfalse
562 \DeclareOption{vertical}{
563 \mp@verticaltrue
564 }
565 \newif\ifmp@annotatevertical\mp@annotateverticalfalse
566 \DeclareOption{annotatevertical}{
567 \mp@annotateverticaltrue
568 }
569 \ProcessOptions\relax
570
571 \ifmp@vertical
572 \newcommand{\mp@processnameanchor}{south}
573 \newcommand{\mp@timeticksanchor}{east}
574 \newcommand{\mp@messagelabelanchor}{south}
575 \newcommand{\mp@stateintervalanchor}{north west}
576 \newcommand{\mp@checkpointanchor}{east}
577 \newcommand{\mp@verticalrotation}{270}
578 \ifmp@annotatevertical
579 \newcommand{\mp@annotaterotation}{270}
580 \else
581 \newcommand{\mp@annotaterotation}{0}
582 \fi
583 \else
584 \newcommand{\mp@processnameanchor}{east}
585 \newcommand{\mp@timeticksanchor}{north}
586 \newcommand{\mp@messagelabelanchor}{west}
587 \newcommand{\mp@stateintervalanchor}{south west}
588 \newcommand{\mp@checkpointanchor}{north}
589 \newcommand{\mp@verticalrotation}{0}
590 \newcommand{\mp@annotaterotation}{0}
591 \fi
592
593 \newcommand{\mp@oobcolour}{red}
594 \newcommand{\oobcolour}[1]{
595 \renewcommand\mp@oobcolour{#1}
596 }
597
598 \newcommand{\mp@colouredboxcolour}{red}
599 \newcommand{\colouredboxcolour}[1]{
600 \renewcommand\mp@colouredboxcolour{#1}
601 }
602
603 \newif\iftimeline
604 % \end{macrocode}
605 %
606
607 %\begin{environment}{messagepassing}
608 % \begin{macrocode}
609 \ExplSyntaxOn
610 %% 1st argument: tikz arguments
611 %% 2nd argument: Float caption (turns in floating)
612 %% 3rd argument: Float placement (`p` by default)
613 %% 4th argument: Float label
614 \NewDocumentEnvironment{messagepassing} {o o o o}
615 {
616 \timelinefalse
617 \setcounter{processnb}{0}
618 \IfNoValueTF{#2} {
619 }{
620 \IfNoValueTF{#3}{
621 \begin{float_messagepassing}[p]
622 } {
623 \begin{float_messagepassing}[#3]
624 }
625 \begin{center}
626 }
627 \IfNoValueTF{#1}{
628 \begin{tikzpicture}[rotate=\mp@verticalrotation]
629 } {
630 \begin{tikzpicture}[rotate=\mp@verticalrotation, #1]
631 }
632 }{
633 %% Draw timeline if boolean is true
634 \iftimeline
635 \begin{pgfonlayer}{background}
636 \setcounter{maxtime}{\@maxtime}
637 \addtocounter{maxtime}{-1}
638 \coordinate (maxtime) at (\@maxtime, 0);
639
640 \addtocounter{processnb}{1}
641 \coordinate (timeline) at (0, -\value{processnb});
642 \draw (timeline) node [anchor=\mp@processnameanchor] {{\it time}};
643 \draw[->] (timeline) -- ($(timeline) + (maxtime)$);
644 \foreach \i in {0,...,\value{maxtime}} {
645 \draw ($(timeline) + (\i, 0) + (0, 0.1)$) -- ($(timeline) + (\i, 0) + (0, -0.1)$) node [anchor=\mp@timeticksanchor] {$\i$};
646 }
647 \end{pgfonlayer}
648 \else
649 \fi
650 \end{tikzpicture}
651 \IfNoValueTF{#2} {
652 \linebreak
653 } {
654 \end{center}
655 \caption{#2}
656 \IfNoValueTF{#4} {
657 }{
658 \label{#4}
659 }
660 \end{float_messagepassing}
661 }
662 }
663 \ExplSyntaxOff
664 % \end{macrocode}
665 % \end{environment}
666 %
667 % \begin{macrocode}
668 %% #1: name
669 %% #2: display name
670 \NewDocumentCommand{\newprocess}{m o}{
671 \addtocounter{processnb}{1}
672 \coordinate (#1) at (0, -\value{processnb});
673 \draw (#1) node[anchor=\mp@processnameanchor] {\IfValueTF{#2}{#2}{$#1$}};
674 }
675 % \end{macrocode}
676 %
677 % \begin{macrocode}
678 %% #1: name
679 %% #2: display name
680 %% #3: width
681 \NewDocumentCommand{\newprocesswithlength}{m o m}{
682 \newprocess{#1}[#2]
683 \processlength{#1}{#3}
684 }
685 % \end{macrocode}
686 %
687 % \begin{macrocode}
688 %% #1: name
689 %% #2: display name
690 %% #3: state interval name
691 \NewDocumentCommand{\newprocesswithstateinterval}{m o m}{
692 \newprocess{#1}[#2]
693 \stateinterval{#1}{0}{#3}
694 }
695 % \end{macrocode}
696 %
697 % \begin{macrocode}
698 %% #1: name
699 %% #2: display name
700 %% #3: width
701 %% #4: crash name
702 \NewDocumentCommand{\newprocesswithcrash}{m o m m}{
703 \newprocess{#1}[#2]{#3}
704 \crash{#1}{#3}{#4}
705 }
706 % \end{macrocode}
707 %
708 % \begin{macrocode}
709 %% #1: sender's name
710 %% #2: send date
711 %% #3: receiver's name
712 %% #4: receive date
713 \newcommand{\send}[4]{
714 \draw[->] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $);
715 }
716 % \end{macrocode}
717 %
718 % \begin{macrocode}
719 %% #1: sender's name
720 %% #2: send date
721 %% #3: receiver's name
722 %% #4: receive date
723 %% #5: message name
724 %% #6: message name display options
725 \NewDocumentCommand{\sendwithname}{m m m m m o}{
726 \IfValueTF{#6}{
727 \draw[->] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $) node[anchor=\mp@messagelabelanchor, pos=0.3, #6] {#5};
728 }{
729 \draw[->] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $) node[anchor=\mp@messagelabelanchor, pos=0.3] {#5};
730 }
731 }
732 % \end{macrocode}
733 %
734 % \begin{macrocode}
735 %% #1: process name
736 %% #2: process width
737 \newcommand{\processlength}[2]{
738 \draw (#1) -- +(#2, 0);
739 }
740 % \end{macrocode}
741 %
742 % \begin{macrocode}
743 %% #1: sender's name
744 %% #2: send date
745 %% #3: receiver's name
746 %% #4: receive date
747 %% #5: state interval name
748 \newcommand{\sendwithstateinterval}[5] {
749 \send{#1}{#2}{#3}{#4}
750 \stateinterval{#3}{#4}{#5}
751 }
752 % \end{macrocode}
753 %
754 % \begin{macrocode}
755 %% #1: sender's name
756 %% #2: send date
757 %% #3: receiver's name
758 %% #4: receive date
759 %% #5: state interval name
760 %% #6: message name
761 %% #7: message name display options
762 \NewDocumentCommand{\sendwithstateintervalandname}{m m m m m m o} {
763 \sendwithname{#1}{#2}{#3}{#4}{#6}[#7]
764 \stateinterval{#3}{#4}{#5}
765 }
766 % \end{macrocode}
767 %
768 % \begin{macrocode}
769 %% #1: sender's name
770 %% #2: send date
771 %% #3: receiver's name
772 %% #4: receive date
773 %% #5: OoB message name
774 %% #6: OoB message name display options
775 \NewDocumentCommand{\sendoutofband}{m m m m m o}{
776 \IfValueTF{#6}{
777 \draw[->, color=\mp@oobcolour] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $) node[anchor=\mp@messagelabelanchor, pos=0.3, #6] {#5};
778 }{
779 \draw[->, color=\mp@oobcolour] (#1) +(#2, 0) -- ($ (#3) +(#4, 0) $) node[anchor=\mp@messagelabelanchor, pos=0.3] {#5};
780 }
781 }
782 % \end{macrocode}
783 %
784 % \begin{macrocode}
785 %% #1: process's name
786 %% #2: state interval date
787 %% #3: state interval name
788 \newcommand{\stateinterval}[3] {
789 \stateintervalspecial{#1}{#2}{#3}{#3}
790 }
791 % \end{macrocode}
792 %
793 % \begin{macrocode}
794 %% #1: process's name
795 %% #2: state interval date
796 %% #3: coordinate name
797 %% #4: state interval label
798 \newcommand{\stateintervalspecial}[4] {
799 \coordinate (#3) at ($ (#1) +(#2, 0) $);
800 \draw (#3) + (0, 0.1) -- +(0, -0.1) node[anchor=\mp@stateintervalanchor] {$#4$};
801 }
802 % \end{macrocode}
803 %
804 % \begin{macrocode}
805 %% #1: process's name
806 %% #2: checkpoint date
807 %% #3: checkpoint name
808 \newcommand{\checkpoint}[3]{
809 \coordinate (#3) at ($ (#1) + (#2, 0) $);
810 \fill (#3) + (-0.05, 0.1) rectangle +(0.05, -0.1);
811 \draw (#3) + (0, -0.1) node[anchor=\mp@checkpointanchor] {$#3$};
812 }
813 % \end{macrocode}
814 %
815 % \begin{macrocode}
816 %% #1: process's name
817 %% #2: checkpoint date
818 %% #3: checkpoint coordinate name
819 %% #4: checkpoint label
820 \newcommand{\checkpointspecial}[4]{
821 \coordinate (#3) at ($ (#1) + (#2, 0) $);
822 \fill (#3) + (-0.05, 0.1) rectangle +(0.05, -0.1);
823 \draw (#3) + (0, -0.1) node[anchor=\mp@checkpointanchor] {#4};
824 }
825 % \end{macrocode}
826 %
827 % \begin{macrocode}
828 %% #1: process's name
829 %% #2: crash date
830 %% #3: crash name
831 \newcommand{\crash}[3]{
832 \coordinate (#3) at ($ (#1) + (#2, 0) $);
833 \draw (#3) + (-0.1, -0.1) -- +(0.1, 0.1);
834 \draw (#3) + (0.1, -0.1) -- +(-0.1, 0.1);
835 }
836 % \end{macrocode}
837 %
838 % \begin{macrocode}
839 %% #1: process's name
840 %% #2: restart date
841 %% #3: restart length
842 \newcommand{\restart}[3]{
843 \draw (#1) + (#2, 0) -- ($ (#1) + (#2, 0) + (#3, 0) $);
844 }
845 % \end{macrocode}
846 %
847 % \begin{macrocode}
848 %% #1: first process's name
849 %% #2: second process's name
850 %% #3: begining of the grey box
851 %% #4: end of the grey box
852 %% #5: caption
853 \newcommand{\colouredbox}[5]{
854 \begin{pgfonlayer}{background}
855 \fill[color=\mp@colouredboxcolour!20] ($(#1) + (#3, 0)$) rectangle ($(#2) + (#4, 0)$) node[midway, color = \mp@colouredboxcolour, rotate=\mp@annotaterotation]{#5};
856 \end{pgfonlayer}
857 }
858 % \end{macrocode}
859 %
860 % \begin{macrocode}
861 %% #1: Timeline length
862 \newcommand{\drawtimeline}[1]{
863 \timelinetrue
864 \def\@maxtime{#1}
865 }
866 % \end{macrocode}
867 %
868 % \begin{macrocode}
869 %% #1: process's name
870 %% #2: annotation date
871 %% #3: annotation
872 \newcommand{\annotate}[3]{
873 \annotatexplicit{#1}{#2}{#3}{#3}
874 }
875 % \end{macrocode}
876 %
877 % \begin{macrocode}
878 %% Same than annotate, but with the coordinate name provided explicitly
879 %% #1: process's name
880 %% #2: annotation date
881 %% #3: annotation
882 %% #4: coordinate name
883 \newcommand{\annotatexplicit}[4]{
884 \coordinate (#4) at ($ (#1) +(#2, 0.1) $);
885 \draw (#4) node[rotate=\mp@annotaterotation, anchor=south] {#3};
886 }
887 % \end{macrocode}