top/lang.tex

   1 \documentclass[../thesis.tex]{subfiles}
   2
   3 \input{subfilepreamble}
   4
   5 \setcounter{chapter}{4}
   6
   7 \begin{document}
   8 \input{subfileprefix}
   9 \chapter{The mTask language}%
  10 \label{chp:mtask_dsl}
  11 \begin{chapterabstract}
  12         This chapter introduces the \gls{TOP} language \gls{MTASK} by:
  13         \begin{itemize}
  14                 \item introducing class-based shallow embedding and the setup of the \gls{MTASK} language;
  15                 \item describing briefly the various interpretations;
  16                 \item demonstrating how the type system is leveraged to enforce all constraints;
  17                 \item showing the language interface for expressions, datatypes, and functions;
  18                 \item and explaining the tasks, task combinators, and \glspl{SDS}.
  19         \end{itemize}
  20 \end{chapterabstract}
  21
  22 Regular \gls{FP} and \gls{TOP} languages do not run on resource-constrained edge devices.
  23 A \gls{DSL} is therefore used as the basis of the \gls{MTASK} system, a complete \gls{TOP} programming environment for programming microcontrollers.
  24 It is implemented as an \gls{EDSL} in \gls{CLEAN} using class-based---or tagless-final---embedding.
  25 This means that the language interface, i.e.\ the language constructs, are a collection of type classes.
  26 Interpretations of this interface are data types implementing these classes.
  27 Due to the nature of this embedding technique, it is possible to have multiple interpretations for programs written in the \gls{MTASK} language.
  28 Furthermore, this particular type of embedding has the property that it is extensible both in language constructs and in interpretations.
  29 Adding a language construct is as simple as adding a type class.
  30 Adding an interpretation is done by creating a new data type and providing implementations for the various type classes.
  31
  32 In order to reduce the hardware requirements for devices running \gls{MTASK} programs, several measures have been taken.
  33 Programs in \gls{MTASK} are written in the \gls{MTASK} \gls{DSL}, separating them from the host \gls{ITASK} program.
  34 This allows the tasks to be constructed at compile time in order to tailor-make them for the specific work requirements.
  35 Furthermore, the \gls{MTASK} language is restricted: there are no recursive data structures, no higher-order functions, strict evaluation, and functions and objects can only be declared at the top level.
  36
  37 \section{Class-based shallow embedding}
  38 Let us illustrate this technique by taking the very simple language of literal values.
  39 This language interface can be described using a single type constructor class with a single function \cleaninline{lit}.
  40 This function is for lifting values, when it has a \cleaninline{toString} instance, from the host language to our new \gls{DSL}.
  41 The type variable \cleaninline{v} of the type class represents the view on the language, the interpretation.
  42
  43 \begin{lstClean}
  44 class literals v where
  45         lit :: a -> v a | toString a
  46 \end{lstClean}
  47
  48 Providing an evaluator is straightforward as can be seen in the following listing.
  49 The evaluator is just a box holding a value of the computation, but it can also be something more complex such as a monadic computation.
  50
  51 \begin{lstClean}
  52 :: Eval a = Eval a
  53
  54 runEval :: (Eval a) -> a
  55 runEval (Eval a) = a
  56
  57 instance literals Eval where
  58         lit a = Eval a
  59 \end{lstClean}
  60
  61 Extending the language with a printer is done by defining a new data type and providing instances for the type constructor classes.
  62 The printer shown below only stores a printed representation and hence the type variable is just a phantom type:
  63
  64 \begin{lstClean}
  65 :: Printer a = Printer String
  66
  67 runPrinter :: (Printer a) -> String
  68 runPrinter (Printer a) = a
  69
  70 instance literals Printer where
  71         lit a = Printer (toString a)
  72 \end{lstClean}
  73
  74 Adding language constructs happens by defining new type classes and giving implementations for the interpretations.
  75 The following listing adds an addition construct to the language and shows the implementations for the evaluator and printer.
  76
  77 \begin{lstClean}
  78 class addition v where
  79         add :: v a -> v a -> v a | + a
  80
  81 instance addition Eval where
  82         add (Eval l) (Eval r) = Eval (l + r)
  83
  84 instance addition Printer where
  85         add (Printer l) (Printer r) = Printer ("(" +++ l +++ "+" +++ r +++ ")")
  86 \end{lstClean}
  87
  88 Terms in our toy language can be overloaded in their interpretation, they are just an interface.
  89 For example, $1+5$ is written as \cleaninline{add (lit 1) (lit 5)} and has the type \cleaninline{v Int \| literals, addition v}.
  90 However, due to the way let-polymorphism is implemented in most functional languages, it is not always straightforward to use multiple interpretations in one function.
  91 Creating such a function, e.g.\ one that both prints and evaluates an expression, requires rank-2 polymorphism (see \cref{lst:rank2_mtask}).
  92
  93 \section{Types}
  94 The \gls{MTASK} language is a tagless-final \gls{EDSL} as well.
  95 As it is shallowly embedded, the types of the terms in the language can be constrained by type classes.
  96 Types in the \gls{MTASK} language are expressed as types in the host language, to make the language type safe.
  97 However, not all types in the host language are suitable for microcontrollers that may only have \qty{2}{\kibi\byte} of \gls{RAM}, so class constraints are added to the \gls{DSL} functions.
  98 \Cref{tbl:mtask-c-datatypes} shows the mapping from \gls{CLEAN} types to \ccpp{} types.
  99 The most used class constraint is the \cleaninline{type} class collection containing functions for serialisation, printing, \gls{ITASK} constraints, \etc\ \citep[\citesection{6.9}]{plasmeijer_clean_2021}.
 100 Most of these functions are automatically derivable using generic programming but can be specialised when needed.
 101 An even stronger restriction is defined for types that have a stack representation.
 102 This \cleaninline{basicType} class has instances for many \gls{CLEAN} basic types such as \cleaninline{Int}, \cleaninline{Real} and \cleaninline{Bool}.
 103 These class constraints for values in \gls{MTASK} are omnipresent in all functions and therefore usually omitted for brevity and clarity.
 104
 105 \begin{table}[ht]
 106         \centering
 107         \caption{Translation from \cmtask{} data types to \ccpp{} datatypes.}%
 108         \label{tbl:mtask-c-datatypes}
 109         \begin{tabular}{lll}
 110                 \toprule
 111                 \cmtask{}                        & \ccpp{}           & \textnumero{}bits\\
 112                 \midrule
 113                 \cleaninline{Bool}               & \cinline{bool}    & 16\\
 114                 \cleaninline{Char}               & \cinline{char}    & 16\\
 115                 \cleaninline{Int}                & \cinline{int16_t}\footnotemark{} & 16\\
 116                 \cleaninline{Real}               & \cinline{float}   & 32\\
 117                 \cleaninline{:: Long}            & \cinline{int32_t} & 32\\
 118                 \cleaninline{:: T = A \| B \| C} & \cinline{enum}    & 16\\
 119                 \bottomrule
 120         \end{tabular}
 121 \end{table}
 122
 123 \footnotetext{In \gls{ARDUINO} \ccpp{} this usually equals a \cinline{long}.}
 124 \Cref{lst:constraints} contains the definitions for the auxiliary types and type constraints (such as \cleaninline{type} and \cleaninline{basicType}) that are used to construct \gls{MTASK} expressions.
 125
 126 \begin{lstClean}[caption={Classes and class collections for the \gls{MTASK} language.},label={lst:constraints}]
 127 class type t | iTask, ... , fromByteCode, toByteCode t
 128 class basicType t | type t where ...
 129 \end{lstClean}
 130
 131 The \gls{MTASK} language interface consists of a core collection of type classes bundled in the type class \cleaninline{class mtask} (see \cref{lst:collection}).
 132 Every interpretation of \gls{MTASK} terms implements the type classes in the \cleaninline{mtask} class collection.
 133 %Optional \gls{MTASK} constructs such as peripherals or lowered \gls{ITASK} \glspl{SDS} are not included in this class collection because not all devices or interpretations support this.
 134
 135 \begin{lstClean}[caption={Class collection for the \gls{MTASK} language.},label={lst:collection}]
 136 class mtask v | expr, ..., int, real, long v
 137 \end{lstClean}
 138
 139 Peripheral, \gls{SDS}, and function definitions are always defined at the top level of \gls{MTASK} programs.
 140 This is enforced by the \cleaninline{Main} type.
 141 Most top level definitions are defined using \gls{HOAS}.
 142 To make their syntax friendlier, the \cleaninline{In} type---an infix tuple---is used to combine these top level definitions.
 143 To illustrate the structure of a \gls{MTASK} programs, \cref{lst:mtask_types} shows a skeleton of a program.
 144
 145 % VimTeX: SynIgnore on
 146 \begin{lstClean}[caption={Auxiliary types and example task in the \gls{MTASK} language.},label={lst:mtask_types}]
 147 // From the mTask library
 148 :: Main a = { main :: a }
 149 :: In a b = (In) infix 0 a b
 150
 151 someTask :: MTask v Int | mtask v & lowerSds v & sensor1 v & ...
 152 someTask =
 153         sensor1 config1 \sns1->
 154         sensor2 config2 \sns2->
 155            sds      \s1  = initialValue
 156         In lowerSds \s2  = someiTaskSDS
 157         In fun      \fun1= ( \(a0, a1)->... )
 158         In fun      \fun2= ( \a->... )
 159         In { main = mainexpr }
 160 \end{lstClean}
 161 % VimTeX: SynIgnore off
 162
 163 Expressions in the \gls{MTASK} language are usually overloaded in their interpretation (\cleaninline{v}).
 164 In \gls{CLEAN}, all free variables in a type are implicitly universally quantified.
 165 In order to use the \gls{MTASK} expressions with multiple interpretations, rank-2 polymorphism is required \citep{odersky_putting_1996}.
 166 \Cref{lst:rank2_mtask} shows an example of a function that simulates an \gls{MTASK} expression while showing the pretty printed representation in parallel.
 167 Providing a type for the \cleaninline{simulateAndPrint} function is mandatory as the compiler cannot infer the type of rank-2 polymorphic functions\citep[\citesection{3.7.4}]{plasmeijer_clean_2021}.
 168
 169 \begin{lstClean}[label={lst:rank2_mtask},caption={Rank-2 polymorphism to allow multiple interpretations.}]
 170 simulateAndPrint :: (A.v: Main (MTask v a) | mtask v) -> Task a | type a
 171 simulateAndPrint mt =
 172             simulate mt
 173         -|| Hint "Current task:" @>> viewInformation [] (showMain mt)
 174 \end{lstClean}
 175
 176 \section{Expressions}\label{sec:expressions}
 177 This section shows all \gls{MTASK} language constructs for expressions.
 178 \Cref{lst:expressions} shows the \cleaninline{expr} class containing the functionality to:
 179 lift values from the host language to the \gls{MTASK} language (\cleaninline{lit});
 180 perform numeric and boolean arithmetics;
 181 do comparisons;
 182 and perform conditional execution.
 183 For every common boolean and arithmetic operator in the host language, an \gls{MTASK} variant is present.
 184 The operators are suffixed by a period to not clash with the built-in operators in \gls{CLEAN}.
 185
 186 \begin{lstClean}[caption={The \gls{MTASK} class for expressions.},label={lst:expressions}]
 187 class expr v where
 188         lit :: t -> v t | type t
 189         (+.) infixl 6 :: (v t) (v t) -> v t | basicType, +, zero t
 190         ...
 191         (&.) infixr 3 :: (v Bool) (v Bool) -> v Bool
 192         (|.) infixr 2 :: (v Bool) (v Bool) -> v Bool
 193         Not           :: (v Bool) -> v Bool
 194         (==.) infix 4 :: (v a) (v a) -> v Bool | Eq, basicType a
 195         ...
 196         If :: (v Bool) (v t) (v t) -> v t | type t
 197 \end{lstClean}
 198
 199 Conversion to and fro data types is available through the overloaded functions \cleaninline{int}, \cleaninline{long} and \cleaninline{real}.
 200 These functions convert the argument to the respective type similar to casting in \gls{C}.
 201 For most interpretations, there are instances of these classes for all numeric types.
 202
 203 \begin{lstClean}[caption={Type conversion functions in \gls{MTASK}.}]
 204 class int  v a :: (v a) -> v Int
 205 class real v a :: (v a) -> v Real
 206 class long v a :: (v a) -> v Long
 207 \end{lstClean}
 208
 209 Values from the host language must be explicitly lifted to the \gls{MTASK} language using the \cleaninline{lit} function.
 210 For convenience, there are many lower-cased macro definitions for often-used constants such as \cleaninline{true :== lit True}, \cleaninline{false :== lit False}.
 211
 212 \Cref{lst:example_exprs} shows some examples of expressions in the \gls{MTASK} language.
 213 Since they are only expressions, there is no need for a \cleaninline{Main}.
 214 \cleaninline{e0} defines the literal \num{42}, \cleaninline{e1} calculates the literal \num{42.0} using real numbers and uses a type conversion.
 215 \cleaninline{e2} compares \cleaninline{e0} and \cleaninline{e1} as integers and if they are equal it returns $\frac{\text{\cleaninline{e2}}}{2}$ and \cleaninline{e0} otherwise.
 216
 217 \begin{lstClean}[label={lst:example_exprs},caption={Example \gls{MTASK} expressions.}]
 218 e0 :: v Int | expr v
 219 e0 = lit 42
 220
 221 e1 :: v Real | expr v
 222 e1 = lit 38.0 +. real (lit 4)
 223
 224 e2 :: v Int | expr v
 225 e2 = If (e0 ==. int e1)
 226         (int e1 /. lit 2) e0
 227 \end{lstClean}
 228
 229 The \gls{MTASK} language is shallowly embedded in \gls{CLEAN} and the terms are constructed and hence compiled at run time.
 230 This means that \gls{MTASK} programs can also be tailor-made at run time using \gls{CLEAN} functions, maximising the linguistic reuse \citep{krishnamurthi_linguistic_2001}.
 231 The \cleaninline{approxEqual} function in \cref{lst:example_macro} is an example of this.
 232 It performs a simple approximate equality---admittedly not taking into account all floating point peculiarities.
 233 When calling \cleaninline{approxEqual} in an \gls{MTASK} expression, the resulting code is inlined.
 234
 235 \begin{lstClean}[label={lst:example_macro},caption={Approximate equality as an example of linguistic reuse in \gls{MTASK}.}]
 236 approxEqual :: (v Real) (v Real) (v Real) -> v Bool | expr v
 237 approxEqual x y eps = x ==. y |.  If (x >. y)
 238         (x -. y <. eps)
 239         (y -. x <. eps)
 240 \end{lstClean}
 241
 242 \subsection{Data types}
 243 Most of the fixed-size basic types from \gls{CLEAN} are mapped on \gls{MTASK} types (see \cref{tbl:mtask-c-datatypes}).
 244 However, it is useful to have access to compound types as well.
 245 All types in \gls{MTASK} have a fixed-size representation on the stack, so sum types are not (yet) supported.
 246 It is possible to lift any types, e.g.\ tuples, using the \cleaninline{lit} function as long as they have instances for the required type classes.
 247 However, you cannot do anything with values of the types besides passing them around.
 248 To be able to use types as first-class citizens, constructors, and field selectors or deconstructors are required (see \cref{chp:first-class_datatypes}).
 249 \Cref{lst:tuple_exprs} shows the scaffolding required for supporting tuples in \gls{MTASK}.
 250 Besides the constructors and field selectors, there is also a helper function available that transforms a function from a tuple of \gls{MTASK} expressions to an \gls{MTASK} expression of a tuple, a deconstructor.
 251 Examples of \gls{MTASK} programs using tuples are seen later in \cref{sec:mtask_functions}.
 252
 253 \begin{lstClean}[label={lst:tuple_exprs},caption={Tuple constructor and field selectors in \gls{MTASK}.}]
 254 class tupl v where
 255         tupl :: (v a) (v b) -> v (a, b) | type a & type b
 256         first :: (v (a, b)) -> v a | type a & type b
 257         second :: (v (a, b)) -> v b | type a & type b
 258
 259         tupopen :: ((v a, v b) -> v c) -> ((v (a, b)) -> v c)
 260         tupopen f :== \v->f (first v, second v)
 261 \end{lstClean}
 262
 263 \subsection{Functions}\label{sec:mtask_functions}
 264 Adding functions to the language is achieved by one type class to the \gls{DSL}.
 265 By using \gls{HOAS}, both the function definition and the calls to the function can be controlled by the \gls{DSL} \citep{pfenning_higher-order_1988,chlipala_parametric_2008}.
 266 The \gls{MTASK} language only allows first-order functions and no partial function application.
 267 To restrict this, a multi-parameter type class is used instead of a type class with one type variable.
 268 The first parameter represents the shape of the arguments, the second parameter the interpretation.
 269 An instance is provided for each function arity instead of providing an instance for all possible arities to enforce that all functions are first order.
 270 By using argument tuples to represent the arity of the function, partial function applications are eradicated.
 271 The definition of the type class and some instances for the pretty printer are as follows:
 272
 273 \begin{lstClean}[caption={Functions in \gls{MTASK}.}]
 274 class fun a v :: ((a -> v s) -> In (a -> v s) (Main (MTask v u)))
 275         -> Main (MTask v u)
 276
 277 instance fun () Show where ...
 278 instance fun (Show a) Show | type a where ...
 279 instance fun (Show a, Show b) Show | type a, type b where ...
 280 instance fun (Show a, Show b, Show c) Show | type a, ... where ...
 281 ...
 282 \end{lstClean}
 283
 284 Deriving how to define and use functions from the type is quite a challenge even though the resulting syntax is made easier using the infix type \cleaninline{In}.
 285 \Cref{lst:function_examples} show some examples of functions to illustrate the syntax.
 286 Splitting out the function definition for each single arity means that for every function arity and combination of arguments, a separate class constraint must be created.
 287 Many of the often used functions are already bundled in the \cleaninline{mtask} class constraint collection.
 288 The \cleaninline{factorial} functions shows a recursive version of the factorial function.
 289 The \cleaninline{factorialtail} function is a tail-call optimised version of the factorial function.
 290 It also illustrates a manually added class constraint, as they are required when functions are used that have signatures not present in the \cleaninline{mtask} class collection.
 291 Zero-arity functions are always called with unit as an argument.
 292 An illustration of this is seen in the \cleaninline{zeroarity} expression.
 293 Finally, \cleaninline{swapTuple} shows an example of a tuple being swapped.
 294
 295 % VimTeX: SynIgnore on
 296 \begin{lstClean}[label={lst:function_examples},caption={Examples of various functions in \gls{MTASK}.}]
 297 factorial :: Main (v Int) | mtask v
 298 factorial =
 299         fun \fac=(\i->If (i <. lit 1)
 300                 (lit 1)
 301                 (i *. fac (i -. lit 1)))
 302         In {main = fac (lit 5) }
 303
 304 factorialtail :: Main (v Int) | mtask v & fun (v Int, v Int) v
 305 factorialtail =
 306            fun \facacc=(\(acc, i)->If (i <. lit 1)
 307                         acc
 308                         (fac (acc *. i, i -. lit 1)))
 309         In fun \fac=(\i->facacc (lit 1, i))
 310         In {main = fac (lit 5) }
 311
 312 zeroarity :: Main (v Int) | mtask v
 313 zeroarity =
 314            fun \fourtytwo=(\()->lit 42)
 315         In fun \add=(\(x, y)->x +. y)
 316         In {main = add (fourtytwo (), lit 9)}
 317
 318 swapTuple :: Main (v (Int, Bool)) | mtask v
 319 swapTuple =
 320            fun \swap=(tupopen \(x, y)->tupl y x)
 321         In {main = swap (tupl true (lit 42)) }
 322 \end{lstClean}
 323 % VimTeX: SynIgnore off
 324
 325 \section{Tasks and task combinators}\label{sec:top}
 326 This section describes the task language of \gls{MTASK}.
 327 \Gls{TOP} languages are programming languages enriched with tasks.
 328 Tasks represent abstract pieces of work and can be combined using combinators.
 329 Creating tasks is done by evaluating expressions.
 330 The result of an evaluated task expression is called a task tree, a run time representation of a task.
 331 In order to evaluate a task, the resulting task tree is \emph{rewritten}, i.e.\ similar to rewrite systems, they perform a bit of work, step by step.
 332 With each step, a task value is yielded that is observable by other tasks and can be acted upon.
 333
 334 The implementation in the \gls{MTASK} \gls{RTS} for task execution is shown in \cref{chp:implementation}.
 335 The following sections show the definitions of the functions for creating tasks.
 336 They also show the semantics of tasks: their observable value in relation to the work that the task represents.
 337 The task language of \gls{MTASK} is divided into three categories:
 338
 339 \begin{description}
 340         \item [Basic tasks] are the leaves in the task trees.
 341                 In most \gls{TOP} systems, the basic tasks are called editors, modelling the interactivity with the user.
 342                 In \gls{MTASK}, there are no editors in that sense.
 343                 Editors in \gls{MTASK} model the interaction with the outside world through peripherals such as sensors and actuators.
 344         \item [Task combinators] provide a way of describing the workflow or collaboration.
 345                 They combine one or more tasks into a compound task.
 346         \item [\Glspl{SDS}] are typed references to shared memory in \gls{MTASK}.
 347                 The data is available for tasks using many-to-many communication but only from within the task language to ensure atomicity.
 348 \end{description}
 349
 350 As \gls{MTASK} is integrated with \gls{ITASK}, a stability distinction is made for task values just as in \gls{ITASK}.
 351 A task in \gls{MTASK} is denoted by the \gls{DSL} type synonym shown in \cref{lst:task_type}.
 352 A task is an expression of the type \cleaninline{TaskValue a} in interpretation \cleaninline{v}.
 353
 354 \begin{lstClean}[label={lst:task_type},caption={Task type in \gls{MTASK}.}]
 355 :: MTask v a :== v (TaskValue a)
 356
 357 // From the iTask library
 358 :: TaskValue a
 359         = NoValue
 360         | Value a Bool
 361 \end{lstClean}
 362
 363 \subsection{Basic tasks}
 364 The \gls{MTASK} language contains interactive and non-interactive basic tasks.
 365 As \gls{MTASK} is integrated in \gls{ITASK}, the same notion of stability is applied to the task values.
 366 Task values have either \emph{no value}, or are \emph{unstable} or \emph{stable} (see \cref{fig:taskvalue}).
 367 Once a task yields a stable value, it does not change anymore.
 368 The most rudimentary non-interactive basic tasks in the task language of \gls{MTASK} are \cleaninline{rtrn} and \cleaninline{unstable}.
 369 They lift the value from the \gls{MTASK} expression language to the task domain either as a stable or unstable value.
 370 There is also a special type of basic task for delaying execution.
 371 The \cleaninline{delay} task---parametrised by a number of milliseconds---yields an unstable value while the time has not passed.
 372 Once the specified time has passed, the time it overshot the planned time is yielded as a stable task value.
 373 See \cref{sec:repeat} for an example task using \cleaninline{delay}.
 374
 375 \begin{lstClean}[label={lst:basic_tasks},caption={Non-interactive basic tasks in \gls{MTASK}.}]
 376 class rtrn v :: (v t) -> MTask v t
 377 class unstable v :: (v t) -> MTask v t
 378 class delay v :: (v n) -> MTask v n | long v n
 379 \end{lstClean}
 380
 381 \subsubsection{Peripherals}\label{sssec:peripherals}
 382 In order for the edge device to interact with the environment, peripherals such as sensors and actuators are employed.
 383 Some peripherals are available on the microcontroller package, others are connected with wires using protocols such as \gls{I2C}.
 384 For every supported sensor or actuator, basic tasks are available that allow interaction with the specific peripheral.
 385 The type classes for these tasks are not included in the \cleaninline{mtask} class collection as not all devices nor all language interpretations support every peripheral connected.
 386
 387 An example of a built-in peripheral is the \gls{GPIO} system.
 388 This array of digital and analogue pins is controlled through software.
 389 \Gls{GPIO} access is divided into three classes: analogue \gls{IO}, digital \gls{IO} and pin mode configuration (see \cref{lst:gpio}).
 390 For all pins and pin modes, an \gls{ADT} is available that enumerates the pins.
 391 The analogue \gls{GPIO} pins of a microcontroller are connected to an \gls{ADC} that translates the measured voltage to an integer.
 392 Digital \gls{GPIO} pins of a microcontroller report either a high or a low value.
 393 Both analogue and digital \gls{GPIO} pins can be read or written to, but it is advised to set the pin mode accordingly.
 394 The \cleaninline{pin} type class allows functions to be overloaded in either the analogue or digital pins, e.g.\ analogue pins can be considered digital pins as well.
 395
 396 For digital \gls{GPIO} interaction, the \cleaninline{dio} type class is used.
 397 The first argument of the functions in this class is overloaded, i.e.\ it accepts either an \cleaninline{APin} or a \cleaninline{DPin}.
 398 Analogue \gls{GPIO} tasks are bundled in the \cleaninline{aio} type class.
 399 \Gls{GPIO} pins usually operate according to a certain pin mode that states whether the pin acts as an input pin, an input with an internal pull-up resistor or an output pin.
 400 This setting can be set using the \cleaninline{pinMode} class by hand or by using the \cleaninline{declarePin} \gls{GPIO} pin constructor to declare it at the top level.
 401 Setting the pin mode is a task that immediately finishes and yields a stable unit value.
 402 Writing to a pin is also a task that immediately finishes, but yields the written value.
 403 Reading a pin is a task that yields an unstable value---i.e.\ the value read from the actual pin.
 404
 405 \begin{lstClean}[label={lst:gpio},caption={The \gls{MTASK} interface for \gls{GPIO} access.}]
 406 :: APin = A0 | A1 | A2 | A3 | A4 | A5
 407 :: DPin = D0 | D1 | D2 | D3 | D4 | D5 | D6 | D7 | D8 | D9 | D10 | ...
 408 :: PinMode = PMInput | PMOutput | PMInputPullup
 409 :: Pin = AnalogPin APin | DigitalPin DPin
 410
 411 class pin p :: p -> Pin
 412 instance pin APin, DPin
 413
 414 class aio v where
 415         writeA :: (v APin) (v Int) -> MTask v Int
 416         readA :: (v APin) -> MTask v Int
 417
 418 class dio p v | pin p where
 419         writeD :: (v p) (v Bool) -> MTask v Bool
 420         readD :: (v p) -> MTask v Bool | pin p
 421
 422 class pinMode v where
 423         pinMode :: (v PinMode) (v p) -> MTask v () | pin p
 424         declarePin :: p PinMode ((v p) -> Main (v a)) -> Main (v a) | pin p
 425 \end{lstClean}
 426
 427 \Cref{lst:gpio_examples} shows two examples of \gls{MTASK} tasks using \gls{GPIO} pins.
 428 \cleaninline{task1} reads analogue \gls{GPIO} pin 3.
 429 This is a task that never terminates.
 430 \cleaninline{task2} writes the \cleaninline{true} (\gls{ARDUINO} \arduinoinline{HIGH}) value to digital \gls{GPIO} pin 3.
 431 This task finishes immediately after writing to the pin.
 432
 433 \begin{lstClean}[label={lst:gpio_examples},caption={\Gls{GPIO} example in \gls{MTASK}.}]
 434 task1 :: MTask v Int | mtask v
 435 task1 = declarePin A3 PMInput \a3->{main=readA a3}
 436
 437 task2 :: MTask v Int | mtask v
 438 task2 = declarePin D3 PMOutput \d3->{main=writeD d3 true}
 439 \end{lstClean}
 440
 441 Peripherals are bundled by their functionality in \gls{MTASK}.
 442 For example, \cref{lst:dht} shows the type classes for all supported \gls{DHT} sensors.
 443 Currently, two different types of \gls{DHT} sensors are supported, the \emph{DHT} family of sensors connect through the \gls{ONEWIRE} protocol and the \emph{SHT} family of sensors connected using the \gls{I2C} protocol.
 444 Creating such a \cleaninline{DHT} object is very similar to creating functions in \gls{MTASK} and uses \gls{HOAS} to make it type safe.
 445 When provided a configuration and a configuration function, the \gls{DHT} object can be brought into scope.
 446 For the \gls{DHT} sensor there are two basic tasks, \cleaninline{temperature} and \cleaninline{humidity}, that produce a task that yields the observed temperature in \unit{\celcius} or the relative humidity as an unstable value.
 447 Other peripherals have similar interfaces, they are available in \cref{sec:aux_peripherals}.
 448
 449 \begin{lstClean}[label={lst:dht},caption={The \gls{MTASK} interface for \glspl{DHT} sensors.}]
 450 :: DHT //abstract
 451 :: DHTInfo
 452         = DHT_DHT Pin DHTtype
 453         | DHT_SHT I2CAddr
 454 :: DHTtype = DHT11 | DHT21 | DHT22
 455 class dht v where
 456         DHT :: DHTInfo ((v DHT) -> Main (v b)) -> Main (v b) | type b
 457         temperature :: (v DHT) -> MTask v Real
 458         humidity :: (v DHT) -> MTask v Real
 459
 460 measureTemp :: Main (MTask v Real) | mtask, dht v
 461 measureTemp = DHT (DHT_SHT (i2c 0x36)) \dht->{main=temperature dht}
 462 \end{lstClean}
 463
 464 \subsection{Task combinators}
 465 Task combinators are used to combine multiple tasks to describe workflows.
 466 The \gls{MTASK} language has a set of simpler combinators from which more complicated workflow can be derived.
 467 There are three main types of task combinators, namely:
 468 \begin{itemize}
 469         \item sequential combinators that execute tasks one after the other, possibly using the result of the left-hand side;
 470         \item parallel combinators that execute tasks at the same time, combining the result;
 471         \item miscellaneous combinators that change the semantics of a task---for example a combinator that repeats the child task.
 472 \end{itemize}
 473
 474 \subsubsection{Sequential}
 475 Sequential task combination allows the right-hand side expression to \emph{observe} the left-hand side task value.
 476 All sequential task combinators are defined in the \cleaninline{step} class and are by default defined in terms of the Swiss Army knife step combinator (\cleaninline{>>*.}, \cref{lst:mtask_sequential}).
 477 This combinator has a single task on the left-hand side and a list of \emph{task continuations} on the right-hand side.
 478 Every rewrite step, the list of task continuations are tested on the task value.
 479 If one of the predicates matches, the task continues with the result of these continuations.
 480 Several shorthand combinators are derived from the step combinator.
 481 \cleaninline{>>=.} is a shorthand for the bind operation, if the left-hand side is stable, the right-hand side function is called to produce a new task.
 482 \cleaninline{>>\|.} is a shorthand for the sequence operation, if the left-hand side is stable, it continues with the right-hand side task.
 483 The \cleaninline{>>~.} and \cleaninline{>>..} combinators are variants of the ones above that ignore the stability and continue on an unstable value as well.
 484
 485 \begin{lstClean}[label={lst:mtask_sequential},caption={Sequential task combinators in \gls{MTASK}.}]
 486 class step v | expr v where
 487         (>>*.) infixl 1 :: (MTask v t) [Step v t u] -> MTask v u
 488         (>>=.) infixl 0 :: (MTask v t) ((v t) -> MTask v u) -> MTask v u
 489         (>>|.) infixl 0 :: (MTask v t)          (MTask v u) -> MTask v u
 490         (>>~.) infixl 0 :: (MTask v t) ((v t) -> MTask v u) -> MTask v u
 491         (>>..) infixl 0 :: (MTask v t)          (MTask v u) -> MTask v u
 492
 493 :: Step v t u
 494         = IfValue    ((v t) -> v Bool) ((v t) -> MTask v u)
 495         | IfStable   ((v t) -> v Bool) ((v t) -> MTask v u)
 496         | IfUnstable ((v t) -> v Bool) ((v t) -> MTask v u)
 497         | Always                                (MTask v u)
 498 \end{lstClean}
 499
 500 The following listing shows an example of a step in action.
 501 The \cleaninline{readPinBin} function produces an \gls{MTASK} task that classifies the value of an analogue pin into four bins.
 502 It also shows that the nature of embedding allows the host language to be used as a macro language.
 503
 504 \begin{lstClean}[label={lst:mtask_readpinbin},caption={Read an analogue pin and bin the value in \gls{MTASK}.}]
 505 readPinBin :: Int -> Main (MTask v Int) | mtask v
 506 readPinBin lim = declarePin PMInput A2 \a2->
 507         { main = readA a2 >>*.
 508                 [  IfValue (\x->x <. lim) (\_->rtrn (lit bin))
 509                 \\ lim <- [64,128,192,256]
 510                 &  bin <- [0..]]}
 511 \end{lstClean}
 512
 513 \subsubsection{Parallel}\label{sssec:combinators_parallel}
 514 The result of a parallel task combination is a compound task that executes both tasks at the same time.
 515 There are two types of parallel task combinators in the \gls{MTASK} language (see \cref{lst:mtask_parallel}).
 516
 517 \begin{lstClean}[label={lst:mtask_parallel},caption={Parallel task combinators in \gls{MTASK}.}]
 518 class (.&&.) infixr 4 v :: (MTask v a) (MTask v b) -> MTask v (a, b)
 519 class (.||.) infixr 3 v :: (MTask v a) (MTask v a) -> MTask v a
 520 \end{lstClean}
 521
 522 The conjunction combinator (\cleaninline{.&&.}) combines the result by putting the values from both sides in a tuple.
 523 The stability of the task depends on the stability of both children.
 524 If both children are stable, the result is stable, otherwise the result is unstable.
 525 The disjunction combinator (\cleaninline{.\|\|.}) combines the results by picking the leftmost, most stable task.
 526 The semantics of both parallel combinators are most easily described using the \gls{CLEAN} functions shown in \cref{lst:semantics_con,lst:semantics_dis}.
 527
 528 \begin{figure}[ht]
 529         \centering
 530         \begin{subfigure}[t]{.5\textwidth}
 531                 \begin{lstClean}[caption={Semantics of the\\conjunction combinator.},label={lst:semantics_con}]
 532 con :: (TaskValue a) (TaskValue b)
 533         -> TaskValue (a, b)
 534 con NoValue r = NoValue
 535 con l NoValue = NoValue
 536 con (Value l ls) (Value r rs)
 537         = Value (l, r) (ls && rs)
 538
 539                 \end{lstClean}
 540         \end{subfigure}%
 541         \begin{subfigure}[t]{.5\textwidth}
 542                 \begin{lstClean}[caption={Semantics of the\\disjunction combinator.},label={lst:semantics_dis}]
 543 dis :: (TaskValue a) (TaskValue a)
 544         -> TaskValue a
 545 dis NoValue r = r
 546 dis l NoValue = l
 547 dis (Value l ls) (Value r rs)
 548         | rs && not ls = Value r rs
 549         | otherwise = Value l ls
 550                 \end{lstClean}
 551         \end{subfigure}
 552 \end{figure}
 553
 554 \Cref{lst:mtask_parallel_example} gives an example program that uses the parallel task combinator.
 555 This task read two pins at the same time, returning when one of the pins becomes high.
 556 If the combinator was the \cleaninline{.&&.}, the type would be \cleaninline{MTask v (Bool, Bool)} and the task would only return when both pins are high but not necessarily at the same time.
 557
 558 \begin{lstClean}[label={lst:mtask_parallel_example},caption={Parallel task combinator example in \gls{MTASK}.}]
 559 task :: MTask v Bool
 560 task =
 561         declarePin D0 PMInput \d0->
 562         declarePin D1 PMInput \d1->
 563         let monitor pin = readD pin >>*. [IfValue id rtrn]
 564         In {main = monitor d0 .||. monitor d1}
 565 \end{lstClean}
 566
 567 \subsubsection{Repeat}\label{sec:repeat}
 568 In many workflows, tasks are to be executed repeatedly.
 569 The \cleaninline{rpeat} combinator does this by executing the child task until it becomes stable.
 570 Once a stable value is observed, the task is reinstated.
 571 The functionality of \cleaninline{rpeat} can also be simulated by using functions and sequential task combinators and even made to be stateful as can be seen from the blink example from \cref{chp:top4iot}.
 572
 573 \begin{lstClean}[label={lst:mtask_repeat},caption={Repeat task combinators in \gls{MTASK}.}]
 574 class rpeat v where
 575         rpeat :: (MTask v a) -> MTask v a
 576 \end{lstClean}
 577
 578 \Cref{lst:mtask_repeat_example} shows an example of a task that uses the \cleaninline{rpeat} combinator.
 579 This resulting task mirrors the value read from analogue \gls{GPIO} pin \cleaninline{A1} to pin \cleaninline{A2} by constantly reading the pin and writing the result.
 580
 581 \begin{lstClean}[label={lst:mtask_repeat_example},caption={Repeat task combinator example in \gls{MTASK}.}]
 582 task :: MTask v Int | mtask v
 583 task = declarePin A1 PMInput  \a1->
 584        declarePin A2 PMOutput \a2->
 585        {main = rpeat (readA a1 >>~. writeA a2 >>|. delay (lit 1000))}
 586 \end{lstClean}
 587
 588 \subsection{Shared data sources}
 589 For some collaborations it is cumbersome to only communicate data using task values.
 590 \Glspl{SDS} are a safe abstraction over any data that fill this gap.
 591 It allows tasks to safely and atomically read, write and update data stores in order to share data with other tasks.
 592 \Glspl{SDS} in \gls{MTASK} are by default references to shared memory but can also be references to \glspl{SDS} in \gls{ITASK} (see \cref{sec:liftsds}).
 593 There are no combinators or user-defined \gls{SDS} types in \gls{MTASK} as there are in \gls{ITASK}.
 594 Similar to peripherals and functions, \glspl{SDS} are defined at the top level with the \cleaninline{sds} function.
 595 They are accessed through interaction tasks.
 596 The \cleaninline{getSds} task yields the current value of the \gls{SDS} as an unstable value.
 597 This behaviour is similar to the \cleaninline{watch} task in \gls{ITASK}.
 598 Writing a new value to \pgls{SDS} is done using \cleaninline{setSds}.
 599 This task yields the written value as a stable result after it is done writing.
 600 Getting and immediately setting \pgls{SDS} is not necessarily an \emph{atomic} operation in \gls{MTASK} because it is possible that another task accesses the \gls{SDS} in between.
 601 To circumvent this issue, \cleaninline{updSds} is available by which \pgls{SDS} can be atomically updated.
 602 The \cleaninline{updSds} task only guarantees atomicity within \gls{MTASK}.
 603
 604 \begin{lstClean}[label={lst:mtask_sds},caption={\Glspl{SDS} in \gls{MTASK}.}]
 605 :: Sds a // abstract
 606 class sds v where
 607         sds :: ((v (Sds t)) -> In t (Main (MTask v u))) -> Main (MTask v u)
 608         getSds :: (v (Sds t))                -> MTask v t
 609         setSds :: (v (Sds t))  (v t)         -> MTask v t
 610         updSds :: (v (Sds t)) ((v t) -> v t) -> MTask v t
 611 \end{lstClean}
 612
 613 \Cref{lst:mtask_sds_examples} shows an example task that uses \glspl{SDS}.
 614 The \cleaninline{count} function takes a pin and returns a task that counts the number of times the pin is observed as high by incrementing the \cleaninline{share} \gls{SDS}.
 615 In the \cleaninline{main} expression, this function is called twice with a different argument.
 616 The results are combined using the parallel disjunction combinator (\cleaninline{.\|\|.}).
 617 Using a sequence of \cleaninline{getSds} and \cleaninline{setSds} would be unsafe here because the other branch might write their old increment value immediately after writing, effectively missing a count.
 618
 619 \begin{lstClean}[label={lst:mtask_sds_examples},caption={Examples with \glspl{SDS} in \gls{MTASK}.}]
 620 task :: MTask v Int | mtask v
 621 task =
 622         declarePin D3 PMInput \d3->
 623         declarePin D5 PMInput \d5->
 624            sds \share=0
 625         In fun \count=(\pin->
 626                     readD pin
 627                 >>* [IfValue id (\_->updSds (\x->x +. lit 1) share)]
 628                 >>| delay (lit 100) // debounce
 629                 >>| count pin)
 630         In {main=count d3 .||. count d5}
 631 \end{lstClean}
 632
 633 \section{Interpretations}
 634 The nature of the \gls{MTASK} \gls{DSL} embedding allows for multiple interpretations of the terms in the language.
 635 The \gls{MTASK} language has interpretations to pretty print, simulate, and generate byte code for terms in the language.
 636 There are many other interpretations possible such as static analyses or optimisation.
 637 Not all these interpretations are necessarily \gls{TOP} engines, i.e.\ not all the interpretations execute the resulting tasks.
 638
 639 \subsection{Pretty printer}
 640 The pretty printer interpretation converts an \gls{MTASK} term to a string representation.
 641 As the host language \gls{CLEAN} constructs the \gls{MTASK} expressions at run time, it can be useful to show the constructed expression at run time as well.
 642 The only function exposed for this interpretation is the \cleaninline{showMain} function (\cref{lst:showmain}).
 643 It runs the pretty printer and returns a list of strings containing the pretty printed result.
 644 The pretty printing function does the best it can but obviously cannot reproduce layout, curried functions, and variable names.
 645 This shortcoming is illustrated by printing a blink task that contains a function and currying in \cref{lst:showexample}.
 646
 647 \begin{lstClean}[caption={The entry point for the pretty printing interpretation.},label={lst:showmain}]
 648 :: Show a // from the mTask pretty printing library
 649 showMain :: (Main (Show a)) -> [String]
 650 \end{lstClean}
 651
 652 \begin{lstClean}[caption={Pretty printing interpretation example.},label={lst:showexample}]
 653 blinkTask :: Main (MTask v Bool) | mtask v
 654 blinkTask =
 655         fun \blink=(\state->
 656                 writeD d13 state >>|. delay (lit 500) >>=. blink o Not
 657         ) In {main = blink true}
 658
 659 // output when printing:
 660 // fun f0 a1 = writeD(D13, a1) >>= \a2.(delay 1000)
 661 //     >>| (f0 (Not a1)) in (f0 True)
 662 \end{lstClean}
 663
 664 \subsection{Simulator}
 665 In a real microprocessor, it is hard to observe the state and to control the sensors in such a way that the behaviour of interest can be observed.
 666 The simulator converts the expression to a ready-for-work \gls{ITASK} simulation to bridge this gap.
 667 There is one entry point for this interpretation (see \cref{lst:simulatemain}).
 668 The task resulting from the \cleaninline{simulate} function presents the user with an interactive simulation environment (see \cref{fig:sim}).
 669 The simulation allows the user to (partially) execute tasks, control the simulated peripherals, inspect the internal state of the tasks, and interact with \glspl{SDS}.
 670
 671 \begin{lstClean}[caption={The entry point for the simulation interpretation.},label={lst:simulatemain}]
 672 :: TraceTask a // from the mTask simulator library
 673 simulate :: (Main (TraceTask a)) -> [String]
 674 \end{lstClean}
 675
 676 \begin{figure}
 677         \centering
 678         \includegraphics[width=\linewidth]{simg}
 679         \caption{Simulator interface for a blink program written in \gls{MTASK}.}\label{fig:sim}
 680 \end{figure}
 681
 682 \subsection{Byte code compiler}
 683 The main interpretation of the \gls{MTASK} system is the byte code compiler (\cleaninline{:: BCInterpret a}).
 684 This interpretation compiles the \gls{MTASK} term at run time to byte code.
 685 With it, and a handful of integration functions, \gls{MTASK} tasks can be executed on microcontrollers and integrated in \gls{ITASK} as if they were regular \gls{ITASK} tasks.
 686 Furthermore, with a special language construct, \glspl{SDS} can be shared between \gls{MTASK} and \gls{ITASK} programs as well.
 687 The integration with \gls{ITASK} is explained thoroughly later in \cref{chp:integration_with_itask}.
 688
 689 The \gls{MTASK} language together with \gls{ITASK} is a heterogeneous \gls{DSL}.
 690 I.e.\ some components---for example the \gls{RTS} on the microcontroller that executes the tasks---is largely unaware of the other components in the system, and it is executed on a completely different architecture.
 691 The \gls{MTASK} language is a \gls{TOP} language with basic tasks tailored for \gls{IOT} edge devices (see \cref{sec:top}).
 692 It uses expressions based a simply-typed $\lambda$-calculus with support for some basic types, arithmetic operations, and function definitions.
 693
 694 \section{Conclusion}
 695 This chapter gave an overview of the complete \gls{MTASK} \gls{DSL}.
 696 The \gls{MTASK} language is a rich \gls{TOP} language tailored for \gls{IOT} edge devices.
 697 The language is implemented as a class-based shallowly \gls{EDSL} in the pure functional host language \gls{CLEAN}.
 698 The language is an enriched lambda calculus as a host language.
 699 It provides language constructs for arithmetic expressions, conditionals, functions, but also non-interactive basic tasks, task combinators, peripheral support, and integration with \gls{ITASK}.
 700 Terms in the language are just interfaces and can be interpreted by one or more interpretations.
 701 When using the byte code compiler, terms in the \gls{MTASK} language are type checked at compile time but are constructed and compiled at run time.
 702 This facilitates tailor-making tasks for the current work requirements.
 703
 704 \input{subfilepostamble}
 705 \end{document}