ABS Documentation

The ABS language is an actor-based, object-oriented, executable modeling language. Its prime features are:

User-defined data types are used for data modeling instead of objects, so ABS models are typically smaller than their Java counterparts.

As mentioned, ABS method calls are asynchronous and create a new process in the target, while the caller process continues to run in parallel, as shown in Figure Process call semantics. At point ①, P1 issues an asynchronous call to some object residing on another cog. In response, a new process P2 is created; P1 and P2 can run in parallel. At point ②, P1 needs the result of the method call and suspends itself. At point ③, P2 finishes and returns a value. P1’s cog then reactivates P1 to continue execution.

The paragraph above elides some details. An asynchronous method call (see Asynchronous Method Calls) produces a future variable, which is used both to synchronize with the callee process (see Await (Statement)) and to get the result (see Get). Future variables are first-class objects that can be passed along, so multiple processes can synchronize on the same future.

The processes created by method calls are scheduled cooperatively and run within the scope of the target object. Objects are grouped into COGs (Concurrent Object Groups). Each cog runs one process at a time, while processes on different cogs run in parallel, as shown in Figure Processes running inside their cogs. This means that each cog is a unit of concurrency and is in charge of scheduling the processes running on its objects. Each process runs until it suspends itself (see Await (Statement) and Unconditional Release: Suspend) or terminates, at which point the cog chooses the next process to run.

A new cog is created by creating an object with a new expression (see Figure Creating an object in a new cog).

An object in an existing cog is created via the new local expression (see Figure Creating an object in the same cog).

ABS models exceptional (unforeseen and erroneous) situations using exceptions. This section gives an overview of the language constructs that deal with exception propagation and recovery.

Exceptions occur when a process cannot continue normal execution, e.g., when trying to divide by zero or when no pattern in a case expression matches the given value. Exceptions can also be thrown by the modeler via the throw statement: Throw. Exceptions thrown implicitly or explicitly are propagated and handled in the same way.

The modeler can define new exceptions; see Exceptions.

Exceptions can be caught and handled locally, i.e., in a lexically enclosing try-catch-finally block in the same method (see Handling Exceptions with Try-Catch-Finally). In that case, the process continues execution and will eventually produce a return value to its future.

In case of an unhandled exception, the future of the process does not receive a return value; instead, it will propagate the unhandled exception to the caller (or any process that tries to get its value). When evaluating f.get on a future that carries an exception instead of a normal return value, the exception will be re-thrown; it can be handled as usual via try-catch or left to propagate up the call chain of futures.

Additionally, terminating a process in the middle of execution might leave its object in an inconsistent state. To recover from this, ABS uses recovery blocks (see Classes). Unhandled exceptions are handed to the recovery block, which can take appropriate action to re-establish the class invariant and/or send asynchronous messages to other objects.

Line terminators and white spaces are defined as in Java.

ABS supports the two common Java-style styles of comments: end-of-line comments and block comments.

An end-of-line comment starts with two slashes, e.g., // text. All text that follows // until the end of the line is treated as a comment.

A block comment is enclosed in /* */, e.g., /* this is a comment */. Block comments can span multiple lines and do not nest.

Identifiers consist of a letter followed by a sequence of letters, numbers and underscores (_).

ABS distinguishes identifiers and type identifiers. Identifiers start with a lower-case character, type identifiers start with an upper-case character. Identifiers name local variables, fields, methods and functions. Type identifiers name interfaces, classes, types, type constructors, deltas and products.

Identifiers can be qualified with a module name (see Modules) or simple (without module name prefix).

The following words are keywords in the ABS language and are invalid as identifiers.

A literal is a textual representation of a value. ABS supports integer literals, floating-point literals, string literals, and the null literal. Rational numbers are written using the division operator /, e.g., 1/4 for one quarter.

