Improvements thanks to Musard

Author: Aslan Askarov

body.tex

@@ -55,8 +55,9 @@ \subsection{A minimal \troupelang\ program}
 
 \subsection{Overview of the basic language}
 At the very core of \troupelang\ is a dynamically typed functional programming language without mutable references. 
-For example, a Fibonacci function in \troupelang\ is written exactly as in SML sans type annotations. 
+For example, a Fibonacci function in \troupelang\ is written exactly as in SML sans type annotations.
 \begin{lstlisting}
+(* basic_fib.trp *)
 let fun fib x = 
         if x > 2 then fib (x - 1) + fib (x - 2)
                  else 1
@@ -139,6 +140,7 @@ \subsubsection{Function declarations}
 Functions are declared using \textcode{let fun} syntax. Mutually recursive functions 
 are delimited using the \textcode{and} keyword.
 \begin{lstlisting}
+(* basic_evenodd.trp *)
 let fun even x = if x = 0 then true else odd (x - 1)
     and odd x = if x = 0 then false else even (x - 1)
 in even 7
@@ -161,6 +163,7 @@ \subsection{Libraries}
 Troupe has a minimal support for built-in libraries. Current libraries include a library \code{lists} for common list manipulations, library  \code{declassifyutil} for declassification of aggregate data structures, and library
 \code{stdio} with convenient wrappers for standard input and output. To use a library, one needs to import it with an \code{import} statement at the top of the program.
 \begin{lstlisting}
+(* basic_lib.trp *)
 import lists 
 printWithLabels (map ( fn i => i + 1) [1,2,3])
 \end{lstlisting}
@@ -174,6 +177,7 @@ \subsubsection{Spawning processes}
 It return the process identifier of the new process, and starts the new process that from now on runs concurrently with the 
 parent process.
 \begin{lstlisting}
+(* basic_spawn.trp *)
 import lists
 let fun printwait x = let val _ = printWithLabels x in sleep 10 end
     fun foo () = map printwait [1,2,3]
@@ -205,6 +209,7 @@ \subsubsection{Sending and receiving messages}
 
 
 \begin{lstlisting}
+(* basic_receive.trp *)
 let fun foo () =
       receive [hn x => printWithLabels ("foo received", x)]
     val p = spawn foo
@@ -248,6 +253,7 @@ \subsubsection{Example: receive with a timeout}
 The use of the unique string avoids creating a confusion when multiple
 timeouts may be involved.
 \begin{lstlisting}
+(* basic_timeout.trp *)
 let fun timeout p r t = let val _ = sleep t
                         in send (p, r)
                         end
@@ -266,6 +272,8 @@ \subsubsection{Example: updateable service}
 messages with the \textcode{"UPDATE"} string.
 
 \begin{lstlisting}
+(* basic_updateableserver.trp *)
+import timeout
 let fun v_one n =
          receive [ hn ("REQUEST", senderid) => 
                         let val _ = send (senderid, n) 
@@ -293,14 +301,16 @@ \subsubsection{Example: updateable service}
     val _ = send (service, ("UPDATE", v_two))
     val _ = send (service, ("COMPUTE", self(), fn x => x * x, 42))
     val _ = receive [ hn x => print x]
-in ()
+in exitAfterTimeout authority 1000 0 
+		"force terminating the server example after 1s"
 end    
 \end{lstlisting}
 The evaluation of this program results in the output
 \begin{verbatim}
 0@{}%{}
 1764@{}%{}
 main thread finished with value: ()@{}%{}
+force terminating the server example after 1s
 \end{verbatim}
 
 \subsection{Debugging concurrent programs}
@@ -359,6 +369,7 @@ \subsection{Monitoring for information flow}
 \paragraph{Explicit flows}
 The following example shows how to create labeled values and how explicit dependencies are propagated.
 \begin{lstlisting}
+(* ifc_explicit.trp *)
 let val x = 10 raisedTo {alice}
     val y = 20 raisedTo {bob}
 in x + y
@@ -382,6 +393,7 @@ \subsection{Monitoring for information flow}
 Labels in \troupelang\ are first-class:
 
 \begin{lstlisting}
+(* ifc_labels.trp *)
 import lists
 map (fn (x,lev) => x raisedTo lev) [ (1, {alice})
                                    , (2, {bob})
@@ -396,6 +408,7 @@ \subsection{Monitoring for information flow}
 
 
 \begin{lstlisting}
+(* ifc_implicit1.trp *)
 let val x = 10 raisedTo {alice} 
 in if x > 5 then 1 else 0 
 end	
@@ -407,6 +420,10 @@ \subsection{Monitoring for information flow}
 branch that has been chosen here. Because, of the dynamic nature of type checking,
 we also carry the information about the chosen branch into the type label.
 
+
+
+
+
 \paragraph{Implicit flows and I/O}
 The implicit information flows are further propagated between processes. 
 In the mailbox, each message is additionally tagged with a label that 
@@ -416,6 +433,7 @@ \subsection{Monitoring for information flow}
 where the pc-tag set to the provided label argument.
 
 \begin{lstlisting}
+(* ifc_implicit2.trp *)
 let val x = 10 raisedTo {secret}
     val p = self()
     val _ = spawn ( fn () => if x > 0 
@@ -438,6 +456,7 @@ \subsection{Monitoring for information flow}
 $\mathit{pc}~\sqsubseteq~\mathit{block}$. To view the labels there is a 
 helper internal function \code{debugpc ()}.
 \begin{lstlisting}
+(* ifc_debugpc.trp *)
 let val x = 1 raisedTo{secret}
     val _ = debugpc() 
     val x = if x > 2 then receive [] else () 
@@ -494,6 +513,7 @@ \subsubsection{Attenuation}
 Authority can be attenuated using the \code{attenuate} primitive. 
 
 \begin{lstlisting}
+(* ifc_attenuate.trp *)
 attenuate (authority, {alice})    
 \end{lstlisting}
 \begin{verbatim}
@@ -505,13 +525,15 @@ \subsubsection{Basic declassification}
 the expression to declassify, the authority, and the target label. For example, a basic declassification
 looks like this. 
 \begin{lstlisting}
+(* ifc_declassify_atten.trp *)
 let val x = 10 raisedTo {alice}
  in declassify (x , authority, {} )
 end 
 \end{lstlisting}
 
 When authority for declassification is not sufficient, Troupe returns an error message.
 \begin{lstlisting}
+(* ifc_declassify_err.trp *)
 let val authAlice = attenuate (authority, {alice})
     val x = 1 raisedTo {bob}
 in declassify (x, authAlice, {})
@@ -537,6 +559,7 @@ \subsubsection{Declassification of the blocking level}
 levels.
 
 \begin{lstlisting}
+(* ifc_pini.trp *)
 let val x = 10 raisedTo {alice}
     val y = 0
     val z = 
@@ -660,7 +683,6 @@ \subsubsection{Registering and looking up processes}
 the node identity and the name at which a process is bound, we can find the process at that node, using the 
 \code{whereis} primitive:
 
-
 \begin{lstlisting}
 let val echo = 
         whereis ( "QmNRwNZACPciLS14cZFApwrCcAdbRAXYgztea9m5XwRe4z"
@@ -670,6 +692,10 @@ \subsubsection{Registering and looking up processes}
 end    
 \end{lstlisting}
 
+The complete echo example -- including the code above and 
+the scripts for generating the identifiers is available at 
+\code{\$TROUPE/examples/network/echo}.
+
 \subsubsection{Aliases}
 Aliases is a mechanism that allows us to avoid having hardcoded node identifiers in the source code. 
 The alias mechanism operates in the way of the traditional Unix hosts files.
@@ -771,6 +797,24 @@ \subsubsection{\code{declassify}}
 \end{description}
 
 
+\subsubsection{\code{exit}}
+\begin{description}
+    \item [Description] Exits the Troupe runtime.
+    \item [Arguments] A tuple \code{(authority, exitCode)}.
+    \item [Returns] Nothing
+    \item [Example usage] \textcode{exit(authority, 0)}
+\end{description}
+
+
+\subsubsection{\code{getTime}}
+\begin{description}
+    \item [Description] Obtains current Unix timestmap
+    \item [Arguments] Unit.
+    \item [Returns] Number. 
+    \item [Example usage] \textcode{getTime()}
+\end{description}
+
+
 \subsubsection{\code{getTime}}
 \begin{description}
     \item [Description] Obtains current Unix timestmap
@@ -780,6 +824,20 @@ \subsubsection{\code{getTime}}
 \end{description}
 
 
+\subsubsection{\code{inputLine}}
+\begin{description}
+\item[Description] Reads a  line from the console.
+\item[Arguments] Unit.
+\item[Returns] String value.
+\item[Blocking behavior] Synchronous. Observe that the blocking label 
+is raised to top after this operation, because the user providing the 
+input is assumed to operate at level top. To prevent this from happening,
+the blocking label can be declassified using the \code{let\ pini} constructs.
+See also library functions \code{inputLineWithPini} and \code{inputLineWithPini}
+from \code{stdio} library.
+\end{description}
+
+
 \subsubsection{\code{lowermbox}}
 \begin{description}
     \item [Description] Lowers the clearance of the current process' mailbox. 
@@ -797,6 +855,17 @@ \subsubsection{\code{mkuuid}}
     \item [Example usage] \textcode{print (mkuuid\ ())}
 \end{description}
 
+
+\subsubsection{\code{node}}
+\begin{description}
+    \item [Description] Returns node identifier of a process.
+    \item [Arguments] Process identifier.
+    \item [Returns] String containing a node identifier.
+\end{description}
+
+
+
+
 \subsubsection{\code{pinipop}}
 \begin{description}
     \item [Description] Pop an authority value from the \emph{pini} stack, and declassify the current blocking level.
@@ -832,6 +901,30 @@ \subsubsection{\code{printWithLabels}}
     \item [Example usage] \code{printWithLabels\ "Hello, world"}
 \end{description}
 
+
+\subsubsection{\code{raiseTrust}}
+\begin{description}
+    \item [Description] Dynamically raise the trust level of a node.
+    \item [Arguments] A triple of a node identifier, root-level authority, and the intended trust level.
+    \item [Returns] Unit.
+    \item [Failure behavior]. Fails if the argument type is invalid. Fails if the authority argument is not top.
+ Fails if the blocking level is not $\bot$.
+    \item [Example usage] $\code{raiseTrust("@alicescomputer", authority, \{alice\})}$
+\end{description}
+Note that the top-level authority is required because this is a privileged operation with system-wide consequences. 
+
+
+
+
+\subsubsection{\code{raisembox}}
+\begin{description}
+    \item [Description] Raises the clearance of the current process' mailbox. 
+    \item [Arguments] A security level
+    \item [Returns] A capability for lowering the mailbox level back to the previous value. 
+    \item [Failure behavior] Fails if the type of the argument is invalid (dynamic type checking).
+\end{description}
+
+
 \subsubsection{\code{random}}
 \begin{description}
     \item [Description] Generates a random number between 0 (inclusive) and 1.
@@ -842,6 +935,39 @@ \subsubsection{\code{random}}
 
 
 
+
+
+\subsubsection{\code{receive}}
+\begin{description}
+    \item [Description] Picks a message from the mailbox.
+    \item [Arguments] A list of \emph{handler functions} (cf. Section~\ref{sec:handlers}).
+    \item [Returns] The value returned by the body of the matching handler.
+\end{description}
+
+\subsubsection{\code{register}}
+\begin{description}
+    \item [Description] Registers the process under a name.
+    \item [Arguments] A tuple of the form $(\mathit{str}, \mathit{pid}, \mathit{authority})$, where $\mathit{str}$ is the name under
+which the process is to be registered, $\mathit{pid}$ is the process identifier, and 
+$\mathit{authority}$ is the top authority value.
+    \item [Returns] Unit.
+    \item [Blocking behavior] Synchronous. 
+    \item [Failure behavior] Crashes if the provided authority is not top, or if the blocking level is not $\bot$.
+    \item [Example usage]\textcode{register ("auctionServer", self(), authority)}
+\end{description}
+
+Note that this is a privileged operation with system-wide consequences. 
+
+
+\subsubsection{\code{rcv}}
+\begin{description}
+    \item [Description] Picks a message from the mailbox with pre-filtering the levels of the messages.
+    \item [Arguments] A triple of the form $(\mathit{hs}, \ell_{\mathit{lo}}, \ell_{\mathit{hi}}) $ where $\mathit{hs}$ is the list of handlers, $\ell_{\mathit{lo}}$ is the lower bound on the \emph{sender-level} of the messages, and 
+$\ell_{\mathit{hi}}$ is the upper bound on the \emph{sender-level} of the messages in the mailbox.
+    \item [Returns] The value returned by the body of the matching handler.
+\end{description}
+
+
 \subsubsection{\code{sandbox}} 
 \begin{description}
     \item [Description] Execute a function in a sandbox for a fixed duration of time.
@@ -919,70 +1045,6 @@ \subsubsection{\code{raisedTo}}
     \item [Example usage] $\code{42\ raisedTo\ \{alice\}}$
 \end{description}
 
-\subsubsection{\code{raiseTrust}}
-\begin{description}
-    \item [Description] Dynamically raise the trust level of a node.
-    \item [Arguments] A triple of a node identifier, root-level authority, and the intended trust level.
-    \item [Returns] Unit.
-    \item [Failure behavior]. Fails if the argument type is invalid. Fails if the authority argument is not top.
- Fails if the blocking level is not $\bot$.
-    \item [Example usage] $\code{raiseTrust("@alicescomputer", authority, \{alice\})}$
-\end{description}
-Note that the top-level authority is required because this is a privileged operation with system-wide consequences. 
-
-
-
-
-\subsubsection{\code{raisembox}}
-\begin{description}
-    \item [Description] Raises the clearance of the current process' mailbox. 
-    \item [Arguments] A security level
-    \item [Returns] A capability for lowering the mailbox level back to the previous value. 
-    \item [Failure behavior] Fails if the type of the argument is invalid (dynamic type checking).
-\end{description}
-
-
-
-
-\subsubsection{\code{readInput}}
-\begin{description}
-\item[Description] Reads a  line from the console.
-\item[Arguments] Unit.
-\item[Returns] String value.
-\item[Blocking behavior] Synchronous.
-\end{description}
-
-
-
-\subsubsection{\code{receive}}
-\begin{description}
-    \item [Description] Picks a message from the mailbox.
-    \item [Arguments] A list of \emph{handler functions} (cf. Section~\ref{sec:handlers}).
-    \item [Returns] The value returned by the body of the matching handler.
-\end{description}
-
-\subsubsection{\code{register}}
-\begin{description}
-    \item [Description] Registers the process under a name.
-    \item [Arguments] A tuple of the form $(\mathit{str}, \mathit{pid}, \mathit{authority})$, where $\mathit{str}$ is the name under
-which the process is to be registered, $\mathit{pid}$ is the process identifier, and 
-$\mathit{authority}$ is the top authority value.
-    \item [Returns] Unit.
-    \item [Blocking behavior] Synchronous. 
-    \item [Failure behavior] Crashes if the provided authority is not top, or if the blocking level is not $\bot$.
-    \item [Example usage]\textcode{register ("auctionServer", self(), authority)}
-\end{description}
-
-Note that this is a privileged operation with system-wide consequences. 
-
-
-\subsubsection{\code{rcv}}
-\begin{description}
-    \item [Description] Picks a message from the mailbox with pre-filtering the levels of the messages.
-    \item [Arguments] A triple of the form $(\mathit{hs}, \ell_{\mathit{lo}}, \ell_{\mathit{hi}}) $ where $\mathit{hs}$ is the list of handlers, $\ell_{\mathit{lo}}$ is the lower bound on the \emph{sender-level} of the messages, and 
-$\ell_{\mathit{hi}}$ is the upper bound on the \emph{sender-level} of the messages in the mailbox.
-    \item [Returns] The value returned by the body of the matching handler.
-\end{description}
 
 \subsubsection{\code{whereis}}
 

main.tex

@@ -39,7 +39,7 @@
 %\author{}
 % \author{\sf Aslan Askarov \\ \small aslan@cs.au.dk}
 
-\date{March 4, 2020}  % Activate to display a given date or no date
+\date{March 16, 2020}  % Activate to display a given date or no date
 
 \begin{document}
 \maketitle