Strings are enclosed in double quotes ("). Line feed in a string is written as \n, carriage return as \r.

The null literal is written as null.

Valid string characters are defined as in the Java language.

Annotations consist of a syntactically valid pure expression, optionally preceded by a type identifier (the “tag”) and a colon (:). They can be put in front of statements and definitions. Annotations are enclosed in square brackets ([]).

There can be more than one annotation in one place. When annotating a place with more than one annotation, writing the annotations in separate pairs of brackets or separated by commas in one pair of brackets produces the same effect.

Annotations are used to write auxiliary information that can be used by various tools. Unknown (user-defined) annotations are ignored by the tool chain. Pre-defined annotations are usually type-checked.

This is an example of annotations with a tag:

The same annotations, written in separate brackets:

Annotations are associated with the following language construct. In the examples above, the first annotation pertains to the class definition of Example, the second annotation pertains to the asynchronous method call o!m().

In general, it is not an error to have more than one annotation with the same tag in the same place. However, some pre-defined annotations might forbid this.

ABS offers the following built-in datatypes:

Int type is a subtype of Rat; this means that Int values are assignable to places of type Rat. Rational values can be converted to integers via the truncate function. Float is a distinct numeric type.

The future type Fut<A> is a special built-in type that denotes that an ABS value of type A will become available in the future. The value that a future holds and will return can be of any concrete type.

Algebraic Data Types in ABS are used to implement user-defined, immutable data values. Because values of algebraic data types are immutable, they can be safely passed on to other objects and cogs and make it easy to reason about program correctness.

Data Type Constructors enumerate the possible values of a data type. Constructors can have zero or more arguments. Each argument can have an optional accessor function (see Accessor Functions).

Interfaces in ABS describe the functionality of objects. Thus, Interfaces in ABS are similar to interfaces in Java. Unlike Java, object references are typed by interfaces and not by their class. See Type-Check Expressions and Type-Cast Expressions for how to obtain a reference to the same object via a different interface.

The syntax of interfaces is given in Interfaces.

In higher-level programming languages, exceptions are generally used to signal an erroneous or abnormal runtime behavior of the program, that should be treated (handled) separately compared to normal values.

Exceptions are declared with the keyword exception, followed by the name of an exception and an optional list of parameters. The semantics are the same as for defining data constructors; naming a parameter will create an accessor function (see Accessor Functions).

Like any other constructor or datatype name, exceptions always start with an upper-case letter.

Exceptions are of type ABS.StdLib.Exception, which is pre-defined in the standard library. It is possible to store exception values in variables of type Exception.

In ABS, exceptions are first-class values; the user can construct exception-values, assign them to variables, pass them in expressions, etc. An exception can be thrown via the throw statement (see Throw) and be caught in a catch block (see Handling Exceptions with Try-Catch-Finally). Additionally, the object itself can recover its invariant after an uncaught exception in a process via its recovery block (see Classes).

A Type Synonym is an alternative type name for a type. Type synonyms are introduced with the keyword type. Parametric type synonyms are not currently supported.

A Location Type is an interface type annotated with a location. The location is seen relative to the current context, and can be one of the following:

When location type checking is active, the following example is erroneous, and will result in a type error:

Literals, as defined in Literals, are expressions.

Template strings are strings allowing embedded expressions. In contrast to normal string literals, template strings can contain linebreaks and other special characters.

A template string starts and ends with a backtick (`) character. A template string can contain zero or more pure expressions enclosed by dollar signs ($). These expressions will be replaced by their string representation (as with the function toString) every time the template string is evaluated.

The only characters that need to be escaped by a backslash (\) in a template string are the backtick (`) and the dollar sign ($). All other characters, including line breaks and the backslash itself, do not need to be specially treated when writing a template string.

The result of this expression will be a string with two lines, and with the values of the local variables name and price in place.

ABS has a range of unary and binary operators working on pre-defined datatypes. All operators are pure (side effect-free).

The following table describes the meaning as well as the associativity and the precedence of the different operators. The list is sorted from low precedence to high precedence.

The expression let T v = p in b evaluates b, with v bound to the value of evaluating the expression p. The newly-introduced binding of v can shadow a binding of v outside of the let expression.

More than one binding can be established in one let expression. Bindings are evaluated sequentially, i.e., later bindings can use earlier variables in their value expression.

Data Constructor Expressions are expressions that create data values by applying arguments to data type constructors. Data constructor expressions look similar to function calls, but data constructors always start with an upper-case letter.

For data type constructors without parameters, the parentheses are optional.

Defining new data types and their constructors is described in Algebraic Data Types.

Function calls apply arguments to functions, producing a value. Function call expressions look similar to data constructor expressions, but function names always start with a lower-case letter. The parentheses are mandatory in function calls.

Calls to partially defined functions (see Partial Function Definitions) are similar to function call expressions, but have an additional prepended set of arguments.

The value of the conditional expression when c then e1 else e2 is either the value of e1 or the value of e2, depending on the value of c, which must be of type Bool. Depending on the value of c, either e1 or e2 is evaluated, but not both.

ABS supports pattern matching via the Case Expression. A case expression consists of an input expression and one or more branches, each consisting of a pattern and a right hand side expression.

The case expression evaluates its input expression and attempts to match the resulting value against the branches until a matching pattern is found. The value of the case expression itself is the value of the expression on the right-hand side of the first matching pattern.

If no pattern matches the expression, a PatternMatchFailException is thrown.

There are four different kinds of patterns available in ABS:

Variables pointing to objects are typed by interface, which means that the concrete class of the referenced object might support more methods than can be called through the reference. The type-check expression checks if an object implements the given interface.

Variables pointing to objects are typed by interface, which means that the concrete class of the referenced object might support more methods than can be called through the reference. The type-cast expression returns a reference of type I to the same object if it implements the given interface I, or null otherwise.

A new expression creates a new object from a class name and a list of arguments. In ABS objects can be created in two different ways. Either they are created in the current COG, using the new local expression, or they are created in a new COG by using the new expression (see The ABS Actor and Concurrency Model for more details about cogs).

Classes can declare an init block (see Classes), which is executed for each new instance. The semantics of the new expression guarantee that the init block is fully executed before the new object begins receiving method calls. Classes can also declare a run method, which is asynchronously invoked after the init block and subject to the normal scheduling rules for processes.

A synchronous call consists of a target expression evaluating to an interface type, a method name declared in that interface, and a list of argument expressions.

The semantics of the synchronous method call differ depending on whether the caller and callee are in the same cog. A synchronous method call between objects in the same cog has Java-like semantics, i.e., the caller is suspended and the called method starts executing immediately. When the called method finishes, the caller process is scheduled and resumes execution.

In the case when caller and called object are in different cogs, a synchronous method call is equivalent to and asynchronous method call immediately followed by a get expression on the resulting future. This means that the intuitive semantics of synchronous method calls are preserved, but introduces the possibility of deadlocks in case the callee tries to call back to an object of the caller cog.

An asynchronous call consists of a target expression evaluating to an interface type, a method name declared in that interface, and a list of argument expressions.

An asynchronous method call creates a new task in the COG that contains the target. This means that the caller task proceeds independently and in parallel with the callee task, without waiting for the result. The result of evaluating an asynchronous method call expression o!m(e) is a future of type (Fut<V>), where V is the return type of the callee method m.

This future is resolved (i.e., it gets a value) when the callee task finishes. It can be used to synchronize with the callee task and obtain the result of the method call.

A get expression is used to obtain the value from a future. The current task is blocked until the future has been resolved, i.e., until either the return value is available or an exception has occurred in the callee task. No other task in the COG can be activated while the current task is blocked by a get expression.

If the future contains a normal return value, the value of the get expression is that value. If the future contains an exception thrown by the callee process, evaluating the get expression will throw the same exception. The value thrown by a get expression can be caught by try-catch as normal (see Handling Exceptions with Try-Catch-Finally).

The following example assigns the return value contained in f to the variable b. In case of any error, b is assigned False.

An await expression is a way to asynchronously call a method, wait for the callee to finish, and optionally get the result in one expression.

The statement above is equivalent to these three statements:

The destiny expression returns the future of the asynchronous call that is currently being executed. It returns a value of the Destiny type. For more information on how Destiny values can be used, see The Destiny Type.

If destiny is evaluated as part of a synchronous call S then it evaluates to the future of the task that is executing S:

For reasons of simplicity and analyzability, ABS does not offer higher-order functions. On the other hand, many common patterns of functional programming are extremely useful, for example the well-known map, filter and fold higher-order functions. For this reason, ABS supports partial function definitions.

Partial function definitions are function definitions taking an additional set of parameters. These additional parameters can be either names of normal functions, or anonymous functions (see Anonymous Functions). Partial function definitions define a set of functions which only differ in function applications but share overall structure. Put another way, partial function definitions define second-order functions — functions that take first-order functions as arguments. Partially defined functions can be used inside functional code, but cannot be passed as parameters to other partial functions.

A partially defined function is called the same way as a normal function, with a separate, non-empty argument list containing the functional arguments. For recursion inside the body of a partially defined function, omit the function parameter list.

To reduce the need to declare a function with a new function name explicitly every time a partially defined function is called, ABS uses anonymous functions. Anonymous functions are only allowed in the first arguments list calls to partially defined functions.

An anonymous function specifies a number of parameters and an expression that may refer to the declared parameters.

The following example is equivalent to the previous example, but does not define the double function explicitly.

Anonymous functions can refer to variables and fields accessible in the context of the partial function call. (Since anonymous functions are not first-class values, no closure is created.)

Some special "functions" cannot be defined with pure expressions, for example the function println. The definition of such functions is done via a special function body written as builtin, with optional pure expression arguments builtin(a, "b", 3). Such builtin functions have to be defined separately in the code generator for each backend where the model is compiled.

Built-in functions in the standard library include:

The Erlang and Java backends can read from a relational database and convert the result into ABS lists. Currently only SQLite databases are supported.

A SQLite database is queried by writing a function with a builtin body with three or more arguments: a literal sqlite3, the name of the database file, the query as a SQL string, and zero or more arguments to the query. The return value is a list of ABS values. The return type of such a function can be:

Query parameters are written as ? in the SQL query string. Each of these parameters must be supplied with a value. ABS query parameters are converted into SQL values (see https://www.sqlite.org/datatype3.html) as follows:

With the above database, the following ABS model can be run:

The skip statement is a statement that does nothing.

A variable declaration statement is used to declare variables. Variable declarations can occur at any point in a sequence of statements; i.e., it is not necessary to declare variables only at the beginning of methods or blocks.

Variables declared inside a block are in scope for the duration of the block. It is an error to declare a variable with the same name of another variable in scope. A local variable can have the same name as an object field.

A variable declaration has an expression that defines the initial value of the variable. The initialization expression is mandatory except for variables of reference types (interfaces and futures), in which case the variable is initialized with null if the initialization expression is omitted.

The assign statement assigns a value to a variable or a field.

Assignments to a field f can be written either this.f = e; or f = e;. In case a local variable f is in scope at the point of the assignment statement, the this prefix has to be used to assign to the field f; assignment to f will change the value of the local variable.

An expression statement is a statement that consists of a single expression. When an expression statement is executed, the expression is evaluated and the resulting value is discarded.

Expression statements are used for their side effects, for example issuing an asynchronous method call without waiting for its result.

An assert statement is a statement for asserting certain conditions. If the expression evaluates to True, executing an assertion is equivalent to skip;. If the expression evaluates to False, it is equivalent to throw AssertionFailException;.

An await statement suspends the current task until the given guard becomes active (evaluates to True). While the task is suspended, other tasks within the same COG can be scheduled.

Guards can wait for a futures to become resolved, for a Boolean condition over the object state to become true, or (in timed ABS) for a certain duration to pass.

In general, each cog will continue running a task without preempting it until the task is finished or it reaches a scheduling point. Await statements are scheduling points, as are suspend statements and assignment or expression statements containing an await expression (see Await (Expression)).

The suspend statement causes the current task to be suspended.

A return statement returns a value from a method. A return statement can only appear as a last statement in a method body.

For asynchronous method calls, executing the return statement will cause the future to be resolved so that it contains a value. Any claim guards awaiting the future will become active.

Methods that have a Unit return type do not need an explicit return statement. The future will be resolved when the method terminates.

The statement throw signals an exception (see Exceptions). It takes a single argument of type ABS.StdLib.Exception, which is the exception value to throw.

Note that the 'throw' statement can only be used inside imperative code. Functional code that cannot return a value in all cases should use the Maybe datatype.

Furthermore, note that some built-in exceptions, like DivisionByZeroException and PatternMatchFailException can originate from functional code. See Predefined exceptions in the Standard Library for a list of built-in exceptions.

A sequence of statements is called a block. A block introduces a scope for local variables.

ABS has the standard conditional statement. The condition has to evaluate to a Boolean value.

The switch statement, like the case expression (see Case), consists of an expression and a series of branches, each consisting of a pattern and a statement (which can be a block).

When a switch statement is executed, its input expression is evaluated and the value matched against the branches until a matching pattern is found. The statement in the right-hand side of that branch is then executed. Any variable bindings introduced by matching the pattern are in effect while executing that statement.

If no pattern matches the expression, a PatternMatchFailException is thrown.

For a description of the pattern syntax, see Case.

The while loop repeats its body while the condition evaluates to True. The condition is re-evaluated after each iteration of the loop.

The foreach loop repeatedly executes its body with a loop value variable bound to each element of the given list, in sequence. An optional loop index variable is bound to the index of the element bound to the value variable, starting with 0.

The rules for the loop variables follow the rules of local variable declarations in blocks: the loop variables cannot shadow existing variables, but can use the same name as an object field. Loop variables go out of scope after execution leaves the body of their foreach loop.

Executing a statement can result in an exception, either explicitly signaled using the throw keyword or implicitly, for example by dividing by zero. The try-catch-finally statement is used to handle exceptions and resume normal execution afterwards.

The statement protected by try (which can be a block) is executed first. If no exception is thrown, execution continues with the optional finally statement, then with the next statement after the try-catch-finally statement.

If during execution of the statement protected by try an exception is thrown, it is matched one-by-one against the exception patterns defined in the catch block. The statement following the first matching pattern will be executed, as in the switch statement (see Switch: Pattern Matching). Execution continues with the optional finally statement, then with the statement following the try-catch-finally statement.

If during execution of the statement protected by try an exception is thrown that is not matched by any branch in the catch block, the exception is unhandled. In this case, first the optional finally statement is executed. If the try-catch-finally was protected by another try-catch-finally statement, the unhandled exception is passed on to this surrounding try-catch-finally statement. Otherwise, the current process terminates and its future is resolved by storing the unhandled exception. Any get expression on this future will re-throw the exception (see Get). The object that ran the aborted process will execute its recovery block with the unhandled exception as parameter (see Classes).

As a syntactic convenience, when matching only a single pattern, the braces around the catch block can be omitted.

Similar to variable declarations, field declarations and class parameters can carry a Final annotation. the effect of such an annotation is to forbid re-assignment to such a field.

The following example will lead to compile-time errors since we are trying to assign new values to two fields declared as Final:

In addition to fields, method parameters and variables can also be declared Final.

For any method definition annotated with [Readonly], the compiler will statically check that its body does not contain assignments to fields.

If an interface declares a method to be read-only, its definition has to be annotated with [Readonly] as well.

The following example shows a class declaration with an atomic method that will lead to a compile error.

For any method definition annotated with [Atomic], the compiler will statically check that its body does not contain suspension points (suspend and await statements) and blocking get expressions. Such methods can be called inside init blocks and in finally clauses; all other methods cannot be called in these places.

If an interface declares a method to be atomic, its definition has to be annotated with [Atomic] as well.

The following example shows a call to an atomic method from an init block. Removing the Atomic annotation from method m would lead to a compile-time error.

A class can be active or passive. Active classes start an activity on their own upon creation. Passive classes only react to incoming method calls. A class is active if and only if it has a run method:

The run method is asynchronously called after object initialization.

A module name is a type name and must always start with an upper case letter.

Every module starts with a declaration of the form

This declaration starts a new module named MyModule. All declarations after this line until the next module declaration belong to the module MyModule.

By default, modules do not export any names. In order to make names defined within a module available to other modules, the names have to be exported. For example, to export a data type and a data constructor, one can write something like this:

Note that in this example, the data constructors are not exported, and other modules can only create values of type Drink by calling the exported constructor functions pourMilk and pourWater. By only exporting the data type without any of its constructors, one can realize abstract data types in ABS.

A special export clause export *; exports all names that are defined in the module. Note that imported names are not re-exported by export *; or export Name; (but can be re-exported via export * from OtherModule; and export Name from OtherModule; clauses).

In order to use exported names of a module in another module, the names have to be imported. In a module definition, a list of import clauses follows the list of export clauses. After being imported, these names are accessible in the current module.

Names can be accessible either qualified (with package prefix) or unqualified, depending on how they are imported.

The following example makes the Drink data type of the module Drinks accessible as Drinks.Drink:

The import * from Module; statement makes all names that are exported from module Module accessible without module qualifier in the current module.

Unit is the empty (void) datatype.

Object is the standard super-interface. All interfaces extend this type. All object references can be assigned to variables of this type.

The Object interface does not specify any methods.

Futures are placeholders for return values of asynchronous methods calls.

Future values are produced by asynchronous method calls (see Asynchronous Method Calls). The current process can suspend itself until a future is resolved, i.e., until the return value of the asynchronous method call is available (see Await (Statement)). The get expression returns the value of a future (see Get). In case the future is not yet resolved, the get expression blocks the current cog.

Futures are first-class values that can be stored and passed around. In case only the return value of the method call is needed and not the future itself, a shorthand can be used that combines the above three statements:

ABS provides pre-defined exceptions that are thrown in specific circumstances. See Exceptions for information about exceptions.

A list is a sequence of values of the same type. Lists are constructed via the list constructor function, e.g., list[1, 2, 3] creates a list of three integers. An empty list is created via list[] or Nil.

The time to access a value via nth is proportional to the length of the list. The first value of a list can be accessed in constant time, using the head function.

The map, fold and filter second-order functions described in this section implement common functional programming patterns. To execute some statements for each element in a list, use a foreach loop (see The Foreach Loop).

A set contains elements of the same type, without duplicates. Sets are constructed via the set constructor function, e.g., set[1, 2, 2, 3] creates a set of three integers 1, 2, 3. The expression set[] produces the empty set.

To add an element to a set, use the function insertElement, to remove an element, use remove. To test for set membership, use the function contains.

The takeMaybe function can be used to iterate through a set. It is used as follows:

Maps are dictionaries storing a value for each key.

Maps are constructed using by passing a list of type Pair<A, B> to the map constructor function. The keys of the resulting map are of type A and values are of type B. The expression map[] produces an empty map.

The following example produces a map with two entries 1 → "ABS" and 3 → "SACO".

The value associated with a key can be obtained using the lookup and lookupDefault functions.

A map can be iterated over via the functions keys, values and entries, which return the set of keys and the list of values and entries of the map, respectively.

This subsection lists definitions of the standard library that do not fit in any other sections.

When an ABS model is started with the -p parameter naming a port number, the model will listen on the specified port for requests. In the following example, we compile a model my-model.abs and start the model API on port 8080:

When running a model with the model API activated, it will not return to the command line after the simulation has finished. Instead, the model will keep listening for requests and method calls.

A running model can be terminated manually from the console (for example, via pressing Ctrl-C), or by requesting the URL /quit. The following command will terminate a model running on port 8080:

The Model API can be used to access objects of the running model, if these models are exposed.

Objects are exposed via a HTTPName annotation. In the following example, two objects of class C are exposed with the names C1 and C2 respectively. The HTTPName annotation can be used on assignment statements, variable declarations and new expression statements.

The Model API can be used to call methods of exposed objects, if those methods are exposed in their interface definition. Exposed methods have some restrictions for which arguments they can accept, because their argument values need to be serialized via JSON or URL parameters when called via the Model API.

In an interface declaration, a HTTPCallable annotation exposes the annotated method such that it is callable from outside, given an exposed object that implements that interface.

It is a compile-time error if the method takes parameters whose types are not supported.

The method can have any return type. Method call results will be returned as a string via the ABS toString() function, except for the types enumerated in the following table.

User-defined datatypes are encoded depending on the presence of accessor functions and HTTPName annotations. If the datatype definition contains neither, values will be encoded as strings via toString(). If at least one accessor function or HTTPName annotation is present, values will be encoded as objects, with the HTTPName annotation value (or accessor function name, if no annotation is present) as key. Unnamed constructor argument values will not be contained in the JSON object.

The Model API can inspect the state of exposed objects, i.e., the names and values of the object’s fields.

The following query returns the names of all exposed objects.

Inspecting an object state directly can be useful for debugging. The following query returns a JSON map of the state of the object exposed as C1, with object fields as keys.

The following query returns a JSON map containing the value of C1’s `field, with "field" as key.

When querying for an unknown object or an unknown field, the HTTP request will produce a 404 response code.

The following query returns, for an object exposed as C1, a JSON array of objects with metadata about callable functions.

Each entry in the resulting list will be a JSON object with the following keys:

Exposed methods are called by querying a URL of the form

Parameters are passed to methods either as query parameters in the URL or in a JSON map passed in as the body of a POST request. For duplicate arguments, parameter values in the URL override values given in the JSON body.

The following query produces the return value of the method call method("value", 50) by invoking it on the object exposed as C1.

This query can be invoked from the shell in two ways, using the curl command, either using query parameters or a JSON body:

Of course, the Model API can not only be invoked via curl but also from other programs. The following example shows how to call a method testConfig that takes an argument mylist of type List<Int> from Javascript using the JQuery library:

Care must be taken to disable timeouts on the HTTP client when querying for long-running methods in this way.

When querying for unknown objects or methods, the HTTP request will produce a 404 response code.

When querying with invalid method parameters, the HTTP request will produce a 400 response code.

When the invoked method throws an exception, the HTTP request will produce a 500 response code.

The simulated clock of Timed ABS (Timed ABS) is accessible via the Model API.

The current value of the clock can be obtained with the following request:

The result is a JSON object with a key 'result' mapping to the current value of the clock.

If the model was started with a clock limit (see Timed ABS and the Model API), the limit can be increased via a request like the following:

The result is a JSON object with a key 'result' mapping to the new clock limit.

This call will always increase the clock limit by the given amount, even if the clock had not yet reached the previous limit. I.e., when now() = 10 and the limit is 20, after the call the limit will be 70, the same as when the clock was already stopped at the limit of 20 when the call was received by the Model API.

Note that increasing the clock limit if the model was not started with an initial limit has no effect.

Since the Model API is implemented via HTTP, it can be accessed from a web browser. The --modelapi-index-file command-line switch is used to supply an index.html file at compile-time:

When running a model on port 8080 and accessing http://localhost:8080/ from a browser, the contents of that file will be displayed.

Sometimes it is necessary to add additional files for visualization, e.g., CSS files, images or JavaScript libraries. The contents of one directory can be added to the model via the --modelapi-static-dir command-line switch:

The contents of the given directory are copied at compile-time. The files within that directory are available within the Model API below the static/ path. For example, a file ./support-files/js/d3.js will be accessible as http://localhost:8080/static/js/d3.js, and can be referred within the index.html file like this:

It is sometimes necessary to change the url under which the model publishes the given index.html file and static files. When starting a model, the parameter --url-prefix can be used to insert a prefix to these paths, and to the /call and /o URLs described above.

As an example, the following command will make the index file given at compile-time available at http://localhost:8080/abcd/5080/index.html:

Time is expressed as a datatype Time, durations are expressed using the datatype Duration, which can be infinite. These datatypes are defined in the standard library as follows:

The function now always returns the current time.

Note that since ABS uses simulated time, two calls to now can return the same value. Specifically, the result of now() changes only by executing duration or await duration statements, or by waiting for resources to become available.

The function deadline returns the deadline of the current process.

The initial value of a deadline is set via a Deadline annotation at the caller site.

The function timeValue returns the value of its argument as a rational number.

The function timeDifference returns the absolute value of the difference between its two arguments, i.e., a value greater or equal to 0.

The function timeLessThan returns True if the value of its first argument is less than the value of its second argument.

The function durationValue returns the value of its argument as a rational number.

The function isDurationInfinite returns True if its argument is InfDuration, False if its argument is Duration(x) for some value x.

The function addDuration adds a duration to a time, returning a new value of type Time. It is an error to pass InfDuration as an argument to this function.

The function subtractDuration subtracts a duration from a time, returning a new value of type Time. It is an error to pass InfDuration as an argument to this function.

The function durationLessThan returns True if the value of its first argument is less than the value of its second argument. In case both arguments are InfDuration, durationLessThan returns False.

The function subtractFromDuration subtracts a value v from a duration, returning a new value of type Duration. In case its first argument is InfDuration, the result will also be InfDuration.

The duration(min, max) statement blocks the cog of the executing process until at least min and at most max time units have passed. The await duration(min, max) statement (see Await (Statement)) suspends the current process until at least min and at most max time units have passed.

The second argument to duration can be omitted; duration(x) is interpreted the same as duration(x, x).

The difference between duration and await duration is that in the latter case other processes in the same cog can execute while the awaiting process is suspended. In the case of the blocking duration statement, no other process in the same cog can execute. Note that processes in other cogs are not influenced by duration or await duration, except when they attempt to synchronize with that process.

The simulated clock advances such that it makes the least amount of “jumps” without missing any point of interest. This means that when a process waits or blocks for an interval (min, max), the clock will not advance more than max, since otherwise it would miss unblocking the process. On the other hand, the clock will advance by the highest amount allowed by the model. This means that if only one process waits for (min, max), the clock will advance by max.

Figure Big-step time advance shows a timeline with two process, P1 and P2. They are waiting for time to advance between (4, 6) and (3, 5) units, respectively. Assuming that no other process is ready to run, the clock will advance the maximum amount that still hits the earliest interval, in this case 5. Since the clock is now within both intervals, both processes are unblocked and ready to run.

By default, the clock will advance when all processes within the model are waiting for the clock. However, it is sometimes desirable to synchronize the internal clock with some external event or system, and therefore to temporarily block it from advancing beyond a certain value.

When starting a model, the erlang backend (Erlang Backend) supports a parameter -l x or --clock-limit x which stops the clock at the given value x. This makes it possible to model infinite systems up to a certain clock value. When the clock limit is reached, the model will terminate even if there are processes which would be enabled by further clock advancement.

When starting a model with both the -l and -p parameters (i.e., with both the model api and a clock limit), a request to the model api of the form /clock/advance?by=x will increase the clock limit by x, thereby causing waiting processes to run until the new limit is reached.

A scheduler is a function that takes a list of processes and chooses one of them. Schedulers are ordinary ABS functions.

The following two example schedulers illustrate the concept. The first, deterministic scheduler takes the first process off the list; the second scheduler chooses a non-deterministic one.

It is possible to formulate an Earliest Deadline First (EDF) scheduler in ABS:

All schedulers must have a result type Process and must take an argument of type List<Process> as their first argument.

A process is an ABS abstract datatype; i.e., there is no constructor available to create a Process value inside ABS. Processes are created by the runtime and handed to schedulers.

Processes have attributes which can be used by schedulers to choose the next process to run. For example, a scheduler could always prefer processes that run a certain method. The following attributes are available:

Schedulers apply to cogs since cogs are responsible for scheduling one of their processes when idle. Since cogs are created via new expressions, a scheduler can be given at that point via an annotation. Classes can have a default scheduler that is given as an annotation to the class definition; any cog created when instantiating this class will have that scheduler by default (unless overridden by an annotation at the new expression).

The following example shows how to define a class that uses the randomscheduler by default. The first argument (the list of processes) must have the name queue.

The following example shows how to create a cog with a different scheduler.

For schedulers with more than one argument, values for subsequent arguments are filled with the value of object fields of the same name current at scheduling time. The object whose fields are used is the first object in a cog, i.e., the object created via the new expression that created the cog. Subseqent objects created in that cog via new local cannot influence the scheduler.

Deployment components are usually managed by a Cloud Provider instance. The Cloud Provider implements the life cycle shown in Figure Deployment Component lifecycle. A deployment component is managed by a cloud provider if it was created via one of the launchInstance methods.

The operations supported by deployment components during their lifecycle are summarized in Table [table-dc-lifecycle].

In ABS, processes run inside cogs. Deployment components are used to provide a location to cogs. Cogs residing on the same deployment component share the resources provided by the deployment component.

Deployment Components are first-class constructs in the ABS language. References to deployment components can be stored in variables of type DeploymentComponent, and the methods documented in this section can be called via asynchronous method calls.

Deployment Components are usually created by a cloud provider instance (see The CloudProvider API), but can also be created using the new expression. A new cog is created on a deployment component by using a DC annotation to the new statement.

If no DC annotation is given for a new statement, the fresh cog (and its first object) are created on the same deployment component as the current cog.

The term “Resource” can be understood in different ways. In ABS, we define “Resource” to be a countable, measurable property of a deployment component. Some resources stay constant throughout the life of a deployment component (e.g., the number of cores), some others are influenced by program execution (e.g., the available bandwidth in the current time slot).

The resource types currently supported by the ABS language are defined in the ABS.DC module as follows:

When a deployment component is created without explicitly giving a value for a resource type, it is assumed to have an infinite amount of that resource. E.g., when modeling a denial of service attack, the deployment component running the attacker code will have infinite speed and bandwidth.

As described above, resource information is added to statements of an ABS model using Cost and DataSize annotations. Executing such annotated statements causes observable changes in the simulated time and deployment component load during simulation.

ABS supports the delta-oriented programming model, an approach that aids the development of a set of programs simultaneously from a single code base, following the software product line engineering approach. In delta-oriented programming, features defined by a feature model are associated with code modules that describe modifications to a core program. In ABS, these modules are called delta modules. Hence the implementation of a software product line in ABS is divided into a core and a set of delta modules.

The core consists of a set of ABS modules that implement a complete software product of the corresponding software product line. Delta modules (or deltas in short) describe how to change the core program to obtain new products. This includes adding new classes and interfaces, modifying existing ones, or even removing some classes from the core. Delta modules can also modify the functional entities of an ABS program, that is, they can add and modify data types and type synonyms, and add functions.

Deltas are applied to the core program by the ABS compiler front end. The choice of which delta modules to apply depends on the selection of a set of features, that is, a particular product of the SPL. The role of the ABS compiler front end is to translate textual ABS models into an internal representation and check the models for syntax and semantic errors. The role of the back ends is to generate code for the models targeting some suitable execution or simulation environment.

The DeltaDecl clause specifies the syntax of delta modules, consisting of a unique identifier, an optional list of delta parameters, an optional module access directive, and a sequence of module modifiers.

The ModuleAccess clause specifies the semantics of unqualified identifiers within a delta. Any identifiers without namespace prefix will be resolved as if they occurred in the module named in the ModuleAccess clause. A delta can always make additions and modifications in any module by fully qualifying the TypeName within module modifiers. New program elements (classes, interfaces, etc.) with unqualified names are added to the module given in the uses clause; it is an error to add new program elements with unqualified names in a delta that does not have a uses clause.

While delta modeling supports a broad range of ways to modify an ABS model, not all ABS program entities are modifiable. These unsupported modifications are listed here for completeness. While these modifications could be easily specified and implemented, we opted not to overload the language with features that have not been regarded as necessary in practice:

Software variability is commonly expressed using features which can be present or absent from a product of the product line. Features are defined and organised in a feature model, which is essentially a set of logical constraints expressing the dependencies between features. Thus the feature model defines a set of legal feature combinations, which represent the set of valid software variants that can be built.