\input texinfo
@c -*- mode: texinfo; -*-

@c %**start of header
@setfilename dezyne.info
@documentencoding UTF-8
@settitle Dezyne Reference Manual
@c %**end of header

@include version.texi

@c Identifier of the OpenPGP key used to sign tarballs and such.
@set OPENPGP-SIGNING-KEY-ID 1A858392E331EAFDB8C27FFBF3C1A0D9C1D65273
@set OPENPGP-SIGNING-KEY-URL https://savannah.gnu.org/people/viewgpg.php?user_id=4348

@c Default queue sizes
@set queue-size 3
@set queue-size-defer 2
@set queue-size-external 1

@c Base URL for downloads.
@set BASE-URL https://dezyne.org/download/dezyne

@copying
Copyright @copyright{} 2014 Ard-Jan Moerdijk@*
Copyright @copyright{} 2014, 2020, 2021, 2022, 2023, 2025 Rutger van Beusekom@*
Copyright @copyright{} 2014 Henk Katerberg@*
Copyright @copyright{} 2014 Ladislau Posta@*
Copyright @copyright{} 2014, 2016, 2019, 2020, 2021, 2022, 2023, 2024, 2025 Janneke Nieuwenhuizen@*
Copyright @copyright{} 2014, 2015, 2016 Rob Wieringa@*
Copyright @copyright{} 2014, 2021, 2025 Paul Hoogendijk@*
Copyright @copyright{} 2021, 2024 Ludovic Courtès@*

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end copying

@dircategory Software development
@direntry
* Dezyne: (dezyne).                     Dezyne Reference Manual.
* dzn: (dezyne)Invoking dzn.            Running Dezyne commands.
* dzn anonymize: (dezyne)Invoking dzn anonymize.  Anonymizing a Dezyne file.
* dzn code: (dezyne)Invoking dzn code.       Generating code from a Dezyne file.
* dzn graph: (dezyne)Invoking dzn graph.      Generating graphs of Dezyne models.
* dzn language: (dezyne)Invoking dzn language.   Lookup and completion.
* dzn lts: (dezyne)Invoking dzn lts.        Manipulate and query an LTS.
* dzn parse: (dezyne)Invoking dzn parse.      Checking the syntax of Dezyne file.
* dzn simulate: (dezyne)Invoking dzn simulate.   Simulating Dezyne models.
* dzn test: (dezyne)Invoking dzn test.  Explore entire LTS state of a program.
* dzn trace: (dezyne)Invoking dzn trace.      Transform verify, code, and simulate traces.
* dzn traces: (dezyne)Invoking dzn traces.     Generate a set of traces.
* dzn verify: (dezyne)Invoking dzn verify.     Verifying Dezyne models.
@end direntry

@titlepage
@title Dezyne Reference Manual
@subtitle Component based, formally verified.
@author The Dezyne developers

@page
@vskip 0pt plus 1fill
Edition @value{EDITION} @*
@value{UPDATED} @*

@insertcopying
@end titlepage

@contents

@c *********************************************************************
@node Top
@top Dezyne

This document describes Dezyne version @value{VERSION}.

@menu
* Introduction::                What is Dezyne about?
* Ideas and Concepts::          Explaining the underlying thinking.
* Installation::                Installing Dezyne.
* Getting Started::             Writing a program in Dezyne.
* Execution Semantics::         How do they do it?
* Formal Verification::         A guide to verification errors.
* Defensive Design::            A protective armor.
* Code Integration::            Creating an executable.
* The Dezyne command-line tools::  Running the tools.
* Dezyne Language Reference::   All the language details.
* Well-formedness::             Interpreting parse errors.
* Contributing::                Your help needed!
* Acknowledgments::             Thanks!
* Concept Index::               Concepts.
* GNU Free Documentation License::  The license of this manual.

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* Purpose::                     Why are we creating Dezyne?
* Conditions for Using Dezyne::  There are (almost) no limits to using Dezyne.

Ideas and Concepts

* Concurrency::                 A message passing programming model.
* Component Based::             Recursive decompositioning.
* Model Based::                 Modeling the real world.
* Design by Contract::          Contracts for message interaction.
* Managing Complexity::         Abstraction and encapsulation.

Installation

* Requirements::                Software needed to build and run Dezyne.

Getting Started

* Hello World!::                First contact with Dezyne.
* A Simple State Machine::      Stateful behavior and protocol.
* A Camera Example::            A System of Components and Systems.
* The Lego Ball Sorter::        A Machine Operating System.

Execution Semantics

* Direct in event::             A provides trigger forwarded
* Direct out event::            A requires trigger forwarded.
* Direct multiple out events::  Multiple requires triggers forwarded.
* Indirect in event::           A requires trigger => requires action.
* Indirect out event::          A provides trigger => provides trigger via requires action.
* Indirect multiple out events::  Provides trigger => provides trigger via requires actions and triggers.
* Indirect blocking out event::  Synchronize two triggers via block and release.
* External multiple out events::  Delay caused by parallelism
* Indirect blocking multiple external out events::  Block, delay, release.
* Multiple provides::           Multiple provides ports
* Blocking multiple provides::  Blocking and multiple provides ports
* Blocking in system context::  Blocking by one level of indirection: collateral blocking

Formal Verification

* Verification Checks and Errors::  Which properties are verified?
* Verification Counter Examples::  What if verification fails?
* Interpreting Verification Errors::  How to fix verification errors.

Defensive Design

* Interface Contracts::         Consequences of a breach of contract.
* Error Handling and Recovery::  Specifying Exceptional behavior.
* Armoring::                    Making a program robust.

Code Integration

* Integrating C++ Code::
* Foreign Component::
* Thread-safe Shell::
* Integrating Scheme Code::

Integrating Scheme Code

* Namespace to Module::

The Dezyne command-line tools

* Invoking dzn::                Running Dezyne commands.
* Invoking dzn anonymize::      Anonymizing a Dezyne file.
* Invoking dzn code::           Generating code from a Dezyne file.
* Invoking dzn exec::           Running an arbitrary command-line.
* Invoking dzn graph::          Generating graphs of Dezyne models.
* Invoking dzn hash::           Computing the cryptographic hash of a dzn-file.
* Invoking dzn hello::          A simple sanity check.
* Invoking dzn language::       Lookup and completion.
* Invoking dzn lts::            Manipulate and query an LTS.
* Invoking dzn parse::          Checking the syntax of Dezyne file.
* Invoking dzn simulate::       Simulating Dezyne models.
* Invoking dzn test::           Explore entire LTS state of a program.
* Invoking dzn trace::          Transform verify, code, and simulate traces.
* Invoking dzn traces::         Generate a set of traces.
* Invoking dzn verify::         Verifying Dezyne models.


Dezyne Language Reference

* Lexical Analysis::            Tokens, separators and whitespace.
* Dezyne Files::                What goes into a Dezyne file?
* Types and Expressions::       Manipulating data in Dezyne.
* Interfaces::                  Defining contracts for components and systems.
* Components::                  Defining a program's behavior in Dezyne.
* Systems::                     Decomposing a system.
* Namespaces::                  Avoiding name collision.

Lexical Analysis

* Identifiers::                 Choosing names.
* Keywords::                    Restricted words.
* Operators::                   Building blocks for expressions.
* Delimiters::                  Constructing lists.
* Lexical Scoping::             Locality of names.
* Comments::                    Explanations for human readers.

Types and Expressions

* Void::                        Definitions without type.
* Bool::                        Builtin boolean type.
* Enum::                        Enumerated user types.
* Subint::                      Integer user types.
* Extern Data Type::            Foreign data user types.
* Expressions::                 Constants and data.

Interfaces

* Events::                      Event or message definitions.
* Behavior::                    Specifying an interface protocol.
* Declarative Statements::      Define when to run which trigger.
* Imperative Statements::       The code that runs upon a trigger.
* Functions::                   Avoiding code duplication.

Behavior

* Behavior Variable::           The detailed state of the behavior.

Declarative Statements

* On::                          Defining what happens upon a trigger.
* Guard::                       Declarative trigger condition.
* Invariant::                   Specifying invariants.
* Using inevitable and optional::  Nitty gritty details on using modeling events.

Imperative Statements

* Action::                      Emitting events.
* Assign::                      Updating state.
* Function Call::               A named collection of imperative statements.
* Empty Statement::             When a trigger has no effect, or there is nothing to do.
* If::                          Imperative decisions.
* Illegal::                     Specifying what is not allowed.
* Reply::                       Determining the reply for a typed trigger.
* Return::                      Returning from a function.
* Variable::                    Defining a local variable.

Components

* Ports::                       Defining a component's communication channels.
* Component Behavior::          Defining a component's behavior.
* Component Types::             Three types of components.
* Component Declarative Statements::  Component-specific declarative statements.
* Component Imperative Statements::  Component-specific imperative statements.
* Multiple Provides Ports::     Providing more than one interface.

Ports

* Injection::                   Ports sharing a resource.
* External::                    Ports with external delay.

Component Declarative Statements

* Component On::                Defining what happens on a trigger.
* Blocking::                    Implementing a synchronous call on decoupled events.
* Formal Binding::              Parameter assignment in blocking or synchronous out context.
* Joining Activities::          A full blocking example.

Component Imperative Statements

* Component Action::            Sending messages over ports.
* Component If::                Imperative decisions in a component.
* Component Illegal::           Using illegal in a component.
* Component Reply::             Using reply in a component.
* Component Defer::             Decoupling execution from the client.

Systems

* Component Instances::         The components of a system.
* Binding::                     The plumbing of a system.

Binding

* Using Injection::             Binding injected ports.

Well-formedness

* Well-formedness Checks Categories::  Types of checks.
* List of Well-formedness Checks::  An alphabetical lookup list.
* Well-formedness -- Top level::  Interfaces, events and components.
* Well-formedness -- Directional::  Direction of trigger and action.
* Well-formedness -- Nesting::  The right place for declarative and imperative.
* Well-formedness -- Mixing::   Mixing of declarative and imperative.
* Well-formedness -- Reply::    Reply and ports.
* Well-formedness -- Valued Actions and Calls::  Careful use of values.
* Well-formedness -- Injection::  Restrictions on injection.
* Well-formedness -- Functions::  Returning and recursing.
* Well-formedness -- Data Parameters::  Data type errors.
* Well-formedness -- System::   Correctly binding all ports.

Well-formedness -- Top level

* Interface must define an event::
* Interface must define a behavior::
* Out-event must be void::
* Component with behavior must have a trigger::
* Component with behavior must define a provides port::

Well-formedness -- Directional

* Cannot use event as action::
* Cannot use event as trigger::

Well-formedness -- Nesting

* Assign outside on::
* Action outside on::
* Nested on used::
* Nested blocking used::
* Cannot use blocking in an interface::

Well-formedness -- Mixing

* Declarative statement expected::
* Imperative statement expected::
* Cannot use otherwise guard more than once::
* Cannot use otherwise guard with non-guard statements::
* Cannot use illegal with imperative statements::
* Cannot use illegal in if-statement::
* Cannot use illegal in function::

Well-formedness -- Reply

* Must specify provides-port with reply on out-trigger::
* Must specify provides-port with reply::

Well-formedness -- Valued Actions and Calls

* Action in member variable initializer::
* Call in member variable initializer::
* Action value discarded::
* Call value discarded::

Well-formedness -- Injection

* Injected port has out-events::

Well-formedness -- Functions

* Missing return::
* Cannot use return outside of function::
* Cannot use statement after recursive call::

Well-formedness -- Data Parameters

* Type mismatch -- parameter expected extern::
* Cannot use out-parameter on out-event::
* Cannot use inout-parameter on out-event::
* Formal binding is not a data member variable::

Well-formedness -- System

* Port not bound::
* Port not bound -- of instance::
* Port is bound more than once::
* Cannot bind port to port::
* Cannot bind two wildcards::
* Instance is in a cyclic binding::
* Cannot bind wildcard to requires port::
* System composition is recursive::
* Cannot bind external port to non-external port::

Contributing

* Building from Git::           The latest and greatest.
* Running Dezyne Before It Is Installed::  Hacker tricks.
* The Perfect Setup::           The right tools.
* Coding Style::                Hygiene of the contributor.
* Submitting Patches::          Share your work.
* Making Decisions::            Collectively choosing the way forward.
* Commit Access::               Pushing to the official repository.
* Reviewing the Work of Others::  Some guidelines for sharing reviews.

Coding Style

* Programming Paradigm::        How to compose your elements.
* Data Types and Pattern Matching::  Implementing data structures.
* Formatting Code::             Writing conventions.

Commit Policy

* Managing Patches and Branches::

@end detailmenu
@end menu

@c *********************************************************************
@node Introduction
@chapter Introduction

Dezyne is a programming language and a set of tools to specify,
validate, verify, simulate, document, and implement concurrent control
software for embedded and cyber-physical systems.

Dezyne incorporates both model based as well as component based
development.  It enables an incremental and collaborative approach to
complex system development by using a novel way of design by
contract.  The Dezyne language allows defining not just the structure,
but equally the detailed behavior of a software system using a C like
syntax.  Its rigorous notation enables automatically creating both
abstract and detailed diagrams consistent with both the structure and
the behavior.

The Dezyne language has formal semantics expressed in
@url{https://mcrl2.org, mCRL2} developed at the department of
Mathematics and Computer Science of the Eindhoven University of
Technology (@url{https://tue.nl,TUE}).  Dezyne requires that every model
is finite, deterministic and free of deadlocks, livelocks, and contract
violations.  This is achieved by means of the language itself as well as
by builtin verification through model checking.  This allows the
construction of complex systems by assembling independently verified
components.

What Dezyne sets apart from other programming languages is the fact that
it treats the language primitives of the message passing programming
model as first class citizens.

Dezyne is Free Software.  Everyone is encouraged to share this software
with others under the terms of the GNU Affero General Public License
version 3 or later (see @url{https://gnu.org/licenses#AGPL, AGPL3+}).
Fundamentally, the Affero General Public License is a license which says
that you have these freedoms and that you cannot take these freedoms
away from anyone else.

If you find Dezyne useful, please let us know.  We are always interested
to find out how Dezyne is being used.

You are also encouraged to help make Dezyne more useful by writing and
contributing new functionality by submitting patches, and by reporting
problems you may encounter, (@xref{Contributing}).

@menu
* Purpose::                     Why are we creating Dezyne?
* Conditions for Using Dezyne::  There are (almost) no limits to using Dezyne.
@end menu

@node Purpose
@section Purpose

The main purpose of Dezyne is to systematically support the development
and evolution of programs for which the validity is determined by their
detailed behavior under operational conditions (E-type programs
@footnote{@url{https://cs.uwaterloo.ca/~a78khan/cs446/additional-material/scribe/27-refactoring/Lehman-LawsOfSoftwareEvolution.pdf,Lehman
Laws of Software Evolution}}).  These are also the type of program which
change the most and are most negatively affected by that change.

@node Conditions for Using Dezyne
@section Conditions for Using Dezyne

@cindex non-free software
@cindex license of generated code
The distribution terms for Dezyne-generated code permit using the code
in free software programs as well as in non-free or proprietary
programs: The Dezyne code generator @emph{transpiles} the user's Dezyne
program into a program in the target language, e.g., @code{C++}, making
the resulting @code{C++} program a derivative work of the user's Dezyne
code, inheriting its copyright and--if applicable, licensing terms.

@cindex Dezyne runtime library
@cindex modifying the Dezyne runtime
The Dezyne runtime is distributed under the GNU Lesser General Public
License (see @url{https://gnu.org/licenses#LGPL, LGPL3+}), which means
that it can be freely and unconditionally used in unmodified form, also
if you are creating a non-free or proprietary software.  If you
@emph{modify} the Dezyne runtime code that you distribute with your
program, one condition applies: The modifications must be made
available.

@quotation Note
Dezyne comes with NO WARRANTY, to the extent permitted by law.
@end quotation

@c *********************************************************************
@node Ideas and Concepts
@chapter Ideas and Concepts

Dezyne aspires to evolve into a general-purpose operating-system
language.  The operating-system qualification refers to programs that
are stateful, highly concurrent, long-lived, resilient, and
exceptionally reliable.  In contrast, short lived programs or programs
that can be completely written in a pure functional way are not the
primary target of Dezyne.  By bringing mathematics and computer
engineering together we hope to foster the creation and evolution of
verified ``operating system''@footnote{preferably microkernel based or
at least distributed, the @url{https://hurd.gnu.org/hurd,GNU Hurd}
anyone?} like applications.

The syntax of Dezyne may feel pretty familiar.  The semantics is quite
distinct from most other languages.  Simply put Dezyne is the super
position of a process calculus onto a general purpose language.  As a
result it adds new levels of organizational structure to the concept of
a general purpose programming language.

@menu
* Concurrency::                 A message passing programming model.
* Component Based::             Recursive decompositioning.
* Model Based::                 Modeling the real world.
* Design by Contract::          Contracts for message interaction.
* Managing Complexity::         Abstraction and encapsulation.
@end menu

@node Concurrency
@section Concurrency

Dezyne is based on a message passing programming model.  Messages are
explicitly represented in the language and expressed in the underlying
process algebra.  The approach allows reasoning about equivalences which
in turn is used in verification and allows compositions to retain their
individually verified properties.

Message passing is a natural way of describing concurrency, from
cooperative multitasking to multi threading and multi processing.  It
abstracts away from cumbersome primitives like semaphores, mutexes,
condition variables, critical sections, etc.  It also removes the
passing of time completely and focuses our reasoning on the ordering of
messages.  Which allows combining synchronous and asynchronous activity
in a single formalism.

Multi tasking vs parallelism.

@node Component Based
@section Component Based

In Dezyne programs are divided into components by means of formal
interfaces isolating the components from their surroundings.  Components
are composed into systems by connecting their ports.  Communication
across port must follow the behavior as defined by their respective
interfaces.  An interface behavior describes the message exchange
between the components on either side of the interface that separates
them.  A component behavior defines the interactions in terms of the
messages exchanged across all of the component ports.

Message or event maps onto a function call.

@node Model Based
@section Model Based

Dezyne is for applications where one encounters the problems that the
operating system does not solve.

As Dezyne is typically used to operate an abstract machine, usually real
world identities are represented.  They are identified by name and their
interaction with their environment is captured as a behavior.  A
behavior is the observable interaction in terms of message exchange.
Interface models and component models both define behaviors.

@node Design by Contract
@section Design by Contract

Regular languages have more or less support for design by contract.  In C
one can assert pre and post conditions. In design there is more support
for this...

As interface behaviors prescribe an interaction protocol, they provide a
convenient and compact way to define contracts.  A contract lists both
expectations and obligations.  Components in turn are a convenient and
compact way to implement such contracts using other sub contractors.
Components distinguish two levels of hierarchy in their interface
contracts: The interfaces they provide and the interfaces they require.
The essential difference between the two is that an interface which is
provided must be completely implemented.  While an interface that is
required may or may not be used completely.

@node Managing Complexity
@section Managing Complexity

The single biggest challenge, when programming at scale, is managing
complexity.  What do we mean by complexity?  The literal meaning is
derived from weaving together.  In programming it refers to the
resulting behavior that emerges from combined interaction.  As the
number of parts and their dependencies increase, the resulting behavior
increases exponentially and very soon it reaches the point where it is
no longer humanly possible to know and understand it.  As a result
making changes will inadvertently lead to unknowingly interfering with
those interactions and defects are introduced.  With increasing
complexity existing techniques, methods and paradigms no longer suffice
to enable the programmer to adequately manage it.  Dezyne offers both
encapsulation as well as abstraction of interaction.  Interaction which
is unencapsulated in other paradigms.  By encapsulating and abstract
Dezyne manages complexity.

@c *********************************************************************
@node Installation
@chapter Installation

@cindex installing Dezyne

To build the Dezyne command line tools from the source tarball, you need
to install some dependencies, see the section below.  When you plan on
contributing to Dezyne you will probably want to build from Git which
has additional requirements (@pxref{Contributing}).

@c There are two ways to get started with Dezyne: use a binary installation
@c that we prepared especially for you, or you can build Dezyne from source
@c yourself.  When you plan on contributing to Dezyne (@pxref{Contributing}),
@c you may want to skip the sections on binary installation.

@menu
* Requirements::                Software needed to build and run Dezyne.
@end menu

@c @node Binary Installation
@c @section Binary Installation

@c @cindex installing Dezyne, binary
@c This section describes how to install Dezyne on an arbitrary system from a
@c self-contained tarball providing binaries for Dezyne and for all its
@c dependencies.  This is often quicker than installing from source, which
@c is described in the next sections.  The only requirement is to have
@c GNU@tie{}tar and gzip.

@c @subsection Generic GNU/Linux Binary

@c Installing goes along these lines:

@c @enumerate
@c @item
@c @cindex binary installation
@c @cindex downloading Dezyne binary
@c @cindex GNU/Linux
@c Download the binary tarball from@*
@c @url{@value{BASE-URL}/dezyne-@value{VERSION}-x86_64-linux.tar.gz},
@c e.g.:

@c @example
@c $ wget @value{BASE-URL}/\
@c dezyne-@value{VERSION}-x86_64-linux.tar.gz
@c @end example

@c Make sure to download the associated @file{.sig} file and to verify the
@c authenticity of the tarball against it; do something like:

@c @example
@c $ wget @url{@value{BASE-URL}/\
@c dezyne-@value{VERSION}-x86_64-linux.tar.gz.sig}
@c $ gpg --verify dezyne-@value{VERSION}-x86_64-linux.tar.gz.sig
@c @end example

@c If that command fails because you do not have the required public key,
@c then run this command to import it:

@c @example
@c $ wget @value{OPENPGP-SIGNING-KEY-URL} \
@c       -qO - | gpg --import -
@c @end example

@c @noindent
@c and rerun the @code{gpg --verify} command.

@c Take note that a warning like ``This key is not certified with a trusted
@c signature!'' is normal.

@c Now, you can unpack the tarball; do something like:

@c @example
@c $ tar --warning=no-timestamp -xf /path/to/\
@c dezyne-@value{VERSION}-x86-64.tar.gz
@c @end example

@c Then try:
@c @example
@c $ cd dezyne-@value{VERSION}
@c $ ./dzn --help
@c @end example

@c @item
@c Make the @command{dzn} command available from other locations or to
@c other users on the machine, for instance with:

@c @example
@c $ ln -s $PWD/dzn ~/bin/dzn
@c or
@c # ln -s $PWD/dzn /usr/local/bin/dzn
@c @end example

@c @item
@c And optionally, make the @command{dzn-env}
@c prefix-command@footnote{@command{dzn-env} can be used as a prefix for
@c using programs from your operating system, such as @command{info},
@c @command{man}, or @command{emacs}; so that they may find and use the
@c documentation and extensions that are provided in the binary release.}
@c available:

@c @example
@c $ ln -s $PWD/dzn-env ~/bin/dzn-env
@c or
@c # ln -s $PWD/dzn-env /usr/local/bin/dzn-env
@c @end example

@c @c TODO: an installer script, either taking care of system-wide
@c @c installation (/usr/local, -- /opt?) or for an ordinary user: ~/bin/
@c @c or ~/.local/bin and environment settings?

@c @item
@c Test your installation

@c @example
@c $ dzn hello
@c $ dzn-env info dezyne
@c @end example

@c @end enumerate

@c @noindent
@c and get busy Dezyne'ing, @pxref{Getting Started}!  You can skip the
@c following sections about building from source.

@c @subsection Generic Microsoft Windows Binary

@c Installing goes along these lines:

@c @enumerate
@c @item
@c @cindex downloading Dezyne binary, Windows
@c @cindex binary installation, Windows
@c @cindex Windows
@c Download the binary zip archive from@*
@c @url{@value{BASE-URL}/dezyne-@value{VERSION}-x86_64-windows.zip},
@c @end enumerate

@c after which you can extract the archive by using 7zip
@c @url{https://www.7-zip.org/}.  Please do not use the built-in Windows
@c archive extraction tool: It does not honor the time stamps of the files
@c in the archive and thus produces a faulty installation.

@c If your system comes with a virus scanner, consider creating an
@c exception for dezyne-@value{VERSION}.

@c @dots{}

@c @noindent
@c and get busy Dezyne'ing, @pxref{Getting Started}!  You can skip the
@c following sections about building from source.

@node Requirements
@section Requirements

This section lists requirements when building Dezyne from source.  The
build procedure for Dezyne is the same as for GNU software, and is not
covered here.  Please see the files @file{README} and @file{INSTALL} in
the Dezyne source tree for additional details.

@cindex website
Dezyne is available for download from its website at
@url{https://dezyne.org/download.html}.

Dezyne depends on the following packages:

@itemize
@item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x, with readline support;
@item @url{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON} 4.x;
@item @url{https://www.gnu.org/software/make/, GNU Make};
@item @url{https://mcrl2.org, mCRL2}, version 202106.0,
@item @url{https://gitlab.com/janneke/scmackerel/, SCMackerel}, version 0.5.3.
@end itemize

Optionally, for @code{C++11}

@itemize
@item @url{https://boost, boost}, for using co-operative co-routines instead of threads.
@end itemize

To use the code that is generated by Dezyne, which includes running the
regression test:
@itemize
@item @url{https://gcc.gnu.org, GCC's g++}, version 5.4 or later.
@end itemize

@c *********************************************************************
@node Getting Started
@chapter Getting Started

In general a program in Dezyne consists of interfaces, components, and
``handwritten'' code, including a @code{main}.  For simple cases such as
the examples in this chapter, a generic @code{main} can be generated and
no handwritten code is needed.

The examples used in this chapter can be found in the Dezyne source tree
at @file{doc/examples/} or downloaded from
@url{https://git.savannah.nongnu.org/cgit/dezyne.git/tree/doc/examples,
doc/examples/ in git}.

@menu
* Hello World!::                First contact with Dezyne.
* A Simple State Machine::      Stateful behavior and protocol.
* A Camera Example::            A System of Components and Systems.
* The Lego Ball Sorter::        A Machine Operating System.
@end menu

@node Hello World!
@section Hello World!

Consider the trivial Dezyne interface @code{ihello_world}

@example
@verbatiminclude examples/ihello-world.dzn
@end example

It defines two events, named @code{hello} and @code{world} of type
@code{void} and a trivial protocol in its @code{behavior}: whenever the
@code{hello} trigger is received (@code{on hello:}), it responds
synchronously with a @code{world} action.

This scenario can be explored using the simulator (@xref{Invoking dzn
simulate}):

@example
$ dzn simulate doc/examples/ihello-world.dzn
(header ((client) ihello_world provides) ((sut) ihello_world interface))
(state ((client)) ((sut)))
labels: hello
eligible: hello
>
@end example

As expected, @code{hello} is the only trigger that is eligible to
execute; entering @code{hello} gives

@example
> hello
<external>.hello -> ...
... -> sut.hello
... <- sut.world
<external>.world <- ...
... <- sut.return
<external>.return <- ...
(state ((client)) ((sut)))
(trail "hello" "world" "return")
labels: hello
eligible: hello
>
@end example

The simulator can also be run non-interactively to produce a friendlier
trace view or sequence diagram

@c generate automagically?
@c print less (state) ??
@c ./pre-inst-env dzn simulate --format=diagram doc/examples/ihello-world.dzn -t hello | tail +4 | head -11
@c XXX use ide diagram?
@example
client          ihello_world
  .                  :
  .                  :
  .hello             :
  .----------------->:
  .                  :
  .             world:
  .<-----------------:
  .                  :
  .            return:
  .<-----------------:
@end example

Now consider a trivial component @code{hello_world}

@example
@verbatiminclude examples/hello-world.dzn
@end example

it provides the @code{ihello_world} interface, which means that it
promises to behave according to the protocol specified in the interface.

The trigger @code{p.hello} is the event @code{hello} when communicated
over the port @code{p}, similarly the action is named @code{p.world}.
Simulation gives:

@example
$ dzn simulate --trail=p.hello doc/examples/hello-world.dzn
(header ((p) ihello_world provides) ((sut) hello_world component))
(state ((p)) ((sut)))
<external>.p.hello -> ...
... -> sut.p.hello
... <- sut.p.world
<external>.p.world <- ...
... <- sut.p.return
<external>.p.return <- ...
(state ((p)) ((sut)))
(trail "p.hello" "p.world" "p.return")
(state ((p)) ((sut)))
(labels "p.hello")
(eligible "p.hello")
@end example

with this trace diagram

@example
p          hello_world
.               :
.               :
.hello          :
.-------------->:
.               :
.          world:
.<--------------:
.               :
.         return:
.<--------------:
@end example

From this component an executable program can be created (@xref{Invoking dzn
code})
@example
$ dzn code doc/examples/ihello-world.dzn
$ dzn code --model=hello_world doc/examples/hello-world.dzn
$ g++ hello-world.cc main.cc -ldzn-c++
@end example

When running this executable and feeding it the trail, we get
@example
echo -e 'p.hello\np.world\np.return' | ./a.out
<external>.p.hello -> sut.p.hello
<external>.p.world <- sut.p.world
<external>.p.return <- sut.p.return
@end example

@node A Simple State Machine
@section A Simple State Machine

The @code{ihello_bool} interface introduces stateful behavior that is
somewhat more interesting

@example
@verbatiminclude examples/ihello-bool.dzn
@end example

This example introduces some new language aspects

@table @code
@item bool idle = true;
A boolean state variable, defining @code{idle=true} as the initial
state,
@item [idle]
A @emph{guard}.  Only when the expression between the brackets evaluates
to @code{true} the @code{on} is eligible to execute.  In the initial
state, the @code{hello} trigger is the only thing that can occur.
The guard and the on are @emph{declarative} statements.  After the
declarative statements follows a,
@item idle = false;
An @emph{imperative} statement.  When @code{hello} trigger occurs, the
interface transitions to state @code{!idle},
@item on cruel: @dots{} on cruel: @dots{}
A non-deterministic choice@footnote{the caller does not resolve the choice
between the two cruel triggers, this is decided by the implementation}.
In the @code{!idle} state, @code{cruel} is accepted; it can either...
@item reply (true)
reply @code{false} and remain not idle, or
@item @{idle = true; reply (idle);@}
execute a compound of two imperative statements: Set the reply value to
@code{true} and transition to the idle state,
@item inevitable
If no @code{cruel} trigger occurs, @emph{inevitably} the @code{world}
action will occur.  @code{inevitable} is a @emph{modeling} event and is
not visible on the trail.  The effect is that @code{world} action now
has become @emph{decoupled} from the caller.
@end table

The state diagram (@xref{Invoking dzn graph}) depicts this protocol
graphically:

@image{images/ihello-bool,2in,,,.png}

This model is already interesting enough to have the mCRL2 model-checker
verify if all is well (@xref{Invoking dzn verify} and @xref{Verification
Checks and Errors})

@example
$ dzn -v verify doc/examples/ihello-bool.dzn
verify: ihello_bool: check: deadlock: ok
verify: ihello_bool: check: unreachable: ok
verify: ihello_bool: check: livelock: ok
verify: ihello_bool: check: deterministic: ok
@end example

which is luckily the case.  The model-checker can also be used to
generate all possible@footnote{the algorithm produces [traces that cover
every transition and every state} traces (@xref{Invoking dzn traces})
for @code{ihello_bool}:

@example
$ dzn -v traces doc/examples/ihello-bool.dzn
@end example

produces three trace files
(@file{ihello_bool.trace.0},@file{ihello_bool.trace.1}, and
@file{ihello_bool.trace.2}) with these traces (the order may differ):

@enumerate
@item
hello,return,world
@item
hello,return,cruel,true
@item
hello,return,cruel,false
@end enumerate

The sequence for the first trace with the asynchronous @code{world}
looks like this

@example
client          ihello_bool
  .                  :
  .                  :
  .hello             :
  .----------------->:
  .                  :
  .            return:
  .<-----------------:
  .                  :
  .                  :
  .             world:
  .<-----------------:
@end example

@noindent
and for the second trace where @code{cruel} happens looks like this

@example
client          ihello_bool
  .                  :
  .                  :
  .hello             :
  .----------------->:
  .                  :
  .            return:
  .<-----------------:
  .                  :
  .                  :
  .cruel             :
  .----------------->:
  .                  :
  .              true:
  .<-----------------:
@end example

@noindent
the third trace is looks like this

@example
client          ihello_bool
  .                  :
  .                  :
  .hello             :
  .----------------->:
  .                  :
  .            return:
  .<-----------------:
  .                  :
  .                  :
  .cruel             :
  .----------------->:
  .                  :
  .             false:
  .<-----------------:
@end example

@noindent
You may have noticed that the first two traces start and end in the
initial state, while the third trace starts in the initial state and
ends in the @code{!idle} state (also see the corresponding state
diagram).

Now have a look at the component @code{simple_state_machine}

@example
@verbatiminclude examples/simple-state-machine.dzn
@end example

It introduces the following concepts:
@table @code
@item enum status @{A, B, C@}
User defined @code{enum} type named @code{status},
@item [s.A]
Field test of enum variable @code{s}: evaluates to @code{true} if
@code{s} has field value @code{A}, it is equivalent to @code{s ==
status.A},
@item [s.B || s.C]
Logical or @code{||} in guard expression (see @xref{Expressions}),
@item on r2.world (): @{@}
A skip statement: upon receiving the @code{r2.world} trigger, the
component does ``nothing'' and is ready for the next event.  Omitting
this line would make the occurrence of @code{r2.world} @emph{illegal}.
@end table

@image{images/simple-state-machine,5in,,,.png}

Verification succeeds

@example
$ dzn -v verify doc/examples/simple-state-machine.dzn
verify: ihello_bool: check: deadlock: ok
verify: ihello_bool: check: unreachable: ok
verify: ihello_bool: check: livelock: ok
verify: ihello_bool: check: deterministic: ok
verify: iworld: check: deadlock: ok
verify: iworld: check: unreachable: ok
verify: iworld: check: livelock: ok
verify: iworld: check: deterministic: ok
verify: simple_state_machine: check: deterministic: ok
verify: simple_state_machine: check: illegal: ok
verify: simple_state_machine: check: deadlock: ok
verify: simple_state_machine: check: unreachable: ok
verify: simple_state_machine: check: livelock: ok
verify: simple_state_machine: check: compliance: ok
@end example

you may want to see what happens to verification or the state diagram
when you comment-out a statement of your choosing in the component's
behavior.

@node A Camera Example
@section A Camera Example

The @code{Camera} example introduces the system component
(@xref{Systems}).  The system diagram (@xref{Invoking dzn graph}) looks
like this:

@image{images/Camera-system,6in,,,.png}

This is what the Camera system looks like in Dezyne:
@example
component Camera
@{
  provides IControl control;

  system
  @{
    Driver driver;
    Acquisition acquisition;
    Optics optics;

    control <=> driver.control;
    driver.acquisition <=> acquisition.port;
    driver.optics <=> optics.port;
  @}
@}
@end example

It introduces the following concepts:
@table @code
@item provides IControl control;
Similar to a regular component, it defines ports,
@item system
The @code{system} specification defines @emph{instances} of components
and their @emph{bindings},
@item Driver driver;
A component instance named @code{driver} of type @code{Driver},
@item Acquisition acquisition;
A component instance named @code{acquisition} of type @code{Acquisition},
which is a @code{system} component itself,
@item Optics optics;
An instance of another @code{system} component,
@item control <=> driver.control;
A binding of the @code{Camera}'s port @code{control} to the port named
@code{control} of the @code{driver} instance.
@item driver.acquisition <=> acquisition.port;
A binding between pairs of ports on component instances.
@end table

The light blue components in the system view, such as @code{lens} are
@emph{foreign} components (@xref{Components}); their definition
looks like this:

@example
component Lens
@{
  provides ILens port;
@}
@end example

A foreign component does not specify any implementation: neither a
@code{behavior} nor a @code{system}; its behavior is said to be
implementation elsewhere, and in a foreign language (in this case
@code{C++}).

The full example is contained in the source tree at
@file{test/all/Camera/Camera.dzn} or
@url{https://git.savannah.nongnu.org/cgit/dezyne.git/tree/test/all/Camera/Camera.dzn,
Camera.dzn}.

The simplified@footnote{A simplified state diagram shows only triggers
on state transitions and hides any actions or reply values.  Also, the
state of the ports or even all extended state can be removed.  For this
diagram, the command @code{dzn graph --backend=state --hide=actions
--remove=extended test/all/Camera/Camera.dzn} was used.} state diagram:

@image{images/Camera-state,6in,,,.png}

@node The Lego Ball Sorter
@section The Lego Ball Sorter

The Lego Ball Sorter example demonstrates how Dezyne can be used to
write the operating system for a machine.  The system view is already
somewhat overwhelming:

@image{images/LegoBallSorter-system,6in,,,.png}

so it makes more sense to look at smaller parts of the system, such as
the @code{MaterialHandler}:

@image{images/MaterialHandler-system,6in,,,.png}

The full example is contained in the source tree at@*
@file{test/all/LegoBallSorter/LegoBallSorter.dzn} or@*
@url{https://git.savannah.nongnu.org/cgit/dezyne.git/tree/test/all/LegoBallSorter/LegoBallSorter.dzn,
LegoBallSorter.dzn}.

@c *********************************************************************
@node Execution Semantics
@chapter Execution Semantics

The semantics of Dezyne derives from implementing message passing as
component based interaction by means of non-reentrant recursive function
invocation.  The occurrence of an event is mapped onto a (class-member)
function call.  Every event function implements the recursive procedural
execution of all of the side effects, e.g.: actions (event function
invocations(, state updates (assignments), and runtime library
interactions: tracing, queueing, flushing and context switching
(blocking and unblocking).

For each in-event all action statements are executed depth-first.  Each
out-event is stored in the event queue of the recipient.  After the
completion of all @code{on} imperative statements, just before control
is passed back to the caller, a component will flush its own queue of
pending out events.  If a component was the recipient of an out-event
while it was not executing any events, it will also be requested to
flush its queue by the sender of the event.

The execution semantics of Dezyne are illustrated using different model
examples and their corresponding sequence diagrams.  When interpreting
the models and their corresponding event sequence traces, keep in mind
that the statements of an event are executed atomically in the context
of the behavior that implements the event.

When interpreting the event sequence traces remember the following:

@enumerate
@item in-events
are executed from left to right and return right to left.

@item out-events
are executed from right to left; each event is queued before it is
flushed and executed.
@end enumerate

In the naming of the different examples the terms @emph{direct} and
@emph{indirect} are used to indicate that execution respectively
continues in the same direction of the initial event, or changes
direction at least once.

@quotation Note
The behavior of every component example in this chapter has been
verified to comply with the behavior of all of its interfaces.
@end quotation

@menu
* Direct in event::             A provides trigger forwarded
* Direct out event::            A requires trigger forwarded.
* Direct multiple out events::  Multiple requires triggers forwarded.
* Indirect in event::           A requires trigger => requires action.
* Indirect out event::          A provides trigger => provides trigger via requires action.
* Indirect multiple out events::  Provides trigger => provides trigger via requires actions and triggers.
* Indirect blocking out event::  Synchronize two triggers via block and release.
* External multiple out events::  Delay caused by parallelism
* Indirect blocking multiple external out events::  Block, delay, release.
* Multiple provides::           Multiple provides ports
* Blocking multiple provides::  Blocking and multiple provides ports
* Blocking in system context::  Blocking by one level of indirection: collateral blocking
@end menu

@node Direct in event
@section Direct in event

A provides port in-event (@code{p.a}) call resulting in a requires port
in-event (@code{r.a}) is implemented as a function calling another
function.

@example
@verbatiminclude semantics/direct_in.dzn
@end example

@image{images/direct_in,,,,.png}

@node Direct out event
@section Direct out event

A requires port out-event (@code{r.a}) resulting in a provides port
out-event (@code{p.a}) is implemented as a function posting an event in
the component queue followed by a call to flush the queue.

@example
@verbatiminclude semantics/direct_out.dzn
@end example

@image{images/direct_out,,,,.png}

@node Direct multiple out events
@section Direct multiple out events

A requires port inevitably triggering multiple out-events (@code{r.a},
@code{r.b}) is implemented as one function call for each out-event
posting in the component queue, followed by a single flush call to
trigger component processing of the events.  The below 2 versions of the
component are indistinguishable looking from the outside.

Notice that the interface declares that @code{a} and @code{b} are
executed atomically.  While in the behavior of the component each event
is handled or forwarded independently.  However to an observer of the
provides interface of the component @code{a} and @code{b} are again
executed atomically.

@example
@verbatiminclude semantics/direct_multiple_out1.dzn
@end example

@image{images/direct_multiple_out1,,,,.png}

@example
@verbatiminclude semantics/direct_multiple_out2.dzn
@end example

@image{images/direct_multiple_out2,,,,.png}

The third variant is left as an exercise to the reader.

@node Indirect in event
@section Indirect in event

A requires port in-event (@code{r.a}) call resulting in a requires port
out-event (@code{r.b}).

@example
@verbatiminclude semantics/indirect_in.dzn
@end example

@image{images/indirect_in,,,,.png}

@node Indirect out event
@section Indirect out event

A requires port out-event (@code{r.b}) posted in the context of a
provides port in-event (@code{p.a}) call is processed before the
provides port in-event (@code{p.a}) returns.

@example
@verbatiminclude semantics/indirect_out.dzn
@end example

@image{images/indirect_out,,,,.png}

@node Indirect multiple out events
@section Indirect multiple out events

Since the provided interface is the same in the three cases below the
externally visible behavior is identical.

The three different behavior implementations of the component show the
subtle differences in the internal handling of messages.

@example
@verbatiminclude semantics/indirect_multiple_out1.dzn
@end example

@image{images/indirect_multiple_out1,,,,.png}

@example
@verbatiminclude semantics/indirect_multiple_out2.dzn
@end example

@image{images/indirect_multiple_out2,,,,.png}

@example
@verbatiminclude semantics/indirect_multiple_out3.dzn
@end example

@image{images/indirect_multiple_out3,,,,.png}

@node Indirect blocking out event
@section Indirect blocking out event

@cindex blocking semantics
The in-event on the provides port (@code{p.a}) blocks (does not return)
until a reply is handled.  This happens in the handling of the requires
port out-event (@code{r.b}).  Also @pxref{Blocking}.

@example
@verbatiminclude semantics/indirect_blocking_out.dzn
@end example

@image{images/indirect_blocking_out,,,,.png}

If the keyword @code{blocking} in above example would be omitted it
would lead to an erroneous situation since the provides in-event
(@code{p.a}) would return before the provides out-event (@code{p.b})
would have been generated.

@node External multiple out events
@section External multiple out events

@cindex external semantics
The addition of @code{external} on a @code{requires} interface removes
the atomicity of an action list, i.e: @code{@{a; b;@}}.  Also
@pxref{External}.

The first example shows how the behavior of @code{external} @code{J1}
interface transforms into the interface behavior of @code{I1} by
forwarding the events in the @code{external_multiple_out1} component
behavior.

@example
@verbatiminclude semantics/external_multiple_out1.dzn
@end example

@image{images/external_multiple_out1,,,,.png}

Two variations of the model above can be considered.  Both variants
provide the same interface behavior (@code{I2} and @code{I3} are
identical), but differ in their requires interface behavior and as a
result in their component behavior.

The first variant uses the requires behavior (@code{J1} and @code{J2}
are identical) as the first example.  The component takes care of
joining the independently received events @code{a} and @code{b} as
required by its provides interface.

@example
@verbatiminclude semantics/external_multiple_out2.dzn
@end example

@image{images/external_multiple_out2,,,,.png}

This variation provides the same interface as it requires.  The
component however, must make sure to join @code{a} and @code{b} again to
implement its provides interface behavior.

@example
@verbatiminclude semantics/external_multiple_out3.dzn
@end example

@image{images/external_multiple_out3,,,,.png}


@node Indirect blocking multiple external out events
@section Indirect blocking multiple external out events

The two requires out-events (@code{r1.b}, @code{r2.b}) can come in any
order.  The message sequence chart shows only one scenario.  The
implementation of the component is such that the provided behavior is
the same in both cases.

@example
@verbatiminclude semantics/indirect_blocking_multiple_external_out.dzn
@end example

@image{images/indirect_blocking_multiple_external_out,,,,.png}

@node Multiple provides
@section Multiple provides

For the remainder of this chapter in our explanations we will be using
the following two interfaces:

@enumerate
@item
@code{ihello}
@example
@verbatiminclude semantics/ihello.dzn
@end example

@item
@code{iworld}
@example
@verbatiminclude semantics/iworld.dzn
@end example
@end enumerate

So far we have seen examples with more than one requires port.  This
topology leads to a tree like hierarchy which is a common structure to
organize or coordinate in a top down fashion.  In the case of sharing a
single resource between multiple parties we need the opposite.  The
example below demonstrates to use of two provides ports.

@example
@verbatiminclude semantics/multiple_provides.dzn
@end example

This component simply multiplexes the @code{hello} events from its
@code{provides} ports to its @code{requires} port, resulting in the
following event sequence trace:

@image{images/multiple_provides,,,,.png}

If we replace the @code{ihello} interface in our previous example with
the @code{iworld} interface and correct for the behavioral changes, we
get the following component:

@example
@verbatiminclude semantics/async_multiple_provides.dzn
@end example

As we can see from the behavior and the event sequence trace below,
asynchronous behavior leads to event interleaving, which requires state
to manage the behavior.

@image{images/async_multiple_provides,,,,.png}

@node Blocking multiple provides
@section Blocking multiple provides

The @code{blocking} keyword can (since 2.15) also be used in combination
with multiple @code{provides} ports.  In our explanation we will
introduce a component that does two things.  First it multiplexes the
@code{provides} ports events over a single @code{requires} port.
Secondly it maps the @emph{synchronous} behavior of the @code{provides}
@code{ihello} interfaces onto the @emph{asynchronous} behavior of the
@code{requires} @code{iworld} interface (see the interface declarations
at the end of this section).

@example
@verbatiminclude semantics/blocking_multiple_provides.dzn
@end example

In the event sequence trace below we can see that for each
@code{provides} port that @emph{asynchronous} @code{hello} @code{world}
transaction is encapsulated.

@image{images/blocking_multiple_provides,,,,.png}

@node Blocking in system context
@section Blocking in system context

Blocking has a direct effect on a single event, but it also influences
the rest of the system behavior.  To investigate the effects of the
@code{blocking} keyword in system context, we will describe two
examples.  In the first example we concentrate our attention on the
event interleaving at the provides ports.  The second example focusses
on the interleaving of events that originate from the requires ports.

The indirect effect of the use of the @code{blocking} keyword is
referred to as @emph{collateral blocking}.  Blocking an event means
making the caller wait by withholding its return until some state has
been reached which is indicated by another event.  To achieve this, the
other processes outside the component that is applying the
@code{blocking} keyword must be able to make progress.  Furthermore the
component must be exposed to this progress to be able to resolve the
@emph{blocking} situation by returning to its caller.

Let us recapitulate @emph{blocking} with a small example component that
will be used by each of the examples in this section.

@example
@verbatiminclude semantics/block.dzn
@end example

@image{images/block,,,,.png}

Here we see component @code{block} that withholds its return on port
@code{b} until it has received event @code{r.world}.  Remember that a
significant amount of time may pass between @code{r.hello} and
@code{r.world}.  During this time the rest system that contains our
@code{block} component could make progress, without the component
becoming aware.  If we add more system context to our @code{block}
component we can see how @emph{collateral blocking} manifests itself.
We will add component @code{collateral} as a client to @code{block}.

@example
@verbatiminclude semantics/collateral.dzn
@end example

Besides being a client to component @code{block} this component is also
a client to another regular non-blocking component.  The event sequence
trace below shows the first of the two possible scenarios implemented by
the @code{collateral} component.

@image{images/collateral0,,,,.png}

In this first scenario nothing is out of the ordinary, but now take a
look at the second event sequence trace below.

@image{images/collateral1,,,,.png}

Here we can see that during the time between @code{b.block} and
@code{b.return} the @code{world} event on port @code{w} is allowed to
occur.  This is the result of the fact that although the
@code{collateral} component is blocked on its call to @code{b.block}, it
will find @code{w.world} in its queue before returning to its caller.
And as a result, forwarding @code{w.world} as @code{h.world} will occur
before returning to its caller, which differs from the previous
scenario.  Verification of component @code{collateral} will check for
both scenarios and ensure that the component behavior complies with all
of the interfaces behavior or otherwise report the non-compliant scenario.
Verification relies on the @code{blocking} annotation on port @code{b}
in order to infer the @emph{collateral blocking} scenario and check for
it.

@subsection Collateral blocking and multiple provides.

We can now revisit the blocking multiple provides example.  Instead of
making the multiplexing component responsible for the synchronization,
we can also add a level of indirection by splitting up
@code{blocking_multiple_provides} into a separate component that takes
care of synchronizing the @emph{asynchronous} behavior and a separate
multiple @code{provides} component.  The latter can be expressed as
component @code{mux} below:

@example
@verbatiminclude semantics/mux.dzn
@end example

This component, notwithstanding the @code{blocking} annotations on its
ports, behaves exactly like component @code{multiple_provides}.
However, when we bring its clients into scope we get the @code{system}
model below.

@example
@verbatiminclude semantics/collateral_multiple_provides.dzn
@end example

In its event sequence trace we can see another impact of
@emph{collateral blocking}.

@image{images/collateral_multiple_provides,6in,,,.png}

Although the behavior across the @code{mux} component is non-overlapping
the behavior of the client components is interleaved.

@quotation Note
In Dezyne blocking is implemented by means of coroutines.  Therefore the
interleaving of event sequences is a form of cooperative multi-tasking.
As a result its behavior is deterministic as opposed to
non-deterministic as in multi-threaded interleaving.
@end quotation

@c *********************************************************************
@node Formal Verification
@chapter Formal Verification

Dezyne provides automated, formal verification of a number of properties
of interfaces, of components, and of components in relation to their
interfaces@footnote{Verification of systems and of functional properties
are under development}.

By running @command{dzn verify}, Dezyne code is translated to
@url{https://mcrl2.org,mCRL2} code and fed to a ``verification
pipeline'', i.e., a series of @code{mcrl2} and @code{dzn} commands
(@xref{Invoking dzn verify}).

The checks that Dezyne offers are of properties that are notoriously
hard for humans to get right in all their detail, and which are
relatively easily translatable to process algebra.

These properties concern the ordering of events, synchronous versus
asynchronous calls and transactions, deadlock, unreachable code,
livelock, and strict adherence to contract.  Verifying a component
together with its provides and requires interfaces ensures that the
component behaves correctly in its environment according to the
specified behavior.  It also ensures that all possible error paths are
fully and correctly handled.

All properties that Dezyne verifies on interface and component level
are @emph{compositional}, which implies, e.g., that as system consisting
of verified components that do not deadlock, is also free of deadlock.

@menu
* Verification Checks and Errors::  Which properties are verified?
* Verification Counter Examples::  What if verification fails?
* Interpreting Verification Errors::  How to fix verification errors.
@end menu

@node Verification Checks and Errors
@section Verification Checks and Errors

A prerequisite for running the verification checks is for Dezyne code to
be syntactically correct: any parse error prohibits the verification from
running and must be fixed first.  Apart from syntactic parse errors, the
parser also checks for a number of so-called ``well-formedness'' errors.
A ``well-formedness'' error is a static check, i.e. a check that the
parser can perform without considering runtime behavior (see
@xref{Invoking dzn parse} and @xref{Well-formedness}).

Dezyne verifies for interfaces and for components:

@table @code

@item deadlock
A deadlock in an interface occurs when the interface reaches a state in
which no @code{in}-events are specified.

A deadlock is a situation where none of the components in a system can
make progress; nothing can happen and the system simply does not
respond.  This commonly occurs when two components each require an
action from the other before they can perform any further action
themselves.  Another common cause is when a component is waiting for
some external event which fails to occur.

In general, deadlocks can be hard to find because the entire system
needs to be reviewed to discover them and freedom from deadlocks is a
property of the system as a whole.  For example, component A might be
waiting for B which is waiting for C while C is waiting for A.  Dezyne
ensures that this never happens.  Each component by itself can be
verified as being deadlock free and within Dezyne this deadlock property
is compositional, which means that components can only be composed in
ways that have been proven not to cause deadlock.

@quotation Note
Dezyne can only verify what it knows; therefore, e.g., handwritten code
can still cause deadlocks.
@end quotation

Upon violation, the following error is reported:
@example
error: deadlock in model <name>
@end example

@item unreachable code
An unreachable code error occurs when there is no code path possible
that ever leads to the execution of the code.

@item illegal
A trigger that is not handled in a certain state, results in an
@code{illegal}.  For components this is also verified for the use of the
interfaces of its requires ports.

Upon violation, the following error is reported:
@example
error: illegal action performed in model <name>
@end example

@item livelock
A livelock in an interface occurs when in a certain state an
@code{inevitable} event can occur without any restriction, i.e., its
state does not change.  This could starve the client that is interacting
with this interface.

A livelock in a component occurs when it is permanently busy with
internal behavior and fails to serve a provides port.  For example, due
to a design error such that the design is constantly interacting with
its requires ports and starving a provides port; or due to the arrival
rate of unconstrained external events such that processing them starves
a provides port.  As seen from the outside of a component, this appears
very similar to deadlock.  The difference is that a deadlocked component
does nothing at all whereas a livelocked component might be performing
lots of actions, but none of them are visible to a component's provides
port.

Upon violation, the following error is reported:
@code{livelock in model <name>}

@item range error
Every possible assignment to a @code{subint} variable must be within its
defined range.

Upon violation, the following error is reported:
@example
error: integer range error in model <name>
@end example

@item type error
A trigger of a typed (i.e., non-@code{void}) event must reply a value
of the type of the event.

Upon violation, the following error is reported
@example
error: type error in model <name>
@end example

Note that trivial cases that can be checked statically, may be reported
by the parser (@xref{Well-formedness}).

@end table

In addition, Dezyne verifies for interfaces:

@table @code

@cindex non-determinism
@cindex unobservable non-determinism
@item observable non-determinism
Interfaces may specify non-deterministic behavior, as long as this
non-determinism is observable by the client of that interface: after
getting the response from the interface, a client must be able to
determine what state the interface is in.

The snippet below shows observable non-determinism, i.e., an example of
allowed non-determinism:

@example
@dots{}
[idle] on hello: @{world; idle=false;@}
[idle] on hello: cruel;
@dots{}
@end example

in the @code{idle} state, upon sending @code{hello} either @code{world}
or @code{cruel} may happen.  This non-deterministic choice cannot be
predicted.  However, when the client sees @code{world}, the state of the
interface is @code{not idle}, after seeing @code{cruel}, the state is
@code{idle}.

This is an example of non-observable non-determinism, which is not
allowed:

@example
@dots{}
[idle] on hello: @{world;idle=false;@}
[idle] on hello: world;
@dots{}
@end example

as for a client it is impossible to tell if the interface is in state
@code{idle} or in state @code{not idle}.

Upon violation, the following error is reported:

@example
error: interface <name> is unobservably non-deterministic
@end example
@end table

In addition, Dezyne verifies for components:

@table @code

@item compliance
The component together with its required interfaces implements the
component behavior.  The compliance check verifies that the component
together with the required interfaces implements the behavior specified
in the provided interface(s), i.e., whether the component honors its
contracts.

Upon violation, the following error is reported:
@example
error: component <name> is non-compliant with interface(s)\
    of provides port(s)
@end example

@item determinism
Components in Dezyne are required to be deterministic.  The most common
cause of non-determinism in a component is the ambiguous declaration of
an event, often due to overlapping guards, i.e., in one state, for an
event two different imperative statements are specified.  Upon violation
the following error is reported:

@code{error: component <name> is non-deterministic}

The event trace will indicate where and under which condition (state)
the ambiguity occurs in the component behavior.  Simulation of the
corresponding event trace can be used to determine the exact location of
the error in the input.

@item queue full
a Dezyne component has a queue where notification events are stored
before they are processed.  During verification it is checked that that
this queue does not overflow, i.e., that it remains non-blocking.  The
component queue size can be specified for verification with the
@option{--queue-size} option.  The default queue size is
@code{@value{queue-size}}.

Upon violation, the following error is reported
@example
error: queue full in model <name>
@end example
@end table

For interfaces, the illegal check, range error check, and type error
check are reported as part of the deadlock check.  For components, the
range error check, the type error check, and queue full check are
reported as part of the illegal check.

@node Verification Counter Examples
@section  Verification Counter Examples

@cindex counter example
@cindex event trace
A verification error does not only show the error it has detected, it
also shows @emph{where} it occurs.  Where an error occurs is specified
by means of a @code{counter example}, or an event trace.

Verifying

@example
@verbatiminclude examples/illegal-requires.dzn
@end example

gives:

@example
$ dzn verify doc/examples/illegal-requires.dzn
model: hello
h.hello
w.hello
<illegal>
@end example

at the end of running this trace, an @code{illegal} action occurs.  This
implies there is an inconsistency in the behavior of the component and
its interface, the contract is violated.  This can either be fixed by a
change to the interface behavior contract or by changing the component
behavior.

@node Interpreting Verification Errors
@section Interpreting Verification Errors

Understanding why a certain verification error occurs, or how to fix it,
is not always easy.  The simulator can help to interpret the error and
identify what is going on (@xref{Invoking dzn simulate}): It can show
the source locations where the error occurs and the state the interface(s)
and/or the component(s) are in.

@cindex event trace
The simulator can interpret the counter example from the verifier:
@example
$ dzn verify doc/examples/illegal-requires.dzn \
  | dzn simulate doc/examples/illegal-requires.dzn
error: illegal action performed in model illegal_requires
(header ((h) ihello provides) ((sut) illegal_requires component) ((w) ihello requires))
(state ((h)) ((sut)) ((w)))
doc/examples/illegal-requires.dzn:6:3: error: illegal
<external>.h.hello -> ...
... -> sut.h.hello
sut.w.world -> ...
... -> <external>.w.world
<illegal>
(state ((h)) ((sut)) ((w)))
doc/examples/illegal-requires.dzn:6:3: error: illegal
(trail "h.hello" "w.world" "<illegal>")
(labels "h.hello" "h.world")
(eligible)
@end example


@c *********************************************************************
@node Defensive Design
@chapter Defensive Design

As Dezyne is intended for operating system like applications,
qualifications like trustworthy, secure, safe, robust, and resilient come
to mind.  Here we discuss how these might be achieved.

If you are dealing with untrustworthy partners, you had better check
that they behave as agreed or otherwise stop the transaction.
Practically this means that one must not rely blindly on external
behavior and external input.

Dezyne interfaces allow you to specify what the implementation can
expect from their client and what they must do in return.  This is not
unlike a contract in terms of a pre-condition and a post-condition.
Moreover, verification can be used to exhaustively show that for each
Dezyne component these pre- and post-conditions hold.  This is what we
call @xref{Design by Contract} or @xref{Interface Contracts}.

Of course any interface contract can be written at the discretion of the
designer/programmer.  It can either be permissive or restrictive.  An
astute reader/thinker may realize that pre- and post-conditions are
transitive and eventually there will not be a Dezyne implementation
behind an interface.  This means that verification cannot be used to
assert upholding the pre- and post-conditions of the boundary interface.
For this boundary we might define a permissive interface (anything goes)
to guard the restricted interface and design an adapter component to
deal with every request outside of the restricted protocol.  This type
of component is referred to as an armor (see @xref{Armoring}).

@menu
* Interface Contracts::         Consequences of a breach of contract.
* Error Handling and Recovery::  Specifying Exceptional behavior.
* Armoring::                    Making a program robust.
@end menu

@node Interface Contracts
@section Interface Contracts

Dezyne does not have an exception mechanism like other languages.  An
exception mechanism is designed to prevent accidentally ignoring missed
pre- or post-conditions.  Instead, in Dezyne the interfaces establish
these restrictions by means of verification (@xref{Formal
Verification}).  So where traditional programming languages must handle
protocol violations using an exception mechanism at runtime, Dezyne
prevents them using the static verification checks@footnote{This is not
unlike languages that use static type analysis and checking (such as
@code{C++} and @code{Haskell}) versus languages that check types at
runtime}.  Interfaces in Dezyne are inherently complete with respect to
their event alphabet.  The generated code will accept every
@code{trigger} but give an @code{illegal} response.

The illegal response is mapped to @code{std::abort ()} in @code{C++}.
Note that for a fully verified Dezyne system, operated by clients that
adhere to the interface specifications, it is impossible for an
@code{illegal} response to be triggered.  In other words, when an
@code{illegal} is triggered, it means that some non-Dezyne code is
violating a protocol (interface specification).

@subsection Implicit interface constraints

Dezyne version 2.17.0 introduces implicit interface constraints.

Before 2.17.0, for a component to be compliant with its provides
interface(s), implementing a component required meticulously specifying
the same behavior in the component as in the provides interface(s);
therefore the code from the interface(s) is often repeated in the
component.

Since version 2.17.0 the provides interface(s) are implicitly applied as
a constraint on the component behavior.  This means that anything
disallowed by the interface, i.e., explicitly or implicitly marked as
@code{illegal}, is implicitly marked as @code{illegal} in the component
behavior.

How does this differ from the existing implicit illegal feature
@xref{Illegal} you may wonder.  The implicit @code{illegal} feature
leads to implicitly marked @code{illegal} behavior when a certain event
is omitted in a certain state.  The constraint feature marks as
@code{illegal} every event in the component behavior which is marked as
@code{illegal} in the corresponding state in the interface behavior.
This avoids the need to repeat the state and guarding from the interface
in the component.  An example of how this may reduce the behavior
specification of a component is the component @ref{proxy}.

@subsection Shared interface variables

Dezyne version 2.18.0 introduces shared interface variables.

Before 2.18.0, for a component to be able to act on the state of another
component through a guard, if or reply expression, it was necessary to
define and maintain a shadow copy of said state, either by inferring its
value or explicitly retrieving it via an action.

Now, components on either side of an interface can use and share the
value of their interface state variables by referring to them via their
respective ports in any expression.

@code{port}.@code{variable}.

@quotation Note
Access is limited to reading only, assignments from the component
behavior are prohibited.  Also, variables from ports marked
@code{external} are inaccessible, due to the process delay between both
sides of the interface.
@end quotation

@quotation Note
Shared interface variables are not inspected by @code{defer}.  As a
consequence an explicit component variable that changes state is
required to cancel a @code{defer}, see @ref{Component Defer} for more
information.
@end quotation

Shared interface state further enhances an existing Dezyne pattern,
where an @code{assert} event combined with a predicate guarding an
illegal is used to define a user defined functional property across
multiple components.  An example of this is used by the
@code{cruise_control} example below.  Here the cruise_control explicitly
checks for unwanted acceleration due to not resetting the throttle or
forgetting to stop the timer, as well as the converse property.

@example
@verbatiminclude examples/cruise-control-interfaces.dzn
@verbatiminclude examples/cruise-control.dzn
@end example

@quotation Note
This Dezyne pattern is intended to become a first class citizen in the
Dezyne language when the Module model type is added.
@end quotation

@node Error Handling and Recovery
@section Error Handling and Recovery

The errors of concern here are not programming or design errors, but
behavior that may occur and must be handled appropriately.  Like a file
open request because of a non existing file.  Therefore these errors are
at least runtime errors.

For a system, which behavior emerges as a result of its function and its
interaction with an unpredictable environment, the Pareto principle
holds for the distribution of its main functions and its error handling
across its behavior.  Typically about 10%-20% of the events that signal
an error, result in 90%-80% of the behavior associated with error
handling.  While 90%-80% of the events that relate to the main functions
of the system typically result in 10%-20% percent of the overall behavior
which is unrelated to error handling.

Error handling is most often a matter of redirecting the handling to the
party in charge to allow them to attempt recovery by retrying, continue
with reduced or gracefully degraded function, by failing safely
altogether, or continue as normal treating the error as a warning.

Dezyne is very effective in allowing engineers to discover the emergent
error behaviors--i.e., without having to resolve to devising test
scenarios, writing test code and running tests---as well as designing
the handling of the respective error conditions.

@node Armoring
@section Armoring

A common programming adagium is to be liberal what you accept and strict
in what you deliver.  Verification clearly depends on the accuracy with
which the behavior of the environment is described by its interface
specifications.  Any inconsistency with reality may lead the execution
of the code into unverified territory.  To avoid this we can apply an
approach called @emph{armoring}.  An armor is a defensive layer of
components that protects the armored components who rely on their
interface contracts from any behavior which would violate those
contracts.  An armoring component can be developed in Dezyne itself by
creating a permissive interface from the strict interface behavior and
letting the armor component map one behavior onto the other making sure
the permissive behavior never violates the strict behavior.

Consider this simple strict interface

@example
@verbatiminclude examples/istrict.dzn
@end example

used by this simple proxy component

@anchor{proxy}
@example
@verbatiminclude examples/proxy.dzn
@end example

Because the @code{istrict} interface is stateful, a problem occurs when
the enviroment would erroneously issue a second @code{p.request} event
before receiving an @code{r.notify}.

Now consider this permissive interface

@example
@verbatiminclude examples/ipermissive.dzn
@end example

that shares its event alphabet with @code{istrict}.  Being permissive
means that it will accept any of the events, regardless of the history.

Using the @code{ipermissive} interface we can derive a simple top armor
component

@example
@verbatiminclude examples/top_armor.dzn
@end example

and likewise, a bottom_armor component

@c What about iwatchdog?
@example
@verbatiminclude examples/bottom_armor.dzn
@end example

The permissive interface is to be used on both sides of the
@code{armored_system}.  The system connects each permissive interface to
a dedicated armor component, one for the top of the system and one for
the bottom.  Both protecting the inside component called @code{proxy}.

@example
@verbatiminclude examples/armor.dzn
@end example

@image{images/armor,,,,.png}

@node Code Integration
@chapter Code Integration

Dezyne code cannot be directly run or compiled into an executable, instead,
the Dezyne code generator is used to translate Dezyne into an
intermediate target language, such as @code{C++} (@xref{Invoking dzn
code}).

The Dezyne code generator will produce human readable code that strongly
resembles the Dezyne code without adding any unnecessary deviations.

@menu
* Integrating C++ Code::
* Foreign Component::
* Thread-safe Shell::
* Integrating Scheme Code::
@end menu

@node Integrating C++ Code
@section Integrating C++ Code

@cindex c++
This chapter describes the @code{C++} code that is generated by Dezyne
and the integration thereof.

@subsection Introduction

Every wellformed Dezyne model can be automatically converted into a
corresponding wellformed C++ representation.  This means that the
generated code will compile without compilation errors.  A verified
Dezyne model, once converted into a corresponding C++ representation,
exhibits the same behavior when executed as can observed in the
Dezyne simulation and verification of the model.

In Dezyne there are three model types: interface, component and system.

In this chapter we cover the code which is generated from these models
as well as the way the generated code might be integrated.

@subsection Interfaces

Dezyne turns an interface such as:

@example
@verbatiminclude examples/some_interface.dzn
@end example

into a C++ class representation similar to this:

@example
@verbatiminclude examples/some_interface.hh
@end example

Each event in an interface is a slot to which a value of something with
the appropriate callable signature can be assigned.  A callable value in
C++ is either: A function pointer or a functor (an object implementing
the function @code{::operator ())}, like a C++11 lambda.  For example:

@example
void foo () @{@}
some_interface port;
port.out.out_event = foo;
port.in.in_event = port.out.out_event;
@end example

Note that the last statement above short circuits the in_event to the
out_event as is described in the Dezyne interface.

@subsection Components

One could consider a component to be no more than the connecting part
between all of its ports.  For example:

@example
@verbatiminclude examples/some_component.dzn
@end example

in which case a simplistic C++ representation could look like this:

@example
@verbatiminclude examples/some_component.hh
@end example

Note that dezyne::ref allows short circuiting events which will be
initialized at a later stage.

However, this representation does not implement the semantics of Dezyne
(see @xref{Execution Semantics}).  In order to achieve this, the Dezyne
runtime manages the event exchange between components.  And of course
for all practical purpose and intent one expects a component behavior to
be more complicated to be able to comply with all of its interface
behaviors.

@subsection Systems

Along the same lines a Dezyne system may aggregate other components
and systems and bind them together by their ports.  For example:

@example
@verbatiminclude examples/some_system.dzn
@end example

or depicted in a diagram:

@image{images/some_system,2in,,,.png}

@subsection Integration

Constructing such a system using Dezyne is straightforward.  Every
model can be automatically converted into code and by the hierarchical
nature of Dezyne all components and systems slot together
automatically, however two facilities are required to allow this: the
dezyne runtime and the dezyne locator.  Both are provided by Dezyne.

In C++ the main function for this system might look like this:

@example
#include "some_system.hh"
#include "dezyne/runtime.hh"
#include "dezyne/locator.hh"
int
main ()
@{
  dezyne::locator loc;
  dezyne::runtime rt;
  loc.set (rt);
  //construct the system
  some_system system (loc);
  //connect the outer events directed at the system
  system.provided_port.out.event = []@{
    std::cout << "system.provided_port.out.event" << std::endl;
  @};
  system.required_port.in.event  = []@{
    std::cout << "system.required_port.in.event" << std::endl;
  @};
  //and finally fire some of the external events
  system.provided_port.in.event ();
  system.required_port.out.event ();
@}
@end example

Runtime: The runtime takes care of decoupling the events between the
caller and the callee when this is required.

Locator: The locator allows injecting the implementation behind a port
deep into the system from the outside.

@cindex injection, c++
In the example you can see that
the locator facility is also responsible for passing an instance of
the runtime into the system.  Injection example:

@example
interface Foo
@{
  in void bar ();
  behavior
  @{
    on bar:@{@}
  @}
@}
component some_component2
@{
  provides some_component2 provided_port;
  requires injected Foo required_port;
  behavior @{ /* ...  */ @}
@}
@end example

@example
int
main ()
@{
  dezyne::locator loc;
  dezyne::runtime rt;
  loc.set (rt);
  Foo foo;
  foo.in.bar = []@{/*no op*/@};
  loc.set (foo);
  some_component comp (loc);
  comp.provided_port.in.in_event ();
@}
@end example

@node Foreign Component
@section Foreign Component

We already saw how to connect code directly to event slots in the
interface.  If we desire to encapsulate this code, we can use a
component without a behavior@footnote{A foreign component is a component
without behavior in Dezyne.} to achieve this.  The code generator will
generate a similar C++ representation for components with and without
behavior.  The only difference is that a component without behavior
declares pure virtual functions which must be implemented by a struct of
class which inherits from the generated C++ representation.  Note that
this approach is not suitable to wrap a Dezyne component or system,
since it would add the Dezyne semantic constraints via the runtime
library a second time.  The derived struct or class must have the same
name as the component in Dezyne.  To avoid a naming conflict, the
generated representation with the same name as the Dezyne component is
placed into the @code{skel}@footnote{@code{skel} is short for skeleton.}
namespace.

It may not be obvious that we may run into a conflict when we put our
foreign component in a file with the same name as the component.  The
reasons for this are as follows.  Names introduced in Dezyne are also
used by the generated code to refer to component representations.  If a
component is not defined locally Dezyne import is mapped to a
@code{#include}.  This means that the actual implementation of a foreign
component must be in a file with the name derived from the component
name.  Therefore the component representation in the @code{skel}
namespace is not written to the same file, the code generator simply
refuses this.  The solution is to put foreign component definitions into
another file, for instance in the file of the system instantiating the
component.

When implementing the foreign component the compiler must also be able
to see the representation in the @code{skel} namespace.  The code
generator makes sure that the actual implementation inheriting the
@code{skel} representation is included directly after it.  Therefore we
do not have to include anything into the header file of our foreign
implementation.  However, if we put the actual definition into a
separate source file, we must include both the header file of the actual
foreign component as well as the header file declaring the @code{skel}
representation.

An example will help clarifying:

@example
@verbatiminclude examples/hello_foreign.dzn
@end example

Here we see an interface @code{ihello}, a @code{foreign} component, a
regular component @code{hello} and a system @code{hello_foreign} being
defined.

For C++ the code generator produces a @file{hello_foreign.hh} and a
@file{hello_foreign.cc} file.  Since @code{hello_foreign} instantiates
the component @code{foreign}, it will @code{#include} a file called
@file{foreign.hh}.  The contents of this file might look something like
this:

@example
@verbatiminclude examples/foreign.hh
@end example

Note the absence of an @code{#include} statement.

If we want to move all member function definitions from the header file
to a source file, we might write @file{foreign.cc} like this.

@example
@verbatiminclude examples/foreign.cc
@end example

Note the presence of @code{#include "hello_foreign.hh"} and remember
this already includes @file{foreign.hh}.


@node Thread-safe Shell
@section Thread-safe Shell

A Dezyne Thread-safe Shell guarantees safe use of a Dezyne system
component in a multi-threaded environment.  It also implements the use
of the @code{blocking} and the @code{defer} keywords.

@subsection Shell Syntax

Use the dzn command-line client to generate code and a thread-safe shell:

@example
  dzn code -l c++ -s SYSTEM FILE    (1)
@end example

Explanation:

1) Generates code for all components and interfaces referred to in the
SYSTEM component.  In addition a thread-safe shell is generated for
SYSTEM.

@subsection Semantics

A thread-safe shell wraps a Dezyne system component.  In addition to an
instance of the Dezyne component it contains a thread and an event
queue.  External code can call event functions on system ports.  The
thread-safe shell defers each external call by posting a function object
in the event queue.  A thread private to the thread-safe shell takes
deferred functions from the queue and executes them one by one.  Thus,
external calls are serviced in the order of arrival.

An external call of a provides port in event blocks until the
thread-safe shell private thread has completed the deferred function
call.  The external call blocks until a @code{reply} has been executed
for the input event port.  A subsequent call on a blocked port will block
until the prior call returns.

An external call of a requires port out event returns a soon as the
event call is scheduled.  The external call return is not synchronized
with the actual execution of the event by a thread-safe shell private
thread.

@subsection Shell Example

Generating C++ code with a thread-safe shell for component @code{SYS}
results in files: @code{SYS.hh}, @code{SYS.cc}, @code{BHV.hh} and
@code{IA.hh}.

A call of @code{SYS::pp.in.iv ()} captures input parameters by value to
prevent data races.  The call schedules a call to
@code{SYS::bhv.pp.in.iv ()} and blocks the calling thread until the
scheduled call returns.

A call of @code{SYS::rp.out.o ()} captures input parameters by value to
prevent data races.  The call schedules a call to
@code{SYS::bhv.rp.out.o ()} and returns immediately.

@example
component SYS
@{
  provides IA pp;
  requires IA rp;
  system
  @{
    BHV bhv;
    pp <=> bhv.pp;
    bhv.rp <=> rp;
  @}
@}
component BHV
@{
  provides IA pp;
  requires IA rp;
@}
extern int $int$;
interface IA
@{
  in void iv (int i);
  out void o (int i);
  behavior
  @{
    on iv: @{@}
    on optional: o;
  @}
@}
@end example

File SYS.hh:

@example
#ifndef SYS_HH
#define SYS_HH
#include #include #include #include #include "BHV.hh"
#include "IA.hh"
#include "IA.hh"
namespace dzn @{struct locator;@}
struct SYS
@{
  dzn::meta dzn_meta;
  dzn::runtime dzn_runtime;
  dzn::locator dzn_locator;
  BHV bhv;
  IA pp;
  IA rp;
  dzn::pump dzn_pump;
  SYS (dzn::locator const&);
@};
#endif // SYS_HH
@end example

File SYS.cc:

@example
#include "SYS.hh"
SYS::SYS (dzn::locator const& locator)
: dzn_meta@{"","SYS",0,@{&bhv.dzn_meta@},@{@}@}
, dzn_locator (locator.clone ().set (dzn_runtime).set (dzn_pump))
, bhv (dzn_locator)
, pp (bhv.pp)
, rp (bhv.rp)
, dzn_pump ()
@{
  pp.in.iv = [&] (int i)
  @{
    return dzn::shell (dzn_pump, [&,i] @{return bhv.pp.in.iv (i);@});
  @};
  rp.out.o = [&] (int i)
  @{
    return dzn_pump ([&,i] @{return bhv.rp.out.o (i);@});
  @};
  bhv.pp.out.o = std::ref (pp.out.o);
  bhv.rp.in.iv = std::ref (rp.in.iv);
  bhv.dzn_meta.parent = &dzn_meta;
  bhv.dzn_meta.name = "bhv";
@}
@end example

@unnumberedsubsec See also:

@itemize

@item @ref{Blocking},
@item @ref{The Dezyne command-line tools},
@end itemize

@node Integrating Scheme Code
@section Integrating Scheme Code

@quotation Note
The Scheme code generator is still considered experimental; use with
caution.
@end quotation

To enable the Scheme code generator, configure by doing something like

@example
./configure --enable-languages=scheme --with-courage
@end example

Dezyne comes with a code generator for GNU Guile @pxref{,,, guile, Guile
reference manual}.  Scheme is an interesting language for using with
Dezyne.  It supports a functional programming style that can be applied
in handwritten code.

@c Not only is Scheme much friendlier than C or C++ for prototyping
@c (@pxref{Scheme vs C, Why Scheme is More Hackable Than C,, guile, GNU
@c Guile Reference Manual}).

Program code written in a purely functional style is more reasonable
than imperative code and especially so for concurrent programs
(@pxref{Chapter 3,, Modularity Objects and State, sicp, Structure and
Interpretation of Computer Programs}).  The Scheme code for Dezyne
components that is generated by the code generator (@xref{Invoking dzn
code}) can still use assignments to store state in an imperative way,
but that is not a problem as this code is verified: the most tricky
aspects of the software are left to Dezyne!

@menu
* Namespace to Module::
@end menu

@node Namespace to Module
@subsection Namespace to Module

The Scheme code generator introduces the ``namespace to module'' feature
which means that a Dezyne file, when it contains a single namespace, is
assumed to describe a module, such as found in languages like GNU Guile
(@pxref{Modules, Guile modules,, guile, GNU Guile Reference Manual}),
JavaScript (Python, etc.).  Similarly, foreigns are assumed to live in
their own module, so that this module can be used/required/imported.

Things to note:

@itemize

@item
Dezyne files that define more than one namespace are not supported for
``namespace to module'',

@item
foreigns go into their own module,

@item
interfaces used by a foreign need to go into their own Dezyne file to
avoid introducing cyclic dependencies,

@item
avoid the name @code{foreign}, the class @code{<foreign>}

@item
foreigns that use the same interfaces need to form a chain of
@code{use-module} and @code{re-export} their port accessors
(@pxref{Using Guile Modules,,, guile, Guile reference manual}).

@end itemize


@c *********************************************************************
@node The Dezyne command-line tools
@chapter The Dezyne command-line tools

@menu
* Invoking dzn::                Running Dezyne commands.
* Invoking dzn anonymize::      Anonymizing a Dezyne file.
* Invoking dzn code::           Generating code from a Dezyne file.
* Invoking dzn exec::           Running an arbitrary command-line.
* Invoking dzn graph::          Generating graphs of Dezyne models.
* Invoking dzn hash::           Computing the cryptographic hash of a dzn-file.
* Invoking dzn hello::          A simple sanity check.
* Invoking dzn language::       Lookup and completion.
* Invoking dzn lts::            Manipulate and query an LTS.
* Invoking dzn parse::          Checking the syntax of Dezyne file.
* Invoking dzn simulate::       Simulating Dezyne models.
* Invoking dzn test::           Explore entire LTS state of a program.
* Invoking dzn trace::          Transform verify, code, and simulate traces.
* Invoking dzn traces::         Generate a set of traces.
* Invoking dzn verify::         Verifying Dezyne models.

@end menu

@node Invoking dzn
@section Invoking @command{dzn}

The @command{dzn} command is a front-end to Dezyne functions, such as
verification, code generation, simulation, etc.  Those functions all
have their own sub @code{command}:

@example
dzn @var{dzn-option}@dots{} @code{command} @var{command-option}@dots{} @file{FILE}...
@end example

Running @code{dzn} without a sub @var{command} shows a brief help text
and the list of available @command{dzn} commands.

The @var{dzn-option}s can be used with every @command{dzn} command and
can be among the following:

@table @code

@item --debug
@itemx -d
Enable debug output.

@item --help
@itemx -h
Display help on invoking @code{dzn}, and then exit.

@item --skip-wfc
@itemx -p
Skip well-formedness checking.

The well-formedness checking of a large program can take a significant
amount of time.  As the well-formedness check does not change a correct
@code{AST} in any way, it can be safely skipped when parsing a
previously checked and unmodified program (@xref{Invoking dzn parse}).

@item --threads=@var{n}
Invoke @code{lps2lts} with @option{--threads}=@var{n}.

@item --timings
@itemx -T
Show detailed Scheme and mCRL2 timing information.

@item --transform=@var{trans}
@itemx -t @var{trans}
Apply transformation @var{trans} after parsing.  Use @command{dzn --help
--verbose} to show all transformations.  This option can be used more
than once.  For example,

@example
dzn code -l dzn -t add-explicit-temporaries -t -o- normalize:compounds test.dzn
dzn code -l dzn -t 'inline-functions(f)' -t -o- normalize:compounds test.dzn
@end example

will inline function @code{f} and remove redundant compound-statements
created by the inlining.

@item --verbose
@itemx -v
Be more verbose, show progress.

@item --version
@itemx -V
Display the current version of @code{dzn}, and then exit.

@item --version-number
Display the current version-number of @code{dzn}, and then exit.  This
may simplify getting the version in environments where Dezyne is the
only program in use that conforms to the GNU coding standards
(@pxref{--version, standards for command-line interfaces,, standards,
GNU Coding Standards}).

@end table

@quotation Note
The @var{dzn-option}s are placed between @command{dzn} and the sub command,
e.g. to increase verbosity when using @command{dzn verify}, use
@example
dzn -v verify file.dzn
@end example
@end quotation

@node Invoking dzn anonymize
@section Invoking @command{dzn anonymize}

The @command{dzn anonymize} command can be used to write an
anonymized version of a Dezyne file to standard output.

@example
dzn @var{dzn-option}@dots{} anonymize ihello.dzn
@end example

Apart from excluding Dezyne keywords, the anonymizer also excludes
dzn-command specific flags and words, such as @code{-m,--model} and
@code{-t,--trail} etc.  So if you need to convey anonymized,
model-specific information with the anonymized Dezyne code, you may do
so by adding these as a comment:

@example
// dzn verify -m hello
// dzn simulate -m hello --trail=h.hello,h.return
@end example

As the names of include files will also be anonymized, it is recommended
to anonymize a preprocessed stream instead (@ref{Invoking dzn parse}):

@example
dzn parse -E hello.dzn | dzn anonymize - > anon.dzn
@end example

The @var{option}s can be among the following:

@table @code

@item --help
@itemx -h
Display help on invoking @code{dzn anonymize}, and then exit.

@end table

@node Invoking dzn code
@section Invoking @command{dzn code}

@cindex code generation
@cindex executable program
While the simulator (@xref{Invoking dzn simulate}) can interpret Dezyne
code directly, to create an executable program Dezyne uses a code
generator.

This code generator, the command @command{dzn code}, generates compilable
or runnable code for a Dezyne file, such as @code{C++}.  Usually---i.e.,
except for trivial cases---this generated Dezyne code is combined with
``handwritten'' code in the target language to create a Dezyne
application, @xref{Code Integration}.

When generating code for @code{C++}, a dependency file is generated as
@file{<output-directory>/.deps/<base>.dzn.dep} for use by the build
system.

@example
dzn @var{dzn-option}@dots{} code @var{option}@dots{} @file{FILE}@dots{}
@end example

If @file{FILE} is a directory, code is generated for all @file{.dzn}
files in that directory.

The @var{option}s can be among the following:

@table @code

@item --calling-context=@var{type}
@itemx -c @var{type}
Generate an extra parameter of @var{type} for every event.

@item --touch-empty-files
@itemx -t
When generating @code{C++} code, if an execution unit is empty, touch
it, creating an empty file for consistency.  This may remove an
irregularity from the build system.

@item --help
@itemx -h
Display help on invoking @command{dzn code}, and then exit.

@item --import=@var{dir}
@itemx -I @var{dir}
Add directory @var{dir} to the import path.

@item --init=@var{PROCESS}
When generating @code{mCRL2} code, use init @var{PROCESS}.  For other
language backends, this options is ignored.

@item --language=@var{language}
@itemx -l @var{language}
Generate code for language @var{language}.

@item --model=@var{model}
@itemx -m @var{model}
Generate a trivial main for @var{model}.  This ``generated main'' can
execute an event trace read from stdin, and writes a code trace to
stderr.  @xref{Getting Started}.

@item --no-constraint
@itemx -C
Do not use a constraining process.

@item --no-unreachable
@itemx -U
Do not generate tags for the unreachable code check.

@item --output=@var{dir}
@itemx -o @var{dir}
Write output to directory @var{dir} (use @code{-} for standard output).

@item --queue-size=@var{size}
@itemx -q @var{size}
When generating @code{mCRL2} code, use component queue size @var{size}
for verification, the default is @code{@value{queue-size}}.  For other
language backends, this options is ignored.

@item --queue-size-defer=@var{size}
When generating @code{mCRL2} code, use defer queue size @var{size} for
verification, the default is @code{@value{queue-size-defer}}.  For other
language backends, this options is ignored.

@item --queue-size-external=@var{size}
When generating @code{mCRL2} code, use external queue size @var{size}
for verification, the default is @code{@value{queue-size-external}}.
For other language backends, this options is ignored.

@item --shell=@var{model}
@itemx -s @var{model}
Generate thread-safe system shell for model @var{model}.  This option
can be used multiple times.  @xref{Thread-safe Shell}.

@end table

@node Invoking dzn exec
@section Invoking @command{dzn exec}

The @command{dzn exec} command runs any command with arguments.

@example
dzn @var{dzn-option}@dots{} exec @var{option}@dots{} @file{command-line}@dots{}
@end example

The @file{command-line} can be anny command-line to run.  This is
helpful for a Docker container that has @command{dzn} as its @emph{entry
point}.

Running

@example
dzn exec ltsconvert hello.aut hello.dot
@end example

runs @command{dzn parse} and returns the preprocessed stream for
@file{examples/hello.dzn}.

The @var{option}s can be among the following:

@table @code

@item --help
@itemx -h
Display help on invoking @code{dzn exec}, and then exit.

@item --verbose
@itemx -v
Show the command to be executed.

@end table

@node Invoking dzn graph
@section Invoking @command{dzn graph}

The @command{dzn graph} command can be used to generate different
graphs from a Dezyne model.

@example
dzn @var{dzn-option}@dots{} graph @var{option}@dots{} @file{FILE}
@end example

The @var{option}s can be among the following:

@table @code

@item --backend=@var{type}
@itemx -b @var{type}
Generate a diagram using backend @var{type}; one of @code{dependency},
@code{lts}, @code{state}, or @code{system} and write it to standard
output.  The default is @code{system}.

The @code{state} diagram can simplified using options @code{--hide} and
@code{--remove}.

@cindex Aldebaran
@cindex @code{lts}
Under the hood, @code{lts} and @code{state} use the Dezyne VM.  LTSs can
be queried and manipulated using @command{dzn lts} (@ref{Invoking dzn
lts}) and the @url{https://mcrl2.org,mCRL2} tooling.

@quotation Note
Generating an LTS for a large component or system using the VM can be
very time-consuming.  For generating an LTS using the verification
engine, see (@ref{Invoking dzn verify}) and (@ref{Invoking dzn traces}).
@end quotation

@item --format=@var{format}
@itemx -f @var{format}
Print trace in format @var{format}; one of @code{aut}, @code{dot}, or
@code{json}.  For @code{--lts} the default is @code{aut}, for other
formats the default is @code{dot}.

@quotation Note
The @code{json} can be processed by
@url{https://gitlab.com/rma.wieringa/dezyne-p5,Dezyne-P5} to draw state
and system diagrams in a browser.
@end quotation

@item --help
@itemx -h
Display help on invoking @command{dzn graph}, and then exit.

@item --hide=@var{hide}
@itemx -H @var{hide}
Generate a state diagram and hide @var{hide} from the transitions; one
of @code{labels} (hide everything), @code{actions} or @code{returns}.

@item --import=@var{dir}
@itemx -I @var{dir}
Add directory @var{dir} to the import path.

@item --model=@var{model}
@itemx -m @var{model}
Generate graph for model @var{model}.  The default is to use the most
``interesting'' model.

@item --queue-size=@var{size}
@itemx -q @var{size}
Use component queue size @var{size} for exploration, the default is
@code{@value{queue-size}}.

@item --queue-size-defer=@var{size}
Use defer queue size @var{size} for exploration, the default is
@code{@value{queue-size-defer}}.

@item --queue-size-external=@var{size}
Use external queue size @var{size} for exploration, the default is
@code{@value{queue-size-external}}.

@item --remove=@var{vars}
@itemx -R @var{vars}
Generate a state diagram and remove variables from nodes @var{remove};
one of @code{ports} or @code{extended}.

@code{ports} Hides the state of the component's or system's ports,
@code{extended} hides the interface's or component's extended state,
i.e., all but the main (first) state variable and implies @code{ports}.

@end table

@node Invoking dzn hash
@section Invoking @command{dzn hash}

The @command{dzn hash} command computes the SHA1 hash of a Dezyne file
and its imports.

@example
dzn @var{dzn-option}@dots{} hash @var{option}@dots{} @file{FILE}@dots{}
@end example

The @file{FILE} must be a Dezyne-file.  The hash can be used for caching
or verification purposes.

Using @option{--verbose} on @command{dzn} also prints the name of the
file.  Running

@example
dzn --verbose hash examples/hello.dzn
@end example

prints a hash of @file{hello.dzn} and its imports.  It matches the
output of running

@example
dzn parse --no-directives examples/hello.dzn | sha1sum
@end example

The @var{option}s can be among the following:

@table @code

@item --help
@itemx -h
Display help on invoking @code{dzn hash}, and then exit.

@end table

@node Invoking dzn hello
@section Invoking @command{dzn hello}

The @command{dzn hello} command can be used to test your installation;
it echos ``hello'' to standard output.

@example
dzn @var{dzn-option}@dots{} hello
@end example

The @var{option}s can be among the following:

@table @code

@item --help
@itemx -h
Display help on invoking @code{dzn hello}, and then exit.

@item --runtime
Display the (installed) location of the runtime, and then exit.

@end table

@node Invoking dzn language
@section Invoking @command{dzn language}

The @command{dzn language} command produces Dezyne language completion
results and location information.  It can be used by an editor or IDE to
create a rich editing experience.

@example
dzn @var{dzn-option}@dots{} language @var{option}@dots{} @file{FILE}
@end example

The @var{option}s can be among the following:

@table @code

@item --complete
@itemx -c
Show completion result; this is the default action.

@item --help
@itemx -h
Display help on invoking @command{dzn language}, and then exit.

@item --import=@var{dir}
@itemx -I @var{dir}
Add directory @var{dir} to the import path.

@item --offset=@var{offset}
Use offset @var{offset} to determine context.

@item --line=@var{line},@var{column}
@itemx --point=@var{line},@var{column}
@itemx -p @var{line},@var{column}
Calculate offset from line @var{line} and column @var{column}.

@item --lookup
@itemx -l
Show lookup result.

@c XXX TODO: is dzn language --verbose really dzn --debug language?
@item --verbose
@itemx -v
Display input, parse tree, offset, context and completions.

@end table

@node Invoking dzn lts
@section Invoking @command{dzn lts}

@cindex Aldebaran
@cindex @code{lts}
@cindex labeled transition system
The @command{dzn lts} command can be used to manipulate and query a
labeled transition system (@var{lts}) in Aldebaran (@code{aut}) format
(@xref{Invoking dzn graph}, @xref{Invoking dzn verify}, @xref{Invoking
dzn traces}).

@example
dzn @var{dzn-option}@dots{} lts @var{option}@dots{} [@file{FILE}]@dots{}
@end example

The @var{option}s can be among the following:

@table @code

@item --cleanup
@itemx -c
Rewrite mCRL2 labels to Dezyne, optionally remove @var{prefix} as
specified with @option{--prefix}.

@item --deadlock
@itemx -d
Detect deadlock in @var{lts} (after introduction of failures) and
produce a witness.

@item --exclude-illegal
Remove edges leading to illegal (in combination with
@option{--failures}).

@item --failures
@itemx -f
Introduce a failure for each 'optional' event into the @file{lts}.

@item --help
@itemx -h
Display help on invoking @command{dzn lts}, and then exit.

@item --illegal
@itemx -i
Detect whether @file{lts} contains @code{<illegal>} labels.

@item --livelock
@itemx -l
Detect tau-loops in @file{lts} and produce a witness.

@item --deterministic-labels=@var{label}[,@var{label}@dots{}]
@itemx -n @var{label}[,@var{label}@dots{}]
Detect whether @file{lts} is deterministic by detecting multiple edges
of @var{label} from a single state, and produce a witness.

@item --prefix=@var{prefix}
Optional @var{prefix} for @option{--cleanup}

@item --tau=@var{event}[,@var{event}@dots{}]
@itemx -t @var{event}[,@var{event}@dots{}]
Hide all @var{event}s from @file{lts}.
@item --exclude-tau=@var{event}[,@var{event}@dots{}]
Exclude given @var{event}s from '@option{--tau}' list.


@item --single-line
@itemx -s
Report each error including its trace (witness) on a single line.

@end table

@node Invoking dzn parse
@section Invoking @command{dzn parse}

The @command{dzn parse} command parses a Dezyne file and reports any
errors, both syntax errors as well as ``well-formedness'' errors.  The
Dezyne parser consists of three stages:

@enumerate
@item
The PEG parser creates a raw @code{parse-tree}@footnote{The @command{dzn
language} command (@xref{Invoking dzn language}) works on this raw
@code{parse-tree}.},
@item
The @code{parse-tree} is converted into the abstract syntax tree
(@code{AST}),
@item
A number of so-called ``well-formedness'' checks are performed on the
@code{AST} that ascertain type correctness and detect semantic errors
(@xref{Well-formedness}),
@item
After parsing, some commands perform a normalization on the @code{AST}.
@end enumerate

The well-formedness checking of a large program can take a significant
amount of time.  As the well-formedness check does not change a correct
@code{AST} in any way, it can be safely skipped when parsing a
previously checked and unmodified program (@xref{Invoking dzn}).

Usually, the parser is invoked implicitly by commands like @command{dzn
verify} and @command{dzn code}.  It can be useful to do an explicit
check for errors, for example after saving a Dezyne file (@xref{The
Perfect Setup}).  Its syntax is:

@example
dzn @var{dzn-option}@dots{} parse @var{option}@dots{} @file{FILE}
@end example

The @var{option}s can be among the following:

@table @code

@item --preprocess
@itemx -E
Resolve imports and produce a content stream.  This pre-processed
content can also be processed later by the parser and it has the
advantage of being independent of the file-system.

@item --no-directives
@itemx -D
Do not include @code{#file} and @code{#imported} directives in
pre-processed stream, removing the need to use, know, or learn
@code{grep -v ^#}.  @option{--no-directives} implies
@option{--preprocess}.

@item --help
@itemx -h
Display help on invoking @command{dzn parse}, and then exit.

@item --import=@var{dir}
@itemx -I @var{dir}
Add directory @var{dir} to the import path.

@item --list-models
List the Dezyne models defined in the file, with their type.

@item --locations
@itemx -L
Show locations in output @var{ast}.

@item --model=@var{model}
@itemx -m @var{model}
Only output @var{ast} for model @var{model}.

@item --parse-tree
@itemx -t
Write the raw @var{peg} parse tree, skip generating a full @var{ast},

@item --output=@var{file}
@itemx -o @var{file}
Write @var{ast} to @var{file}, use ``-'' for standard output.

@end table

@node Invoking dzn simulate
@section Invoking @command{dzn simulate}

The @command{dzn simulate} command starts a simulation run.

Under the hood, @command{dzn simulate} uses the Dezyne VM.  The
simulator can be used to explore Dezyne models (interfaces, components,
and systems), and to interpret error traces (witnesses) from the
verification engine (@xref{Getting Started}).  It shows code locations,
state, and state transitions and produces friendly error messages.  The
simulator and verification both report the same errors (@xref{Formal
Verification}).  The simulator, however, only reports errors that it
encounters while interpreting a specific event trace.  The verifier
performs an exhaustive search for errors but only produces a witness
and does not report any context information.  Its syntax is:

@example
dzn @var{dzn-option}@dots{} simulate @var{option}@dots{} @file{FILE}
@end example

The @var{option}s can be among the following:

@table @code

@item --format=@var{format}
@itemx -f @var{format}
Print trace in format @var{format}; one of @code{diagram}, @code{event},
or @code{trace}.  The default is @code{trace}.

@item --help
@itemx -h
Display help on invoking @command{dzn simulate}, and then exit.

@item --import=@var{dir}
@itemx -I @var{dir}
Add directory @var{dir} to the import path.

@item --internal
@itemx -i
Display internal events when using the @code{diagram} trace format.

@item --locations
@itemx -l
Display locations in the trace, this implies @option{--format=@code{trace}}.

@item --model=@var{model}
@itemx -m @var{model}
Start simulating @var{model}.  The default is the most ``interesting''
model.

@item --no-compliance
@itemx -C
Do not run the compliance check.

@item --no-deadlock
@itemx -D
Do not run the deadlock check at the end of the trail (EOT).

@item --no-interface-determinism
Do not run the observable non-determinism check on interfaces.

@item --no-interface-livelock
Do not run the interface livelock check at the end of the trail (EOT).

@item --no-queue-full
@itemx -Q
Do not run the external queue-full check at the end of the trail (EOT).

@item --no-refusals
@itemx -R
Do not run the compliance check for the failures model refusals check at
the end of the trail (EOT).

@item --queue-size=@var{size}
@itemx -q @var{size}
Use component queue size @var{size} for simulation, the default is
@code{@value{queue-size}}.

@item --queue-size-defer=@var{size}
Use defer queue size @var{size} for simulation, the default is
@code{@value{queue-size-defer}}.

@item --queue-size-external=@var{size}
Use external queue size @var{size} for simulation, the default is
@code{@value{queue-size-external}}.

@item --strict
@itemx -s
Use strict matching of trail, i.e., the trail must contain all
observable events.

@item --trail=@var{trail}
@itemx -t @var{trail}
Use trail @var{trail}.  The default is to read from @code{stdin}.

@item --verbose
@itemx -v
Display non-communication steps in the trace, this implies
@option{--format=@code{trace}}, @option{--locations}.

@end table

@node Invoking dzn test
@section Invoking @command{dzn test}

The @command{dzn test} command can be used to explore a program's entire
LTS state space.

@example
dzn @var{dzn-option}@dots{} test @var{option} hello.aut ./hello
@end example

The @var{option}s can be among the following:

@table @code

@item --format=@var{format}
@itemx -f @var{format}
Print @code{LTS} in format @var{format}; one of @code{aut}, or
@code{dot}.  The default is @code{aut}.

@item --help
@itemx -h
Display help on invoking @code{dzn test}, and then exit.

@item --retry=@var{retry}
@itemx -f @var{retry}
Retry @var{retry} times upon failure.  Use @code{0} to retry infinite
times.

@end table

@node Invoking dzn trace
@section Invoking @command{dzn trace}

The @command{dzn trace} command is a pseudo-filter to convert between
different trace formats:

@c This is kind-of define by example; should we create a more formal
@c definition?  Where?

@table @code
@item event trace (trail)
An event trace or @emph{trail} is a list of event names observable by
interacting with a Dezyne model, for example, for
@file{doc/examples/hello-world.dzn}:

@example
p.hello
p.world
p.return
@end example

@item event trace (character separated)
Some tools, such as the simulator also read an event trace separated by
a comma or a space:

@example
 p.hello,p.world,p.return
"p.hello p.world p.return"
@end example

@item code trace (arrow trace)
The Dezyne executable code can produce a trace showing the sender and
the receiver of an event on the same line:

@example
<external>.p.hello -> sut.p.hello
<external>.p.world <- sut.p.world
<external>.p.return <- sut.p.return
@end example

@item simulator trace (split-arrow trace)
The simulator produces a trace showing the sender and the receiver of an
event both on their own line:

@example
<external>.p.hello -> ...
... -> sut.p.hello
... <- sut.p.world
<external>.p.world <- ...
... <- sut.p.return
<external>.p.return <- ...
@end example

which is especially useful when the lines are prefixed with location
information.

@end table

The @command{dzn trace} command reads arrow traces and converts them to
a code trace (the default) or an event trace.  A split-arrow trace can
also be converted to an ASCII sequence diagram.  Its syntax is:

@example
dzn @var{dzn-option}@dots{} trace @var{option}@dots{} [@file{FILE}]
@end example

The @var{option}s can be among the following:

@table @code

@item --format=@var{format}
@itemx -f @var{format}
Display trace in format @var{format}, one of @code{diagram},
@code{event}, @code{json}, or @code{sexp}.  The default is @code{code}.

@quotation Note
The @code{json} can be processed by
@url{https://gitlab.com/rma.wieringa/dezyne-p5,Dezyne-P5} to draw
a trace diagram in a browser.
@end quotation

@item --help
@itemx -h
Display help on invoking @command{dzn trace}, and then exit.

@item --internal
@itemx -i
Show communication between components in the system.  When using the
option @option{--format=diagram} on a system trace, the communication
between components in the system is hidden by default.

@item --locations
@itemx -L
Show locations in output.

@item --meta
@itemx -m
When using @option{format=event} also show meta-events, such as
@code{<defer>} and @code{<illegal>}.

@item --trace=@var{trace}
@itemx -t @var{trace}
Use trace @var{trace}.  The default is to read from standard input.

@end table

@node Invoking dzn traces
@section Invoking @command{dzn traces}

@cindex Aldebaran
@cindex @code{lts}

The @command{dzn traces} command generates an exhaustive set of event
traces or trails for a behavioral Dezyne model.  It can also be used to
generate an @var{lts} in Aldebaran format (@xref{Invoking dzn lts},
@xref{Invoking dzn graph}, @xref{Invoking dzn verify}).

Under the hood, @command{dzn traces} uses @command{dzn code} and mCRL2.

@example
dzn @var{dzn-option}@dots{} traces @var{option}@dots{} @file{FILE}
@end example

The @var{option}s can be among the following:

@table @code

@item --flush
@itemx -f
Include @code{<flush>} events in trace.

@item --help
@itemx -h
Display help on invoking @command{dzn traces}, and then exit.

@item --illegal
@itemx -i
Include traces that lead to an illegal.

@item --import=@var{dir}
@itemx -I @var{dir}
Add directory @var{dir} to the import path.

@item --lts
@itemx -l
Instead of generating trace files, generate an @var{lts} in Aldebaran
format.

@item --model=@var{model}
@itemx -m @var{model}
Generate traces for model @var{model}.

@item --no-constraint
@itemx -C
Do not use a constraining process.

@item --output=@var{dir}
@itemx -o @var{dir}
Write trace files to directory @var{dir}.

@item --queue-size=@var{size}
@itemx -q @var{size}
Use component queue size @var{size} for generation, the default is
@code{@value{queue-size}}.

@item --queue-size-defer=@var{size}
Use defer queue size @var{size} for trace generation, the default is
@code{@value{queue-size-defer}}.

@item --queue-size-external=@var{size}
Use external queue size @var{size} for trace generation, the default is
@code{@value{queue-size-external}}.

@item --traces
@itemx -t
Generate trace files, this is the default.  Using @option{--traces} will
generate trace files even when @option{--lts} is used.

@end table

@node Invoking dzn verify
@section Invoking @command{dzn verify}

The @command{dzn verify} command exhaustively checks a Dezyne file for
verification errors in Dezyne models.  @xref{Formal Verification}.

@example
dzn @var{dzn-option}@dots{} verify @var{option}@dots{} @file{FILE}@dots{}
@end example

If @file{FILE} is a directory, all @file{.dzn}-files in that directory
are verified.

The @var{option}s can be among the following:

@table @code

@item --all
@itemx -a
This is a deprecated alias for @option{-k,--keep-going}.

@item --help
@itemx -h
Display help on invoking @command{dzn verify}, and then exit.

@item --import=@var{dir}
@itemx -I @var{dir}
Add directory @var{dir} to the import path.

@item --keep-going
@itemx -k
Show all errors, i.e., keep going after finding an error.  By default,
verification stops after finding a verification error.

@item --model=@var{model}
@itemx -m @var{model}
Limit verification to @var{model}, and for a behavioral component
model, to its interfaces.

@quotation Note
Verification cannot be limited to @code{system} component models;
verifying a system model is a no-op@footnote{The compositional property
of the Dezyne component-based programming paradigm guarantees that the
verification of a @code{system} component model amounts to the
verification of all its @code{interface} models and behavioral
@code{component} models.}.
@c XXX TODO: reference to compositional quality/property
@end quotation

@item --no-constraint
@itemx -C
Do not use a constraining process.

@item --no-interfaces
Do not verify interfaces.

@item --no-unreachable
@itemx -U
Disable the unreachable code check.  For large models the unreachable
code check may have a serious performance impact.

@item --out=@var{format}
@cindex Aldebaran
@cindex @code{lts}
Run a partial verification pipeline to produce @var{format}.

Interesting formats are @code{mcrl2}, @code{aut},
@code{aut-dpweak-bisim}, @code{aut-weak-trace}, and
@code{aut+provides-aut}.  Use @option{--out=help} for a full list.

The verification pipeline starts by generating @code{mCRL2} code, which
is converted into an @var{lps} and then into an @var{lts}
(@xref{Invoking dzn lts}).  The @var{lts} is then manipulated further.

Using the @option{--debug} on @command{dzn} (@xref{Invoking dzn}) shows
the pipelines with all their commands that are being used, ready for
use on the command line.

@item --queue-size=@var{size}
@itemx -q @var{size}
Use component queue size @var{size} for verification, the default is
@code{@value{queue-size}}.

@item --queue-size-defer=@var{size}
Use defer queue size @var{size} for verification, the default is
@code{@value{queue-size-defer}}.

@item --queue-size-external=@var{size}
Use external queue size @var{size} for verification, the default is
@code{@value{queue-size-external}}.

@end table

@node Dezyne Language Reference
@chapter Dezyne Language Reference

Dezyne is a component based language as well as a method for the
development of event-driven systems.  The language has formal semantics,
which is coherently expressed in: a textual representation, a graphical
representation, a mathematical representation, a source code
representation, and the observable behavior of a machine executing the
resulting program.  The concepts available in the language denote the
different properties@footnote{ Structural: events and their direction in
an interface, ports on a component, components in a system, bindings
between the ports; behavioral: guarded triggers performing actions |
assignments | if-else | functions} that can be observed and have meaning
in one or more of the representations: textual, graphical, mathematical,
program and execution.

The @code{C}-like syntax of Dezyne should give it a familiar feel to
many programmers.  Dezyne has some unique language concepts and syntax
elements that are described in this chapter.

@menu
* Lexical Analysis::            Tokens, separators and whitespace.
* Dezyne Files::                What goes into a Dezyne file?
* Types and Expressions::       Manipulating data in Dezyne.
* Interfaces::                  Defining contracts for components and systems.
* Components::                  Defining a program's behavior in Dezyne.
* Systems::                     Decomposing a system.
* Namespaces::                  Avoiding name collision.
@end menu

@node Lexical Analysis
@section Lexical Analysis

@cindex parser
@cindex parsing
@cindex PEG
Dezyne is a @code{C}-like language.  This means that identifiers must be
separated by either whitespace, delimiters or operators and is otherwise
whitespace invariant.  The Dezyne parser is defined using a partial
expression grammar or ``PEG'' (@pxref{PEG Parsing,,, guile, GNU Guile
Reference Manual}).

@menu
* Identifiers::                 Choosing names.
* Keywords::                    Restricted words.
* Operators::                   Building blocks for expressions.
* Delimiters::                  Constructing lists.
* Lexical Scoping::             Locality of names.
* Comments::                    Explanations for human readers.
@end menu

@node Identifiers
@subsection Identifiers

In Dezyne identifiers are used to name objects like interfaces,
components, events, user defined types, variables, etc.  A keyword
cannot be used as an identifier and identifiers are case-sensitive.

@example
identifier ::= [a-zA-Z_][a-zA-Z0-9_]*
@end example

An identifier starts with a letter or an underscore, which can be
followed by further letters, digits, or underscores.  The following are
all valid identifiers:

@example
p, hello, Alarm, turn_on, VALUE_123, _
@end example

@quotation Note
That by convention Dezyne identifiers are also used in the target
language, however the target language may impose further restrictions on
identifiers.
@end quotation

@node Keywords
@subsection Keywords

The following list shows identifiers that are reserved words in Dezyne,
or @emph{keywords}.  These keywords may not be used as an identifier
name.

@example
behavior        blocking        bool            component
defer           else            extern          external
enum            false           if              illegal
import          inevitable      injected        inout
interface       in              invariant       namespace
on              optional        otherwise       out
provides        reply           requires        return
subint          system          true
@end example

@node Operators
@subsection Operators

Dezyne uses infix notation for expressions.  The following are operators
in Dezyne:
@example
||      &&      =>      !
+       -
<       >       <=      >=      ==      !=      <=>
@end example

@node Delimiters
@subsection Delimiters

The following are delimiters in Dezyne, for introducing lists:

@example
(       )       @{       @}       $
@end example

and for elements in lists:

@example
,       .       ;       =
@end example

@node Lexical Scoping
@subsection Lexical Scoping

A lexical @emph{scope} adds locality to a name.  Names in one lexical
scope do not interfere (collide or shadow) with another scope.
Referring to a scoped identifier

@example
reference ::= scope* identifier
scope ::= identifier "."
@end example

Dezyne defines the following scopes:

@table @code
@item enum
The field values of an enum:

@example
enum result @{TRUE, FALSE, ERROR@};
@end example

are referenced to by using the enum type name as scope:

@example
result.TRUE
@end example

@item interface
A type defined in an interface:

@example
interface ihello
@{
   enum result @{TRUE, FALSE, ERROR@};
@}
@end example

can be used in a component, e.g., to define a variable:

@example
ihello.result status = ihello.result.TRUE;
@end example

@item behavior
All definitions in a behavior are local to that behavior and cannot be
referenced from outside it@footnote{This may change when Dezyne gains
support for hierarchical behaviors, a.k.a. submachines.},

@item port
A port is an interface instance; events that are communicated over a
port use the name of the port as their scope:

@example
provides ihello p;
@dots{}
on p.hello (): p.world ();
@end example

@item instance
An @code{instance} (or component instance), is an instance of a
component.  A port defined in a component

@example
component hello
@{
  provides ihello p;
  requires ihello r;
@}

@end example

can be referenced to by using the component instance name as their scope

@example
component sys
@{
  provides ihello sp;
  requires ihello sr;
  system
  @{
    hello h;
    sp <=> h.p;
    h.r <=> sr;
  @}
@}
@end example

@item namespace
Types defined in a namespace are referenced to by using the name of the
namespace as their scope.
@c TODO add example
@end table

@node Comments
@subsection Comments

Dezyne supports single-line and multi-line comments very similar to
@code{C}.  Multi-line comments may be nested.  All characters part of a
comment are skipped by the parser.

@example
/* This is an example of multi-line comment.
 * The line below is ignored also:
 * this component implements...
 */
component hello
@{
  provides ihello p; // a single-line comment
@}
@end example

@node Dezyne Files
@section Dezyne Files

Dezyne types, interfaces, and components are organized in files.  A
file, with extension '.dzn' by convention, may contain zero or more of
type definitions, interfaces, and/or components.

The toplevel Dezyne program text is defined as follows:

@example
text ::= root
root ::= (import | data-expression
           | namespace | type | function | interface | component)*
@end example

An interface can refer to global types and functions (since 2.20), a
component can refer to global types, functions (since 2.20), interfaces
and other components.  An explicit @code{import} clause is needed when
the referred information is defined in another file.

@subsection Import

@cindex file import
@cindex import
An @code{import} clause makes available all types, interfaces and
components that are defined in another file.  From an imported interface
or component the 'public' parts are available, i.e., all information but
the interface or component behavior, or the component system details.

@example
import    ::= "import" (file-name "/")* file-name ";"
file-name ::= [a-zA-Z0-9_+.-]+
@end example

@quotation Note
That by convention the basename of the Dezyne file-name is used as the
target language basename, however the target platform may impose further
restrictions on a file-name.
@end quotation

By convention, Dezyne files use the extension @code{.dzn}.  Some
examples:

@example
import file-name.dzn;
import ../global-types.dzn;
import some/directory/prefix/library.dzn;
@end example

An imported file may contain imports itself, these are also imported.
When a file occurs twice in the resulting set of imports, it is expanded
only once.  This avoids introducing duplicate definitions.  Mutually
recursive imports are allowed (@xref{Invoking dzn parse}).

@node Types and Expressions
@section Types and Expressions

In Dezyne all variables and constants are typed.  A number of type
constructs are available.

@example
state-type      ::= bool / enum / subint / void
data-type       ::= extern
type            ::= state-type | data-type
@end example

@code{type}s are used for event reply types, variables,
function parameters, function, function return types, and function call
arguments.  @code{data-type}s are used for event and action parameters.
Currently, events cannot have @code{state-type}s parameters;
only @code{data-type}s.

Before Dezyne 2.19.0, the event reply type, and function return type,
where restricted to state-types. As of Dezyne 2.19.0, data-types
are also allowed.

@menu
* Void::                        Definitions without type.
* Bool::                        Builtin boolean type.
* Enum::                        Enumerated user types.
* Subint::                      Integer user types.
* Extern Data Type::            Foreign data user types.
* Expressions::                 Constants and data.
@end menu

@node Void
@subsection @code{void}

@code{void} is used for defining untyped events and functions, e.g.,

an event without reply value:

@example
in void hello ();
@end example

a function without return value:

@example
void foo ()
@{
  world;
@}
@end example

@node Bool
@subsection @code{bool}

@cindex bool type
@cindex true
@cindex false
Dezyne has a builtin boolean type @code{bool} with constants
@code{false} and @code{true}.

Available boolean operators are:

@table @code
@item !b
Logical negation of a boolean expression,
@item b1 && b2
Logical and of two boolean expressions,
@item b1 || b2
Logical or of two boolean expressions,
@item b1 == b2
Logical implies of two boolean expressions,
@item b1 => b2
Equality of two boolean expressions,
@item b1 != b2
Inequality of two boolean expressions,
@end table
where @code{b}, @code{b1}, and @code{b2} are boolean expressions.

It is used to define boolean events

@example
in bool test ();
@end example

boolean variables

@example
bool idle = true;
@end example

and parameters and functions

@example
bool negate (bool input)
@{
  return !input;
@}
@end example

The implies operator (@code{=>}) is available as of Dezyne 2.19.0.
The expression @code{b1 => b2} expresses that if condition @code{b1} hold
than also condition @code{b2} should hold. Note that we have the equivalence

@example
b1 => b2   ==  !b1 || b2
@end example


@node Enum
@subsection @code{enum}

@cindex enum type
An interface or component can specify a user defined enumerated
type.  Such a type has a name and a list of values.

@example
enum   ::= "enum" identifier "@{" fields "@}" ";"
fields ::= identifier ("," identifier)* ","?
@end example

An example:

@example
enum result @{FALSE,TRUE,ERROR@};
@end example

where @code{enum} is a keyword; this defines the enum type @code{result}
with three values.

In expressions the enum values are referred to with a dot notation:
@code{result.FALSE}.

Available enum operators are:

@table @code
@item e1 == e2
Equality of two enum expressions,
@item e1 != e2
Inequality of two enum expressions,
@item v.ERROR
A field-test: testing the value of an enum variable, denoted by
@code{v.ERROR}, which is shorthand for @code{v == result.ERROR}
@end table
where @code{e1} and @code{e2} denote enum expressions, and @code{v} an
enum variable of type @code{result}.

@node Subint
@subsection @code{subint}

@cindex integer type
@cindex subint type
The integer type is available in Dezyne in a restricted way@footnote{the
subint definition allows range checking and prevents accidental
unboundedness during model checking}: only a finite contiguous subrange
of integer numbers can be used.  An explicit type definition is needed
for each subset, where a @code{C}-like syntax is used.

@example
subint  ::= "subint" identifier "@{" range "@}" ";"
range   ::= integer ".." integer
integer ::= ("-")? [0-9]+
@end example

An example:

@example
subint int @{-1..2@};
@end example

where @code{subint} is a keyword.  This defines the finite type
@code{int} with possible values -1, 0, 1, and 2.  Available integer
operators are:

@table @code

@item comparison

@table @code
@item i1
@item i1 <= i2
@item i1 >= i2
@item i1 >  i2
@item i1 == i2
@item i1 != i2
@end table

@item i1 + i2,
Integer addition,
@item i1 - i2
Integer subtraction,
@end table
where @code{i1} and @code{i2} denote integers.

@quotation note
Integers of different @code{subint} types can be used in comparison,
assignment, and function calls.  The verifier will check that the
resulting integer value is within the defined @code{subint} range.
@end quotation

@node Extern Data Type
@subsection @code{extern} data

@cindex data type
@cindex extern
Apart from @code{bool}, @code{enum}, and @code{int} types introduced
above, also @code{extern} data types can be defined.  An @code{extern}
data type is defined as follows:

@cindex data-expression
@example
extern          ::= "extern" identifier data-expression ";"
data-expression ::= "$" (!"$")* "$" | data-variable
data-variable   ::= identifier
@end example

The @code{data-expression} is a type expression in the target
language.

No Dezyne-supported expressions are available for data types, apart from
@code{data-expression}s.  The content of the data-expression is passed
to the target language verbatim.

For example, a @code{C++} string type could be defined as follows:

@example
extern string $std::string$;
@end example

@node Expressions
@subsection Expressions

Expressions in Dezyne are strictly typed.

@cindex bool-expression
@cindex boolean-expression
@example
expression ::= bool-expression | data-expression | enum-expression
                | integer-expression
@end example

@quotation Note
The well-formedness check (@xref{Well-formedness}) verifies that
expressions are of the correct type.
@end quotation

@subsubheading Bool Expressions

@example
bool-expression ::= bool-literal
                     | bool-variable
                     | action
                     | call
                     | field-test
                     | "!" bool-expression
                     | "(" bool-expression ")"
                     | bool-expression bool-operator bool-expression
                     | int-expression comparison-operator int-expression
bool-variable   ::= identifier | port "." identifier
bool-literal    ::= "false" | "true"
field-test      ::= enum-variable "." enum-field
bool-operator   ::= "==" | "!=" | "&&" | "||" | "=>"
comparison-operator
                ::= "==" | "!=" | "<" | "<=" | ">" | ">="
@end example

where @code{action} and @code{call} are of type @code{bool}.

@subsubheading Enum Expressions

@cindex enum-expression
@example
enum-expression ::= enum-literal
                     | enum-variable
                     | action
                     | call
enum-literal    ::= enum "." field
enum-variable   ::= identifier | port "." identifier
@end example

where @code{action} and @code{call} are of the correct @code{enum} type.

@subsubheading Int Expressions

@cindex int-expression
@cindex integer-expression
@example
int-expression  ::= int-literal
                      | subint-variable
                      | action
                      | call
                      | "-" int-expression
                      | "(" int-expression ")"
                      | int-expression int-operator int-expression
subint-variable ::= identifier | port "." identifier
int-literal     ::= "-"? [0-9]+
int-operator    ::= "+" | "-"
@end example

where @code{action} and @code{call} are of a @code{subint} type.

@node Interfaces
@section Interfaces

@cindex event
@cindex interface
@cindex message
Interfaces describe the interaction between two components: the events
(or messages) that can and cannot be communicated, i.e., the interaction
protocol.

@example
interface ::= "interface" identifier "@{" types-and-events behavior "@}"
type-and-events
          ::= (type | event)*
behavior  ::= "behavior" "@{" behavior-statement* "@}"
@end example

Each event has a direction specified by the @code{in} or @code{out}
keywords.  An event labeled with @code{in} (@code{in}-event) is received
by the implementation providing the interface.  Conversely, an event
labeled with @code{out} (@code{out}-event) is emitted by the
implementation providing the interface.  Note that from the point of
view of an implementation requiring an interface the interpretation of
@code{in} and @code{out} is inverted.

The interface protocol is specified in the @code{behavior} section.

@example
$include <string>;$
interface ihello
@{
  @b{enum} result @{FALSE,TRUE,ERROR@};
  @b{extern} string $std::string$;
  @b{in} result hello (string greeting);
  @b{out} void world ();
  @b{behavior} @{ @dots{} @}
@}
@end example

@menu
* Events::                      Event or message definitions.
* Behavior::                    Specifying an interface protocol.
* Declarative Statements::      Define when to run which trigger.
* Imperative Statements::       The code that runs upon a trigger.
* Functions::                   Avoiding code duplication.
@end menu

@node Events
@subsection Events

Events are messages or function calls and returns that are communicated
between components.

@example
event     ::= direction type identifier "(" parameter-list? ")" ";"
direction ::= "in" | "out"
parameter-list
          ::= parameter ( "," parameter)*
parameter ::= parameter-direction? data-type identifier
parameter-direction
          ::= "in" | "out" | "inout"
@end example

Some examples.

A void in-event called @code{e} with an empty parameter list:

@example
in void e ();
@end example

a typed in-event called @code{e2}:

@example
in enum_type e2 ();
@end example

a void in-event called @code{e3} with two data parameters

@example
out void e3 (some_id in_id, out some_id out_id);
@end example

a void out-event called @code{e4} with a data parameter

@example
out void e4 (some_string s);
@end example

@quotation Note
There are two restrictions on @code{out}-event definitions:
@itemize
@item
@code{out}-events must be of type @code{void}, and
@item
@code{out}-events can only take @code{in} parameters.
@end itemize
@end quotation

@subsubsection Modeling Events

Apart from user-defined events, Dezyne has two special builtin events
called @code{optional} and @code{inevitable}.  These are called
``modeling events'' and are used in interface to specify
@emph{decoupled} behavior (@xref{Using inevitable and optional}).

@node Behavior
@subsection Behavior

The @code{behavior} section of an interface defines the protocol of the
interface.  The protocol prescribes the causal relation between events
and state.  The behavior is akin to a state machine.

@example
behavior ::= "behavior" "@{" behavior-statement* "@}"
behavior-statement
         ::= type | variable | function | declarative-statement
@end example

@menu
* Behavior Variable::           The detailed state of the behavior.
@end menu

@node Behavior Variable
@subsubsection Behavior @code{variable}

The @code{behavior} variables define the state of the behavior.
They are sometime referred to as @emph{state variables}.

@example
variable ::= (type identifier = expression
                | data-type identifier) ";"
@end example

where @code{type} and @code{expression} must match.

For example:

@example
bool idle = true;
@end example

@quotation Note
The @code{expression} used in the definition of a behavior variable must
be a constant expression, i.e.: no @code{action}, @code{call} or
@code{variable}-reference is allowed.
@end quotation

@node Declarative Statements
@subsection Declarative Statements

A trigger is prescribed by an interface to be handled by an
implementation as is the condition under which it occurs.  Collectively
this is referred to as a declarative statement.  The condition is
expressed as a @code{guard}, the trigger as an @code{on}.  The code that
is executed when both the guard expression evaluates to @code{true} and
the trigger occurs, is called the @emph{imperative statement}
(@xref{Imperative Statements}).

@example
declarative-statement ::= guard | on | invariant | declarative-compound
declarative-compound  ::= "@{" (declarative-statement ";")* "@}"
@end example


@menu
* On::                          Defining what happens upon a trigger.
* Guard::                       Declarative trigger condition.
* Invariant::                   Specifying invariants.
* Using inevitable and optional::  Nitty gritty details on using modeling events.
@end menu

@node On
@subsubsection @code{on}

The @code{on} defines which trigger is to be handled:

@example
on        ::= "on" trigger ("," trigger)* ":" statement
trigger   ::= event-name | "inevitable" | "optional"
statement ::= declarative-statement | imperative-statement | illegal
illegal   ::= "illegal"
@end example

For example:

@example
on hello: @{@}
on inevitable: @{world; idle = true;@}
@end example

When two or more observably distinct imperative statements are specified
for a certain trigger, the interface is said to behave
@emph{non-deterministic} with respect to the trigger.  For example:

@example
on hello: world;
on hello: cruel;
@end example

when the trigger @code{hello} is sent, the response can either be
@code{world} or @code{cruel} but which one it will be cannot be
predicted.  Non-determinism in interfaces is allowed as long as it is
@emph{observable non-determinism}, i.e., after the trigger has returned
the client should be able to know which state the interface is in.  For
example, this is not allowed:

@example
on hello: @{@}
on hello: idle = true;
@end example

and will lead to a verification error (@xref{Verification Checks and
Errors}).

@quotation Note

@itemize
@item
There must be exactly one imperative statement for every combination of
@code{guard} and @code{on},
@item
There can be only one @code{on} leading to an imperative statement.
@end itemize
@end quotation

@node Guard
@subsubsection @code{guard}

@example
guard ::= "[" bool-expression "]" statement
@end example

For example:

@example
[idle]  on hello: idle = false;
[!idle]
@{
  on hello: idle = true;
  on inevitable: @{world; idle = true;@}
@}
@end example

@node Invariant
@subsubsection @code{invariant}
@cindex invariant

Invariants are part of Dezyne language since version 2.19.0.
The invariant statement expresses a property on states variable and/or shared
state from ports that should hold. It resembles an @code{assert} statement known
for other languages: whenever the expression of the invariant does not
hold, i.e. evaluates to false, an "invariant" error is reported. Invariant
statements only have an effect during simulation and verification.

@example
invariant   ::= "invariant" bool-expression
@end example

Invariants can be used in the behavior of an interface or component.
All invariants are evaluated before processing a trigger, and for a component
we have the additional condition that the queue must be empty. For a component, when the queue
is not empty, evaluating invariants is skipped; the trigger is processed first.

Note that an invariant statement can be guarded, for example:

@example
[state.Enabled] invariant device.state.On;
@end example

Above invariant example for a component expresses that whenever the component
is in its @code{Enabled} state, the device should be in the @code{On} state.

Note that invariants and on statements can be combined:
@example
[state.Enabled]
@{
  invariant device.state.On;
  on ctrl.disable (): @{device.switch_off; state = state.Disabled;@}
@}
@end example


Note that a guarded invariant can be rewritten to an unguarded invariant
using the boolean "implies" (@code{=>}) operator. So, for instance, the example could
equally well expressed by:

@example
invariant state.Enabled => device.state.On;
@end example

@node Using inevitable and optional
@subsubsection Using @code{inevitable} and @code{optional}

In interfaces, two @emph{modeling} events may be used as abstract
triggers, i.e.@: @code{inevitable} and @code{optional}:

@example
on inevitable: imperative-statement;
on optional:   imperative-statement;
@end example

Where @code{inevitable} implies that if no other triggers occur, this
trigger is guaranteed to occur, and @code{optional} implies that the
trigger may or may never occur.

Note that an inevitable event is not always guaranteed to occur, it is
only inevitable in the absence of other events.

An example of an interface using both inevitable and optional.

@example
@verbatiminclude examples/inevitable-optional.dzn
@end example

In the interface above a reply value of @code{true} on @code{hello}
informs the client sending the @code{hello} that the @code{world} can be
waited on.  However in case the reply value of @code{hello} is
@code{false} and the client would sit there waiting for @code{cruel} to
happen, they may sit there forever because @code{cruel} might never
happen.  This is what we refer to as a @emph{deadlock}.  To avoid this
@emph{deadlock} as a client, they must make sure that they can handle a
@code{cruel} in case it does happen and that they have another way of
making progress in case @code{cruel} never happens.

Conversely, the implementation of this interface may choose to perform
the cruel always, never or intermittently after a @code{hello} followed
by a @code{false}, but it must (being contractually required) always do
a @code{world} after a @code{hello} followed by a @code{true}.

@node Imperative Statements
@subsection Imperative Statements

The imperative statement is the statement that will be executed when a
guarded trigger occurs (see also @xref{Declarative Statements}).

@example
imperative-statement
          ::= action | assign | call | if | reply | return | variable
                | imperative-compound
                | empty-statement
imperative-compound
          ::= "@{" (imperative-statement ";")+ "@}"
empty-statement
          ::= ";" | "@{" "@}"
@end example

@menu
* Action::                      Emitting events.
* Assign::                      Updating state.
* Function Call::               A named collection of imperative statements.
* Empty Statement::             When a trigger has no effect, or there is nothing to do.
* If::                          Imperative decisions.
* Illegal::                     Specifying what is not allowed.
* Reply::                       Determining the reply for a typed trigger.
* Return::                      Returning from a function.
* Variable::                    Defining a local variable.
@end menu

@node Action
@subsubsection @code{action}

When handling a trigger (a @code{in}-event), an interface can emit zero
or more @code{out}-events.  The event that follows a trigger is are
referred to as an @code{action}.

@example
action ::= event-name ";"
@end example

where @code{event-name} is the name of an @code{out}-event defined in
the interface.

For example

@example
world;
@end example

@node Assign
@subsubsection @code{assign}

The value of a previously defined variable can be updated using an
@code{assign}:

@example
assign ::= variable "=" expression ";"
@end example

For example:

@example
idle = true;
idle = !b;
idle = negate (idle);
@end example

where @code{b} and @code{idle} are variables of type @code{bool},
@code{negate} is a function with one @code{bool} parameter and
return-type @code{bool} (see @xref{Function Call}).

@node Function Call
@subsubsection @code{call}

@example
call          ::= identifier "(" argument-list ")"
argument-list ::= (expression ",")*
@end example

For example:

@example
foo ();
bar (true, 12);
@end example

Note that the value returned by a @code{call} to a non-@code{void}
@code{function} is not allowed to be ignored.  Therefore in the example
above both @code{foo} and @code{bar} must be @code{function}s of type
@code{void}.  By capturing the value in a variable definition or the use
of an @code{assign} to an existing variable is the proper way to handle
the return value:

@example
bool b = bool_function ();
b = bool_function ();
@end example

Another way is to properly use a return value is in simple expressions,
possibly combined with: @b{==}, @b{!=}, @b{!}, @b{&&}, @b{||} (since
2.14.0)

@example
if (bool_function ()) @dots{};
if (!bool_function ()) @dots{};
if (!bool_function () && b) @dots{};
if (enum_function () == result.FALSE) @dots{};
if (enum_function () != result.TRUE || b) @dots{};
reply (enum_function ());
reply (enum_function () != result.ERROR);
@end example

or in any expression (since 2.16.0).

@node Empty Statement
@subsubsection Empty Statement

@cindex empty statement
@cindex skip
The empty statement or @code{skip} statement defines for @emph{nothing}
to happen.

@example
empty-statement ::=  ";" | "@{" "@}"
@end example

For example:

@example
on hello: @{@}
on cruel: ;
@end example

@node If
@subsubsection @code{if}

Conditional handling of statements is supported by the @code{if}, which
can have an optional else:

@example
if ::= ("if" "(" bool-expression ")" imperative-statement)
         | ("if" "(" bool-expression ")" imperative-statement
              "else" imperative-statement)
@end example

For example

@example
if (idle)
  @{world; idle = false;@}
else
  cruel;
@end example

Since 2.14.0, a typed @code{call} may be used in an
@code{if}-expression.

For example:

@example
if (bool_function ()) @dots{};
if (!bool_function ()) @dots{};
if (!bool_function () && b) @dots{};
if (enum_function () == result.TRUE) @dots{};
if (enum_function () != result.ERROR || b) @dots{};
@end example

Since 2.16.0, arbitrarily complex expressions may be used.

Note that nested @code{if}s are allowed:

@example
if (b1) if (b2) then-statement else else-statement
@end example

is interpreted as

@example
if (b1)
@{ if (b2) then-statement else else-statement @}
@end example

In other words: @code{else} binds to the closest @code{if}.

@quotation Note
In an interface, an @code{illegal} is not allowed as a then-statement or
an else-statement, however the same can be expressed using a
@code{guard}.
@end quotation

@node Illegal
@subsubsection @code{illegal}

A trigger can be explicitly marked as being @code{illegal} in a certain
state.  In that case, @code{illegal} must be the only imperative
statement for that trigger.

@example
illegal ::= "illegal" ";"
@end example

For example:

@example
on hello: illegal;
@end example

@quotation Note
Since 2.14.0, a declarative-statement followed by an @code{illegal} can
be completely omitted, since it has the same meaning.  It is however
still available for backwards compatibility.
@end quotation

@node Reply
@subsubsection @code{reply}

Define the value to be returned at the end of an @code{on} with a typed
trigger.

@example
reply ::= "reply" "(" expression ")" ";"
@end example

For example:

@example
on hello: reply (true);
@end example

@quotation Note
Reply does not mean ``return'', it merely defines the value that is
returned when the @code{on} has finished executing.  @code{reply} does
not have to be the final imperative statement, however it must occur
exactly once on every path through every sequence statements.
@end quotation

@node Return
@subsubsection @code{return}

@code{return} is used to return program execution from the body of a
function to the caller, possibly providing a value.

Implicitly returning from a @code{void} function is allowed.  Also it is
not required to use @code{return} as the last statement of a @code{void}
function, i.e., an early return skipping over remaining statements is
allowed.

@example
return ::= "return" ";"
             | "return" expression ";"
@end example

For example:

@example
void foo ()
@{
  if (idle) return;
  world;
@}

bool negate (bool b)
@{
  return !b;
@}
@end example

@node Variable
@subsubsection @code{variable}

Defining a local variable is syntactically identical to a behavior
variable:

@example
variable ::= (type identifier "=" expression
               | data-type identifier "=" data-expression
               | data-type identifier) ";"
@end example

For example:

@example
bool b = true;
bool not_idle = !idle;
bool c = negate (idle);
@end example

@node Functions
@subsection Functions

A function can be used to name and reuse a sequence of imperative
statements.  As of version 2.20, a function is not required to be scoped
to an interface or component behavior, but may be defined in the same
scope as interfaces and components, see also @xref{Dezyne Files}.

@example
function ::= type identifier "(" parameter-list ")"
               "@{" imperative-statement* "@}"
@end example

For example:

@example
void foo ()
@{
  bye;
  cruel;
  world;
@}

bool bar (bool b, int i)
@{
  if (b)
    world;
  idle = i == 12;
  return idle;
@}
@end example

Functions are allowed to be called recursively.  This includes mutual
recursive functions (function @code{f} calling function @code{g} and
vice versa).  However only as long as every function involved in the
recursion is @emph{tail recursive}; which means that a recursive call is
the last statement in the function.

Previous versions of the language restricted functions to the scope of
behaviors.  Starting with version 2.20 functions may be declared
independent from interface and component behaviors.  This obviously
results in the ability allow functions to be reused across behaviors and
thereby prevent duplication of data related functions.  Functions not
confined to the scope of an interface or component may or may not be
defined in the Dezyne language.  In the latter case, during
verification, the entire range of possible return values is verified by
selecting each value non-deterministically.

@subsection Expression Functions
@cindex expression-function
@cindex predicate

A expression functions can be used to name a single expression of type bool.

@example
expression-function ::= bool identifier "(" ")" "=" expression ";"
@end example

The expression of the expression functions can contain calls to other
expression functions but regular function calls or actions are not allowed.
Note that expression functions can be used in a declarative context,
like guards and invariants, while this is not allowed for regular functions.

Expression functions are available as of Dezyne 2.19.0.

@node Components
@section Components

Components are the building blocks in a Dezyne.  They allow composition
into bigger components called system components.

A component has a list of ports and optionally a behavior or a system
block.

@example
component ::= "component" "@{" port+ (behavior | system)? "@}"
behavior  ::= "behavior" "@{" behavior-statement* "@}"
system    ::= "system" "@{" system-statement* "@}"
@end example

@menu
* Ports::                       Defining a component's communication channels.
* Component Behavior::          Defining a component's behavior.
* Component Types::             Three types of components.
* Component Declarative Statements::  Component-specific declarative statements.
* Component Imperative Statements::  Component-specific imperative statements.
* Multiple Provides Ports::     Providing more than one interface.
@end menu

@node Ports
@subsection Ports

@cindex port
@cindex provides
@cindex requires
A port is an instance of an interface.  A component has ports through
which it interacts with other components.  As such a port is one of the
two end-points connecting two components.

@example
port      ::= ("provides" interface-type identifier ";")
              | ("requires" qualifier? interface-type identifier ";")
qualifier ::= "blocking" | "external" | "injected";
@end example

The keyword @code{provides} indicates that a component implements all
of the interface behavior.

The keyword @code{requires} indicates that a component relies on some
or all of the interface behavior in its implementation.

For example:

@example
@b{provides} ihello p;
@b{provides} blocking ihello p;      // (1)
@b{requires} ihello r;
@b{requires} blocking ihello r;      // (2)
@b{requires} @b{external} itimer t;  // (3)
@b{requires} @b{injected} ilogger l; // (4)
@end example

1) provides port which may potentially block.  The @code{blocking}
qualifier must be used on a provides port when @code{blocking} is used
in the component's behavior, or when the @code{blocking} qualifier is
used on a @code{requires} port.

2) requires port which may potentially block.  The @code{blocking}
qualifier must be used on a requires port when the port it is bound to
has a @code{blocking} qualifier.

3) port to a component with a potential delay in its communication
(@pxref{External})

4) port to a shared resource (@pxref{Systems})

Furthermore a component receives its @code{trigger}s from its
surroundings through its ports.  Note that a component @code{trigger} is
either a @code{provides-in} or a @code{requires-out} event.  If the
component emits events over its ports they are referred to as
@code{action}s.  An @code{action} is either a @code{provides-out} or a
@code{requires-in} event.

@menu
* Injection::                   Ports sharing a resource.
* External::                    Ports with external delay.
@end menu

@node Injection
@subsubsection Injection

@cindex injection
A @code{requires} port can be specified to be @code{injected}:

@example
@b{requires} @b{injected} ilogger l;
@end example

This indicates that the port can be bound to a corresponding port
residing at any level in the system hierarchy.  An @code{injected} port
is the exception to the one to one rule, i.e., it allows many ports to
be connected to a single instance.  For this reason @code{out} events
are not allowed in interfaces which are @code{injected}.

@xref{Systems} for a detailed description of the binding of injected
ports.

@node External
@subsubsection @code{external}

@cindex external
The @code{external} keyword specifies that communication over a
@code{requires} port may experience a delay.  This may for instance be
caused by the switch between execution contexts as in inter-process
communication or the use of threads.

@example
@b{requires} @b{external} itimer t;
@end example

During verification the delay on an @code{external} interface is
experienced an additional interleaving of events that would otherwise
not occur.

@subsubsection Race condition due to external delay

Component @code{remote_timer_proxy} illustrates how a delayed
communication channel may cause a race condition leading to illegal
behavior.

The implementation of component @code{remote_timer_proxy} is correct (no
illegal behavior) for @code{requires itimer rp} but incorrect for
@code{requires external itimer rp} due to race between @code{pp.cancel}
and @code{rp.timeout}.

@example
@verbatiminclude examples/remote-timer-proxy.dzn
@end example

@node Component Behavior
@subsection Component Behavior

The @code{behavior} section of a component defines its behavior.

@example
behavior           ::= "behavior" "@{" behavior-statement* "@}"
behavior-statement ::= type | variable | function | declarative-statement
@end example

A component behavior describes the communication or the exchange of
events between a itself and other components in its environment
connected to its ports.  Each port is defined by a local name and a
behavior refers to these ports by name when it relates @code{trigger}s
and @code{action}s (see also @xref{Ports}).

@node Component Types
@subsection Component Types

There are tree types of component:

@table @code
@item component, regular component, or leaf
A component that defines its implementation in its @code{behavior},
@item foreign
A component that defines only ports.  Its behavior is said to be defined
elsewhere.  This is a placeholder for a component that is implemented by
some other means, like another programming language (e.g. @code{C++}),
@item system
A component that comprises other components in its @code{system}
specification, @xref{Systems}.
@end table

@subsubsection A Leaf Component

Every component in Dezyne is a leaf component, unless it is a system
component.  The following component implements one interface and a
straightforward behavior section:

@example
@b{component} hello
@{
  @b{provides} ihello p;
  @b{requires} ihello r;
  @b{requires} itimer t;
  @b{behavior}
  @{
    @b{on} p.hello (): t.create ();
    @b{on} t.timeout (): r.hello ();
    @b{on} r.world (): p.world ();
  @}
@}
@end example

@subsubsection A Foreign Component

This component does not reveal its implementation in Dezyne under this
name.  It represents a component implemented elsewhere.  It may be
implemented in another programming language, or it is implemented in
Dezyne without exposing any of its implementation details.

@example
@b{component} timer
@{
  @b{provides} itimer t;
@}
@end example

@subsubsection A System Component

A component @code{timer_system} decomposed into two components
@code{ihello} and @code{timer} where these components are connected via
their ports.

@example
@b{component} timer_system
@{
  @b{provides} ihello p;
  @b{requires} ihello r;
  @b{system}
  @{
    hello h;
    timer t;
    p @b{<=>} h.p;
    h.t @b{<=>} t.t;
    h.r @b{<=>} r;
  @}
@}
@end example

@node Component Declarative Statements
@subsection Component Declarative Statements

For a component behavior, the list of declarative statements is extended
with @code{blocking} (@xref{Blocking}).  So we get:

@example
component-declarative-statement ::= declarative-statement | blocking
@end example

@menu
* Component On::                Defining what happens on a trigger.
* Blocking::                    Implementing a synchronous call on decoupled events.
* Formal Binding::              Parameter assignment in blocking or synchronous out context.
* Joining Activities::          A full blocking example.
@end menu

@node Component On
@subsubsection Component @code{on}

Similar to an interface, in a component the @code{on} defines which
trigger is to be handled.  Component triggers, however, belong to
a port and carry formal parameters:

@example
on            ::= ("on" triggers ":" statement)
                  | ("on" illegal-triggers ":" illegal)
triggers      ::= trigger ("," trigger)*
trigger       ::= port-name "." event-name "(" formal-list? ")"
formal-list   ::= formal ("," formal)*
formal        ::= identifier | (identifier formal-binding)
statement     ::= declarative-statement | imperative-statement | illegal
imperative-statement
              ::= action | assign | call | if | reply | return | variable
                  | imperative-compound
                  | defer-statement
                  | empty-statement
illegal       ::= "illegal"
imperative-compound
              ::= "@{" (imperative-statement ";")* "@}"
defer-statement
              ::= "defer" argument-list? imperative-statement
argument-list ::= "(" ")" | "(" expression ("," expression)* ")"
empty-statement
              ::=
illegal-triggers
              ::= illegal-trigger ("," illegal-trigger)*
illegal-trigger
              ::= port-name "." event-name
@end example

The @code{formal-list} to be used is defined by the parameters of the
event definition in the interface.  Their relation is position-based.
Formal parameters may introduce another name than specified in the
@code{event} definition in the interface.

For example:

@example
on p.hello (greeting): w.hello (greeting);
on p.cruel, r.hello: illegal; // Note this is optional since 2.14.0.
@end example

When two or more imperative statements are specified for a certain
trigger, the component is said to be @emph{non-deterministic}.  For
example:

@example
on p.hello (): w.hello ();
on p.hello (): ;
@end example

non-determinism in components is not allowed and will lead to a
verification error (@xref{Verification Checks and Errors}).

The @code{formal-binding} is a feature for @code{blocking} and
synchronous out event contexts @xref{Formal Binding}.

@node Blocking
@subsubsection @code{blocking}

@cindex blocking
The @code{blocking} keyword is a declarative statement that can be used
in a component.

@example
blocking ::= "blocking" statement
@end example

Using @code{blocking} requires an explicit @code{reply}.  It can only be
used in a component.  If the @code{reply} is omitted for the
@code{blocking} @code{trigger}, the imperative statement of another
@code{trigger} must perform the @code{reply} for the blocked port.
Thus, time and value of a blocked port reply depend on another
@code{trigger}.  @code{blocking} may be used once in the declarative
prefix.

Only @code{provides} ports are affected by @code{blocking}.  A call of a
provides port in-event will not return before a @code{reply} is
performed for that port.

Guards or @code{on} is commutative with respect to blocking.  If
@code{blocking} appears before a guard or @code{on} it applies
to the imperative statement after the guard or @code{on}.

@quotation Note

@itemize
@item
When @code{blocking} is used in component which is not the top component
in a system and the system has multiple @code{provide}s ports, the
system must be verified for deadlocks.  Merely verifying all individual
components is not enough.

@item
Systems containing @code{blocking} component instances must be
contained in a thread-safe shell (@pxref{Thread-safe Shell}).
@end itemize

@end quotation

For example:

@example
on trigger (): blocking imperative-statement;         (1)
@end example

@example
blocking on trigger (): imperative-statement;         (2)
@end example

@example
on trigger (): blocking [guard] imperative-statement; (3)
@end example

@example
on trigger ():
@{
  blocking [guard] imperative-statement1;             (4)
  [guard] imperative-statement2;
@}
@end example

Explanation:

2) The @code{blocking} keyword applies to the
@code{imperative-statement} following @code{on trigger:}.  This form is
semantically equivalent to 1).

3) The @code{blocking} keyword applies to the @code{imperative-statement}
following @code{[guard]}.  This form is semantically equivalent to
@code{on trigger (): [guard] blocking imperative-statement;}"

4) The @code{blocking} keyword applies to @code{imperative-statement1}.
It does @emph{not} apply to @code{imperative-statement2}.

@node Formal Binding
@subsubsection Formal Binding

A formal binding @emph{binds} a member variable to an @code{out} or
@code{inout} formal parameter.  At the moment of the @code{reply}, the
value of the bound member variable is assigned to the formal parameter.
A formal binding can be used in blocking context or synchronous out
event context.

@example
trigger        ::= port-name "." event-name "(" formal-list? ")"
formal-list    ::= formal ("," formal)*
formal         ::= identifier | (identifier formal-binding)
formal-binding ::= "<-" identifier
@end example

The @code{identifier} in @code{formal-binding} must be a member variable
of the component.

For example:

@example
extern int $int$;
component blocking_binding
@{
  provides ihello h;
  requires iworld w;

  behavior
  @{
    int g = $123$;
    bool busy = false;
    [!busy] on h.hello (n <- g): blocking @{w.hello (); busy = true;@}
    [busy] on w.world (): @{g = $456$; h.reply (); busy = false;@}
    [busy] on w.cruel (): @{h.reply (); g = $456$; busy = false;@}
  @}
@}
@end example

in the case of @code{w.world} the assignment of @code{g = $456$} before
the release of the blocked thread by @code{h.reply ()} ensures that
parameter @code{n} returns with value @code{456}.  However in the case
of @code{w.cruel} the caller of @code{h.hello} receives @code{123} via
parameter @code{n}.

For a synchronous interface @code{iworld} with behavior:
@example
on hello: world;
on hello: cruel;
@end example

a formal binding can be used in synchronous out event context:

@example
extern int $int$;
component synchronous_out_event_binding
@{
  provides ihello h;
  requires iworld w;

  behavior
  @{
    int g = $123$;

    on h.hello (n <- g): w.hello ();
    on w.world (): @{g = $456$; h.reply (true);@}
    on w.cruel (): @{h.reply (true); g = $456$; ;@}
  @}
@}
@end example

in the case of @code{w.world} the assignment of @code{g = $456$} before
the reply by @code{h.reply ()} ensures that parameter @code{n} returns
with value @code{456}.  However in the case of @code{w.cruel} the caller
of @code{h.hello} receives @code{123} via parameter @code{n}.

For a void event without reply:

@example
extern int $int$;
component synchronous_out_event_binding
@{
  provides ihello h;
  requires iworld w;

  behavior
  @{
    int g = $123$;

    on h.hello (n <- g): w.hello ();
    on w.world (): g = $456$;
  @}
@}
@end example

the caller receives the caller of @code{h.hello} receives the last
assigned value: @code{456}.

@quotation Note
The intent is to simplify this specific behavior in the future when data
flow verification is added.
@end quotation

@node Joining Activities
@subsubsection Joining Activities

Component @code{join} illustrates the use of @code{blocking} in
synchronizing a @code{starter} with the activities of two
@code{runner}s.

@example
@verbatiminclude examples/join.dzn
@end example

@node Component Imperative Statements
@subsection Component Imperative Statements

@menu
* Component Action::            Sending messages over ports.
* Component If::                Imperative decisions in a component.
* Component Illegal::           Using illegal in a component.
* Component Reply::             Using reply in a component.
* Component Defer::             Decoupling execution from the client.
@end menu

@node Component Action
@subsubsection Component @code{action}

When handling the response of a @code{trigger}, a component can send one
or more events over its ports.  The sending of a
@code{provides-out}-event or a @code{requires-in} event is referred to
as an @code{action}.

@example
action        ::= port-name "." event-name argument-list
argument-list ::= "(" ")" | "(" expression ("," expression)* ")"
@end example

where @code{port-name} is the name of a port defined in the component,
and @code{event-name} is the name of an event defined in the interface
associated with the port.

Note that the @code{event} in an @code{action} statement must be of type
@code{void}.  For a typed @code{action} the @code{reply} value may not
be ignored.  A variable definition or an @code{assign} are the
appropriate ways to handle a @code{reply} value:

@example
bool b = r.bool_event ();
b = r.bool_event2 ();
@end example

or it can be used directly in a simple expression, optionally in
combination with @b{==}, @b{!=}, @b{!}, @b{&&}, or @b{||} (since 2.14.0)

@example
if (r.bool_event ()) @dots{};
if (!r.bool_event ()) @dots{};
if (!r.bool_event () && b) @dots{};
if (r.enum_event () == result.FALSE) @dots{};
if (r.enum_event () != result.TRUE || b) @dots{};
reply (r.enum_event ());
reply (r.enum_event () != result.ERROR);
@end example

or in any expression (since 2.16.0).

@quotation Note
The restriction of using only one @code{action} or @code{call} in an
expression has been lifted (since 2.16.0).
@end quotation

@node Component If
@subsubsection Component @code{if}

In a component an @code{illegal} can be used as an imperative
statement in the branch of an @code{if} as any other imperative
statement (@xref{Component Illegal}).

@example
if ::= ("if" "(" bool-expression ")" then-statement)
         | ("if" "(" bool-expression ")" then-statement
            "else" else-statement)
then-statement := imperative-statement | illegal
else-statement := imperative-statement | illegal
@end example

For example:

@example
if (error) illegal;
@end example

Since 2.14.0, one typed @code{action} or typed @code{call} may be used
in an @code{if}-expression.

Since 2.16.0, arbitrarily complex expressions may be used.

For example:

@example
if (r.bool_event ()) @dots{};
if (!r.bool_event ()) @dots{};
if (!r.bool_event () && b) @dots{};
if (r.enum_event () == result.FALSE) @dots{};
if (r.enum_event () != result.TRUE || b) @dots{};
if (bool_function ()) @dots{};
if (!bool_function ()) @dots{};
if (!bool_function () && b) @dots{};
if (enum_function () == result.TRUE) @dots{};
if (enum_function () != result.ERROR || b) @dots{};
@end example

@node Component Illegal
@subsubsection Component @code{illegal}

A @code{trigger} can be explicitly marked as @code{illegal}.  In that
case, @code{illegal} must be the only imperative statement for that
trigger.

@example
on      ::= "on" illegal-triggers ":" illegal
illegal-triggers
        ::= illegal-trigger ("," illegal-trigger)*
illegal-trigger
        ::= port-name "." event-name
illegal ::= "illegal" ";"
@end example

Note that in this case the @code{trigger}'s formal parameter list may be
omitted.

For example:

@example
on p.hello,r,world: illegal;
@end example

@quotation Note
A trigger with an @code{illegal} response can also be omitted since an
@code{illegal} response is the default behavior for every
@code{trigger}.
@end quotation

In a component an @code{illegal} can be used as an imperative statement
in the branch of an @code{if} as any other imperative statement
(@xref{Component If}).

@node Component Reply
@subsubsection Component @code{reply}

A typed trigger event requires an appropriate return value in its
response handling, the @code{reply} only determines the value not the
moment of returning it:

@example
  reply (typed_expression);
@end example

@code{reply} is also used to release a blocked call (@xref{Blocking}),
or set the reply value from a synchronous context like so:

@example
  port.reply ();
  port.reply (expression);
@end example

@node Component Defer
@subsubsection Component @code{defer}

@cindex defer
@code{defer} is a keyword that may be placed in front of an imperative
statement.

@example
defer-statement
              ::= "defer" argument-list? imperative-statement
argument-list ::= "(" ")" | "(" expression ("," expression)* ")"
@end example

@code{defer} indicates that the execution of the corresponding statement
must be postponed at least until after returning back to the caller.
Note that in order for the deferred statement to execute, the
surrounding system must have reached an overall state where it can
accept new activating events, i.e., this state is a system wide run to
completion state.

The primary goal of @code{defer} is to decouple the execution of an
imperative statement from the caller.  This allows implementing an
asynchronous interface almost as concisely as implementing it
synchronously, as demonstrated by the example below.

@example
@verbatiminclude examples/defer.dzn
@end example

Here we can observe the difference between synchronous and asynchronous
behavior once more.  When the @code{synchronous} boolean equals
@code{true} the @code{world} action occurs in the context, e.g. between
the @code{hello} and its @code{return}.  When @code{synchronous} equals
@code{false} the @code{world} action occurs after the @code{return}.
This behavior is clearly depicted by the following state diagram.

@image{images/defer,2.5in,,,.png}

Perhaps the @code{idle} state might seem superfluous in the example
above, however it is not.  Besides resulting in component behavior which
is not compliant with its interface, removing the @code{idle} state and
the corresponding guard would allow a client to do multiple consecutive
@code{h.hello}'s, which results in an overflow of the defer queue.

Besides state playing a role in avoiding @code{defer} queue overflow,
there is another aspect related to state and the use of @code{defer}.
In order for the deferred statement to execute, the component must
remain in the same state as it was at the time of invoking @code{defer}.
Anything that changes the state of the component after invoking
@code{defer} but before the deferred statement executes will remove it
from the queue, and thereby implicitly cancel it.  This is demonstrated
by the example below.  Note that a data member variable is not part of
the component state, and changing its value does not cancel the deferred
statement.

@example
@verbatiminclude examples/defer-cancel.dzn
@end example

Here we see that the @code{cruel} event makes the component @code{idle}
again and in compliance with the interface this implies that the
@code{world} event can no longer occur.  The corresponding component
state diagram is depicted below.

@image{images/defer-cancel,2in,,,.png}

The ability to cancel a deferred statement is not always desirable.  The
way to influence the skip behavior is to add an argument list of state
variables to the @code{defer} keyword.  This limits the scope of the
state which is observed by @code{defer} in deciding when to skip the
execution.  The two extreme cases are:

@itemize
@item
The full list of variables, which is equivalent to @code{defer} without
an argument list.
@item
The empty list of variables, which removes ability to cancel entirely.
@end itemize

We can see an example of a @code{defer} argument list below.

@example
@verbatiminclude examples/defer-selection.dzn
@end example

Here the execution of the deferred statement must remain unaffected by
the change to the @code{cruel} state variable.  We can achieve this by
only observing the @code{state} variable as the example shows or not
observing any state at all.  The latter case is left as an exercise to
the reader.

@node Multiple Provides Ports
@subsection Multiple Provides Ports

A component is not limited to a single provides port, it is allowed to
offer multiple interfaces simultaneously.  When a component provides
multiple ports it can receive @code{in}-events via any of its provides
ports.  As a result the interface behaviors of the provides ports are
effectively interleaved and the component is expected to handle that
appropriately.

When providing multiple ports, two restrictions hold for the component
behavior:

@table @code
@item V-fork
Within the handling of an @code{in}-event of a provides port, it is not
allowed to directly post an @code{out}-event on another provides port.

@item Y-fork
Within the handling of an @code{out}-event of a requires port, it is not
allowed to post an @code{out}-event to more than one provides port.
@end table

The rationale behind both limitations is that if V-forking or Y-forking
would be allowed that it potentially leads to behavior which is beyond
the scope of single component verification.

Violating of any of these restrictions is reported as a compliance
error.

Here are examples of the two types of forking that lead to a compliance
error:

@example
@verbatiminclude examples/compliance-multiple-provides-fork.dzn
@end example

@node Systems
@section Systems

A @code{system} component, or @code{system} is a component which is
composed from one or more sub components.  The @code{system} block
instantiates each of the sub components and either connects their ports
together or exposes them as its own, such that all ports are bound.

@example
system-component ::= "component" "@{" port* system "@}"
system           ::= "system" "@{" system-statement* "@}"
system-statement ::= (instance | binding)
instance         ::= component-name identifier ";"
binding          ::= end-point "<=>" end-point ";"
end-point        ::= port-name
                     | wildcard
                     | (instance-name "." port-name)
                     | (instance-name "." wildcard)
wildcard         ::= "*"
@end example

@quotation Note
A binding can have only one @code{wildcard}, @xref{Using Injection}.
@end quotation

For example:

@example
@verbatiminclude examples/top-middle-bottom.dzn
@end example

The system description shows the instantiation of the two component
instances @code{ci1} and @code{ic2} and two connections or bindings
between ports.

@menu
* Component Instances::         The components of a system.
* Binding::                     The plumbing of a system.
@end menu

@node Component Instances
@subsection Component Instances

In a system description a sub component is specified by its type and
local name:

@example
instance ::= component-name identifier ";"
@end example

The component definition of @code{component-name} has to be available,
potentially through an @code{import}.

It is allowed to have more than one instance of the same type:

@example
hello h1;
hello h2;
@end example

@node Binding
@subsection Binding

Communication between components is achieved through component ports.
The lines of communication are established by binding ports:

@example
binding   ::= end-point "<=>" end-point ";"
end-point ::= port-name
              | wildcard
              | (instance-name "." port-name)
              | (instance-name "." wildcard)
wildcard  ::= "*"
@end example

Note that bindings are symmetrical, i.e., left and right
@code{end-points} can be exchanged.  Communication is restricted to
ports of the same (interface) type.  Moreover the communication
'direction' has to be compatible.  There are two cases:

@itemize

@item
Two sub components communicating: always a @code{provides} port binds to
a @code{requires} port, like in @code{top.rr <=> middle.pp} in the
@code{top_middle_bottom} system example above.

@item
In the case of port forwarding, where a sub-component port is exposed as a
system port, the directions of the ports must be the same, like in
@code{p <=> top.pp} and @code{bottom.rr <=> r} in the
@code{top_middle_bottom} system example above.

@end itemize

@menu
* Using Injection::             Binding injected ports.
@end menu

@node Using Injection
@subsubsection Using Injection

@cindex injection
Binding of @code{injected} ports is done at a higher system level
(@pxref{Components}).  A wild-card character (@code{*}) is used to
achieve the binding of the @code{provides} port of a single instance to
all @code{injected requires} ports.

Let's take a logging interface as an example:

@example
interface ilog
@{
  ...
@}
component logger
@{
  provides ilog log;
  ...
@}
@end example

Suppose a lot of components require logging:

@example
...
component some_component12
@{
  provides some_interface12 p;
  requires injected ilog l;
  ...
@}
component some_component13 @{
  provides some_interface13 p;
  requires injected ilog l;
  ...
@}
...
@end example

then some system component can bind all logging in one go:

@example
component some_system
@{
  ...
  system
  @{
    logger clog;
    ...
    some_component12 c12;
    some_component13 c13;
    ...
    clog.log <=> *;
  @}
@}
@end example

It is allowed to group some components in a sub system:

@example
component some_sub_system
@{
  ...
  system @{
    ...
    some_component12 c12;
    some_component13 c13;
    ...
  @}
@}
@end example

and use the wild-card binding for that sub system:

@example
component some_system
@{
  ...
  system
  @{
    logger clog;
    some_sub_system subsys;
    ...
    clog.log <=> subsys.*;
  @}
@}
@end example

@node Namespaces
@section Namespaces

@cindex scoping
@cindex namespace
All component, interface, and type definitions are defined in a
@code{namespace}, which provides name scoping.  The scope is used as a
prefix when referring to the name from another scope.

@example
namespace      ::= "namespace" compound-identifier "@{" namespace-root "@}"
namespace-root ::= (namespace | type | function | interface | component)*
compound-identifier
               ::= scope* identifier
scope          ::= identifier "."
@end example

For example:

@example
namespace space
@{
  extern string $std::string$;
  interface ihello
  @{
     enum result @{FALSE, TRUE, ERROR@};
     in result hello (string s);
     out void world ();
     behavior
     @{
       on hello (s): reply (result.TRUE);
    @}
  @}
@}
@end example

@subsection Namespace Extension

It is allowed to spread the definition of types, interfaces, components,
and sub-namespaces over multiple instances of a namespace scope.  This is
most useful since in a 'real' project definitions are spread over
multiple files.

So

@example
namespace space
@{
  extern string $std::string$;
  interface ihello @{ ...  @}
@}
@end example

is equivalent to

@example
namespace space
@{
  extern string $std::string$;
@}
namespace space
@{
  interface ihello @{ ...  @}
@}
@end example

@subsection Referencing

When within namespace @code{space} the type @code{string} is defined,
then outside that namespace it is referred to by prefixing it with the
name of that namespace and a dot, as in: @code{space.string}.

Within its own namespace the short name @code{string} is also accepted.

In complex cases it may be necessary to refer to the default
@emph{global} namespace which has an empty name; this results in a
namespace prefix starting with a dot, as can be seen in the following
(somewhat convoluted) example.

@example
@verbatiminclude examples/inner-space.dzn
@end example

which defines:

@itemize

@item interface @code{foo.I} with local enum @code{foo.I.Bool}
@item interface @code{inner.foo.I} with local enum @code{inner.foo.I.Bool}
@item component @code{inner.space}
@item component @code{bar.c}
@end itemize

The two variables defined in component @code{inner.space} have types
@code{foo.I.Bool} and @code{.foo.I.Bool} respectively.  The first type
expands to @code{inner.foo.I.Bool} since it is defined in namespace
@code{inner}.  The starting dot in the second definition prevents this
expansion.

@node Well-formedness
@chapter Well-formedness

The syntax as defined in @ref{Dezyne Language Reference} leaves room for
certain combinations and variations that would lead to Dezyne code that
cannot be translated to an mCRL2 process algebra specification.  This
chapter describes a collection of well-formedness checks that are
defined on top of the syntax.

Apart from the syntax checks performed by the parser, five additional
categories of checks can be identified:

@table @emph
@item definition checks
Upon failure, these produce a @code{undefined identifier} error,
@item parameter checks
Upon failure, these produce a @code{count mismatch} error,
@item type checks
Upon failure, these produce a @code{type-mismatch} error,
@item shadowing checks
Upon failure, these produce a @code{shadowing} error,
@item well-formedness checks
Semantic checks, a.k.a. ``well-formedness'' checks.  Upon failure, these
produce a @code{well-formedness} error.
@end table

The first four categories are common programming errors and should not
need additional explanation.  The last category---the well-formedness
checks---are unique to Dezyne and are described in this chapter.

@menu
* Well-formedness Checks Categories::  Types of checks.
* List of Well-formedness Checks::  An alphabetical lookup list.
* Well-formedness -- Top level::  Interfaces, events and components.
* Well-formedness -- Directional::  Direction of trigger and action.
* Well-formedness -- Nesting::  The right place for declarative and imperative.
* Well-formedness -- Mixing::   Mixing of declarative and imperative.
* Well-formedness -- Reply::    Reply and ports.
* Well-formedness -- Valued Actions and Calls::  Careful use of values.
* Well-formedness -- Injection::  Restrictions on injection.
* Well-formedness -- Functions::  Returning and recursing.
* Well-formedness -- Data Parameters::  Data type errors.
* Well-formedness -- System::   Correctly binding all ports.
@end menu

@node Well-formedness Checks Categories
@section Well-formedness Checks Categories

Well-formedness checks on the @code{behavior} part of a model come in a
number of categories:

@table @emph

@item Top level
Interface, event and component definitions.

@item Directional
@code{trigger}s and @code{action}s are expected at different places
depending on the direction of their @code{event}.

@item Nesting
The imperative part of the language (@code{assign}s, @code{action}s,
function @code{call}s) are only allowed in an imperative statement or in
a function body,

@item Mixing
The use of statements within @code{compound}s is restricted,

@item Reply
The usage of @code{reply},

@item Valued Actions and Calls
The use of non-@code{void} @code{action}s and @code{call}s,

@item Injection
The use of @code{injected} ports,

@item Functions
A function body should be imperative, and have a well-defined return.

@item Data Parameters
The use of data parameters,

@item Injection
The use of @code{injected} ports,

@item System
All ports should be bound correctly.

@end table

@quotation Note
A trigger is an event that occurs and is prefixed by @code{on} in the
behavior, an action is an event that is emitted inside the imperative
body of a trigger.
@end quotation

@node List of Well-formedness Checks
@section List of Well-formedness Checks
The well-formedness checks in alphabetical order:

@*
@xref{Action in member variable initializer},@*
@xref{Action outside on},@*
@xref{Action value discarded},@*
@xref{Assign outside on},@*
@xref{Call in member variable initializer},@*
@xref{Call value discarded},@*
@xref{Cannot bind external port to non-external port},@*
@xref{Cannot bind port to port},@*
@xref{Cannot bind two wildcards},@*
@xref{Cannot bind wildcard to requires port},@*
@xref{Cannot use blocking in an interface},@*
@xref{Cannot use event as action},@*
@xref{Cannot use event as trigger},@*
@xref{Cannot use illegal in function},@*
@xref{Cannot use illegal in if-statement},@*
@xref{Cannot use illegal with imperative statements},@*
@xref{Cannot use inout-parameter on out-event},@*
@xref{Cannot use otherwise guard more than once},@*
@xref{Cannot use otherwise guard with non-guard statements},@*
@xref{Cannot use out-parameter on out-event},@*
@xref{Cannot use return outside of function},@*
@xref{Cannot use statement after recursive call},@*
@xref{Component with behavior must define a provides port},@*
@xref{Component with behavior must have a trigger},@*
@xref{Declarative statement expected},@*
@xref{Formal binding is not a data member variable},@*
@xref{Imperative statement expected},@*
@xref{Injected port has out-events},@*
@xref{Instance is in a cyclic binding},@*
@xref{Interface must define a behavior},@*
@xref{Interface must define an event},@*
@xref{Missing return},@*
@xref{Must specify provides-port with reply},@*
@xref{Must specify provides-port with reply on out-trigger},@*
@xref{Nested blocking used},@*
@xref{Nested on used},@*
@xref{Out-event must be void},@*
@xref{Port is bound more than once},@*
@xref{Port not bound},@*
@xref{Port not bound -- of instance},@*
@xref{System composition is recursive},@*
@xref{Type mismatch -- parameter expected extern}.@*

@node Well-formedness -- Top level
@section Well-formedness -- Top level

These checks are concerned about interface, event and component
definitions.

@menu
* Interface must define an event::
* Interface must define a behavior::
* Out-event must be void::
* Component with behavior must have a trigger::
* Component with behavior must define a provides port::
@end menu

@node Interface must define an event
@subsection Interface must define an @code{event}

Completely ``passive'' interfaces are not allowed; at least one
@code{in}-event or @code{out}-event is required:

@example
@verbatiminclude parse/interface-without-event.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/interface-without-event.texi
@end example

@node Interface must define a behavior
@subsection Interface must define a @code{behavior}

Interfaces without behavior are not allowed.  No adequate default
behavior is available:

@example
@verbatiminclude parse/interface-without-behavior.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/interface-without-behavior.texi
@end example

@node Out-event must be void
@subsection @code{out}-event must be @code{void}

Only @code{in}-events can have a non-@code{void} type.

@example
@verbatiminclude parse/typed-out-event.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/typed-out-event.texi
@end example

@node Component with behavior must have a trigger
@subsection Component with behavior must have a trigger

Any component with a @code{behavior} specification is supposed to be
'reactive'.  This implies that it should have at least one
@code{provides} interface with an @code{in}-event, or at least one
@code{requires} Interface with an @code{out}-event.  Such an event acts
as a @code{trigger} for the component to react on.  So-called ``active''
components are not supported.

@noindent
An example:

@example
@verbatiminclude parse/component-provides-without-trigger.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/component-provides-without-trigger.texi
@end example

@noindent
Another example:

@example
@verbatiminclude parse/component-requires-without-trigger.dzn
@end example

@noindent
This results in the following error messages:

@example
@verbatiminclude parse/component-requires-without-trigger.texi
@end example

@node Component with behavior must define a provides port
@subsection Component with behavior must define a provides port

Any component with a @code{behavior} specification must have a
@code{provides} port through which the component is activated.

@noindent
An example:

@example
@verbatiminclude parse/component-without-provides.dzn
@end example

@noindent
The examples results in the following error messages:

@example
@verbatiminclude parse/component-without-provides.texi
@end example

@node Well-formedness -- Directional
@section Well-formedness -- Directional

@code{trigger}s and @code{action}s are expected at different places,
depending on the direction of their @code{event}.

@menu
* Cannot use event as action::
* Cannot use event as trigger::
@end menu

@node Cannot use event as action
@subsection Cannot use event as action

In an interface this indicates the an @code{in-}event--that can only be
used as a @code{trigger}---is used as an @code{action} in the imperative
body of an @code{on}.

@example
@verbatiminclude parse/interface-trigger-used-as-action.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/interface-trigger-used-as-action.texi
@end example

in a component this indicates that either it is an @code{in}-event of a
@code{provides} interface, or an @code{out}-event of a @code{requires}
interface that is used as an @code{action} in the imperative body of an
@code{on}.

@example
@verbatiminclude parse/component-trigger-used-as-action.dzn
@end example

@noindent
This results in the following error messages:

@example
@verbatiminclude parse/component-trigger-used-as-action.texi
@end example

@node Cannot use event as trigger
@subsection Cannot use event as trigger

In an interface this indicates an @code{out}-event is used as a
@code{trigger}.

@example
@verbatiminclude parse/interface-action-used-as-trigger.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/interface-action-used-as-trigger.texi
@end example

in a component this indicates that either it is an @code{out}-vent of a
@code{provides} interface, or an @code{in}-event of a @b{requires}
interface that is used as a @code{trigger}.

@example
@verbatiminclude parse/component-action-used-as-trigger.dzn
@end example

@noindent
This results in the following error messages:

@example
@verbatiminclude parse/component-action-used-as-trigger.texi
@end example

@node Well-formedness -- Nesting
@section Well-formedness -- Nesting

Dezyne statements are either @emph{declarative} or @emph{imperative}.
One or more declarative statements must be used as a prefix to the
imperative statement (@xref{Declarative Statements}).  Imperative
statements cannot be used without a ``declarative prefix'', and
declarative statements cannot be used inside an imperative statement

@menu
* Assign outside on::
* Action outside on::
* Nested on used::
* Nested blocking used::
* Cannot use blocking in an interface::
@end menu

@node Assign outside on
@subsection @code{assign} outside @code{on}

An @code{assign} occurred outside the scope of a declarative
context:

@example
@verbatiminclude parse/assign-outside-on.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/assign-outside-on.texi
@end example

@node Action outside on
@subsection @code{action} outside @code{on}

An @code{action} occurred outside the scope of a declarative context:

@example
@verbatiminclude parse/action-outside-on.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/action-outside-on.texi
@end example

@node Nested on used
@subsection Nested @code{on} used

@example
@verbatiminclude parse/nested-on.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/nested-on.texi
@end example

@node Nested blocking used
@subsection Nested @code{blocking} used

@example
@verbatiminclude parse/nested-blocking.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/nested-blocking.texi
@end example

@node Cannot use blocking in an interface
@subsection Cannot use @code{blocking} in an interface

Event handling can be 'blocking' in component behavior only.  It is not
allowed in interfaces.  So:

@example
@verbatiminclude parse/blocking-in-interface.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/blocking-in-interface.texi
@end example

@node Well-formedness -- Mixing
@section Well-formedness -- Mixing

A behavior description introduces a sequence of statements.  A statement
itself can be a @code{compound}, which is a sequence of statements
between curly braces.

In order to be able to define clear semantics, there are some
restrictions on the mix of statements in such a sequence.

@menu
* Declarative statement expected::
* Imperative statement expected::
* Cannot use otherwise guard more than once::
* Cannot use otherwise guard with non-guard statements::
* Cannot use illegal with imperative statements::
* Cannot use illegal in if-statement::
* Cannot use illegal in function::
@end menu

@node Declarative statement expected
@subsection Declarative statement expected

If a @code{compound} statement starts with a declarative statement, all
other statements must be declarative statements.

@example
@verbatiminclude parse/mixing-declarative.dzn
@end example

@noindent
This results in the following error messages:

@example
@verbatiminclude parse/mixing-declarative.texi
@end example

@node Imperative statement expected
@subsection Imperative statement expected

If a @code{compound} statement starts with an imperative statement, all
other statements must be imperative statements.

@example
@verbatiminclude parse/mixing-imperative.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/mixing-imperative.texi
@end example


@node Cannot use otherwise guard more than once
@subsection Cannot use @code{otherwise} guard more than once

An @code{otherwise} guard catches the remaining cases for a list of
guards.  For that reason it is not allowed to have more than one
@code{otherwise} statement in a list.  So:

@example
@verbatiminclude parse/second-otherwise.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/second-otherwise.texi
@end example

@node Cannot use otherwise guard with non-guard statements
@subsection Cannot use @code{otherwise} guard with non-guard statements

An @code{otherwise} guard catches the remaining cases for a list of
guards.  For that reason it is not allowed combine an @code{otherwise}
statement with a non-@code{guard}.  So:

@example
@verbatiminclude parse/otherwise-without-guard.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/otherwise-without-guard.texi
@end example

@node Cannot use illegal with imperative statements
@subsection Cannot use @code{illegal} with imperative statements

An @code{illegal} statement must occur on its own; no other
@code{action}s or @code{assign}s are allowed.  That also applies if the
@code{illegal} occurs in a nested @code{compound}:

@example
@verbatiminclude parse/imperative-illegal.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/imperative-illegal.texi
@end example

In a component, using an @code{illegal} within a conditional statement
@emph{is} allowed.  Also the condition may be accompanied by other
@code{action}s, e.g:

@example
@verbatiminclude examples/component-if-illegal.dzn
@end example

@node Cannot use illegal in if-statement
@subsection Cannot use @code{illegal} in @code{if}-statement

In an interface, a @code{trigger} can only be declared @code{illegal} in
a direct way.  This is due to the declarative character of interfaces.
To be more specific, it must not occur in an @code{if}.  An example:

@example
@verbatiminclude parse/interface-if-illegal.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/interface-if-illegal.texi
@end example

@node Cannot use illegal in function
@subsection Cannot use @code{illegal} in function

In an interface, a @code{trigger} can only be declared @code{illegal} in
a direct way.  This is due to the declarative character of interfaces.
To be more specific, it must not occur in a function body.  An example:

@example
@verbatiminclude parse/interface-function-illegal.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/interface-function-illegal.texi
@end example

@node Well-formedness -- Reply
@section Well-formedness -- Reply

A @code{reply} is required in the handling of a typed (i.e.
non-@code{void}) trigger.  It is also required in case a @code{trigger}
(which in this case might be @code{void}) is used in @code{blocking}
mode; in that case the occurrence of the reply might be postponed.  In
general this is hard to check statically.  What can be checked is
described below.

@menu
* Must specify provides-port with reply on out-trigger::
* Must specify provides-port with reply::
@end menu

@node Must specify provides-port with reply on out-trigger
@subsection Must specify @code{provides}-port with @code{reply} on out-trigger

When a @code{reply} is used in the body of a @code{requires-out}
trigger, and the component has multiple provides ports, the @code{reply}
must specify which port it belongs to:

@example
@verbatiminclude parse/requires-reply-needs-provides-port.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/requires-reply-needs-provides-port.texi
@end example

@node Must specify provides-port with reply
@subsection Must specify @code{provides}-port with @code{reply}

When a @code{reply} is used in the body of a function, and the component
has multiple provides ports, the @code{reply} must specify which port it
belongs to:

@example
@verbatiminclude parse/function-reply-needs-provides-port.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/function-reply-needs-provides-port.texi
@end example

@node Well-formedness -- Valued Actions and Calls
@section Well-formedness -- Valued Actions and Calls

Both @code{action}s and function @code{call}s can be typed, and as such
are considered to be expressions.  They can only be called are from the
imperative statement.  The reason is that @code{action}s and function
@code{calls} (at least the functions that contain @code{action}s) cause
a side effect.

This means that @code{action}s or function @code{call}s cannot be used
to initialize the value of a global variable in a behavior, neither
can it be used in a @code{guard} statement.

@menu
* Action in member variable initializer::
* Call in member variable initializer::
* Action value discarded::
* Call value discarded::
@end menu

@node Action in member variable initializer
@subsection @code{action} in member variable initializer

An @code{action} is used in the initial value of a member variable.

@example
@verbatiminclude parse/action-in-member-definition.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/action-in-member-definition.texi
@end example

@node Call in member variable initializer
@subsection @code{call} in member variable initializer

A function @code{call} is used in the initial value of a member
variable.

@example
@verbatiminclude parse/call-in-member-definition.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/call-in-member-definition.texi
@end example

@node Action value discarded
@subsection @code{action} value discarded

A typed Action is called without using its return value.

@example
@verbatiminclude parse/action-discard-value.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/action-discard-value.texi
@end example

@node Call value discarded
@subsection @code{call} value discarded

A typed function is called without using its return value.

@example
@verbatiminclude parse/call-discard-value.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/call-discard-value.texi
@end example

@node Well-formedness -- Injection
@section Well-formedness -- Injection

Not every port can be injected.

@menu
* Injected port has out-events::
@end menu

@node Injected port has out-events
@subsection @code{injected} port has @code{out}-events

When a Component has a @code{requires injected} port, its interface must
not have @code{out}-events.

@example
@verbatiminclude parse/injected-with-out-event.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/injected-with-out-event.texi
@end example

@node Well-formedness -- Functions
@section Well-formedness -- Functions

@itemize

@item
A function body can only contain imperative statements, including
@code{action}s.  See the sections on 'Mixing' and 'Direction' above,

@item
A typed function is required to have an explicit return,

@item
A return is only allowed in a function body,

@item
A recursive function is required to be tail recursive.

@end itemize

@menu
* Missing return::
* Cannot use return outside of function::
* Cannot use statement after recursive call::
@end menu

@node Missing return
@subsection Missing @code{return}

A typed function should return a value using the @code{return}
statement.  An error is issued when a return is not guaranteed.  An
example:

@example
@verbatiminclude parse/function-missing-return.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/function-missing-return.texi
@end example

@node Cannot use return outside of function
@subsection Cannot use @code{return} outside of function

A @code{return} statement is restricted to function body.  So:

@example
@verbatiminclude parse/return-outside-function.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/return-outside-function.texi
@end example

@node Cannot use statement after recursive call
@subsection Cannot use statement after recursive @code{call}

A function that is recursive must be tail recursive, i.e., in its body
any recursive function call shall not be followed by other statements.
So:

@example
@verbatiminclude parse/function-not-tail-recursive.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/function-not-tail-recursive.texi
@end example

@quotation Note
Two functions @code{f} and @code{g} that are defined in terms of each
other are mutual recursive and are thus also considered to be recursive.
@end quotation

@node Well-formedness -- Data Parameters
@section Well-formedness -- Data Parameters

The restrictions on data parameters are summarized here.

@menu
* Type mismatch -- parameter expected extern::
* Cannot use out-parameter on out-event::
* Cannot use inout-parameter on out-event::
* Formal binding is not a data member variable::
@end menu

@node Type mismatch -- parameter expected extern
@subsection Type mismatch: parameter expected @code{extern}

All event parameters specified in an event definition must be data
parameters; in other words, they must have a data type.  An example:

@example
@verbatiminclude parse/event-with-bool-parameter.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/event-with-bool-parameter.texi
@end example

@node Cannot use out-parameter on out-event
@subsection Cannot use @code{out}-parameter on @code{out}-event

An @code{out}-event must not have an @code{out}-parameter.

@example
@verbatiminclude parse/out-parameter-on-out-event.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/out-parameter-on-out-event.texi
@end example

@node Cannot use inout-parameter on out-event
@subsection Cannot use @code{inout}-parameter on @code{out}-event

An @code{out}-event must not have an @code{inout}-parameter.  An
example:

@example
@verbatiminclude parse/inout-parameter-on-out-event.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/inout-parameter-on-out-event.texi
@end example

@node Formal binding is not a data member variable
@subsection Formal binding is not a data member variable

Formal binding, which is the binding of a data member variable
@code{data} to an event parameter @code{p} using the @code{p <- data}
construct, is only allowed in a component, in an @code{on} context.
Using @code{<-} in any other context is reported as a parse error.

@example
@verbatiminclude parse/out-binding-reversed.dzn
@end example

@noindent
This results in the following error messages:

@example
@verbatiminclude parse/out-binding-reversed.texi
@end example

@node Well-formedness -- System
@section Well-formedness -- System

In a system, the component's ports and all sub component's ports must be
bound correctly.

Bindings in which `'wildcards'' are involved will be described at the
end of this section.

@menu
* Port not bound::
* Port not bound -- of instance::
* Port is bound more than once::
* Cannot bind port to port::
* Cannot bind two wildcards::
* Instance is in a cyclic binding::
* Cannot bind wildcard to requires port::
* System composition is recursive::
* Cannot bind external port to non-external port::
@end menu

@node Port not bound
@subsection @code{port} not bound

No binding is specified for a port of a system.

@example
@verbatiminclude parse/port-not-bound.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/port-not-bound.texi
@end example

@node Port not bound -- of instance
@subsection @code{port} not bound -- of @code{instance}

No binding is specified for a port of a component @code{instance}.

@example
@verbatiminclude parse/instance-port-not-bound.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/instance-port-not-bound.texi
@end example

@node Port is bound more than once
@subsection @code{port} is bound more than once

More than one binding is specified for a port of a system or one of its
component instances:

@example
@verbatiminclude parse/port-bound-twice.dzn
@end example

@noindent
This results in the following error messages:

@example
@verbatiminclude parse/port-bound-twice.texi
@end example

@node Cannot bind port to port
@subsection Cannot bind port to port

The directions of the left and right port mentioned in the binding do
not match.  The following constructs are allowed:

@itemize

@item
When binding a port of the system to a port of a component instance, the
directions must be the same:

@itemize

@item @b{provides} binds to @b{provides}
@item @b{requires} binds to @b{requires}
@end itemize

@item
When binding a port of the system to another port of the system
Component, the directions must be the opposite:

@itemize

@item @b{provides} binds to @b{requires} or vice versa.

@end itemize

@item
When binding a port of a component instance to a port of another (or the
same) component instance, the directions must be the opposite:

@itemize

@item @b{provides} binds to @b{requires} or vice versa.

@end itemize

@end itemize

@example
@verbatiminclude parse/binding-mismatch-direction.dzn
@end example

@noindent
This results in the following error messages:

@example
@verbatiminclude parse/binding-mismatch-direction.texi
@end example

@node Cannot bind two wildcards
@subsection Cannot bind two wildcards

@example
@verbatiminclude parse/binding-two-wildcards.dzn
@end example

@noindent
This results in the following error messages:

@example
@verbatiminclude parse/binding-two-wildcards.texi
@end example

@node Instance is in a cyclic binding
@subsection @code{instance} in in a cyclic binding

We can define communication ``direction'' for bindings as follows:

@itemize

@item
For two component instances communicating: the @code{requires} port directs to
the @code{provides} port in the binding.

@item
For port forwarding (an external port is forwarded to a component
instance port) or vice versa: A @code{provides} external port directs to
a component instance @code{provides} port, and a component instance
@code{requires} directs to a @code{requires} external port.

@end itemize
To prevent component re-entrancy and guarantee run-to-completion
semantics, cycles in 'directed' communication are not allowed within a
system component.

In the most trivial example, which creates a one-component cycle:

@example
@verbatiminclude parse/binding-cycle.dzn
@end example

@noindent
This results in the following error messages:

@example
@verbatiminclude parse/binding-cycle.texi
@end example

@noindent
A more elaborate example creates a cycle over three components:

@example
@verbatiminclude parse/binding-cycle-elaborate.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/binding-cycle-elaborate.texi
@end example

@node Cannot bind wildcard to requires port
@subsection Cannot bind wildcard to @code{requires} port

Since @code{injected} ports are always @code{requires} ports and a
wildcard is used to bind such a port, the other side of a wildcard
binding must be a @code{provides} port.  In this example:

@example
@verbatiminclude parse/binding-wildcard-requires.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/binding-wildcard-requires.texi
@end example

@node System composition is recursive
@subsection System composition is recursive

A system may instantiate an arbitrary set of components, which in turn
can be systems themselves.  It is not allowed to have a self-instance
neither directly nor indirectly, since that would lead to an infinite
tree of components.

In the example below five systems are defined that have mutual
instances.  System @code{c1} instantiates @code{c3}, which
instantiates @code{c4}, which instantiates @code{c1}.

@example
@verbatiminclude parse/recursive-system.dzn
@end example

@noindent
This results in the following error messages:

@example
@verbatiminclude parse/recursive-system.texi
@end example

@node Cannot bind external port to non-external port
@subsection Cannot bind @code{external} port to non-@code{external} port

There is a restriction in the binding of external ports: when an
external requires port of a system Component is bound, the other side of
the binding must be an external requires port also (this is only
possible when that is a port of a sub Component).  In the example below
some errors are reported.

@example
@verbatiminclude parse/binding-mismatch-external.dzn
@end example

@noindent
This results in the following error message:

@example
@verbatiminclude parse/binding-mismatch-external.texi
@end example

@c *********************************************************************
@node Contributing
@chapter Contributing

This project is a cooperative effort, and we need your help to make it
grow!  Please get in touch with us on @email{dezyne-devel@@nongnu.org} and
@code{#dezyne} on the Libera Chat IRC network.  We welcome ideas, bug
reports (please send your bug reports to @email{bug-dezyne@@nongnu.org}),
patches, and anything that may be helpful to the project.

Note: bug reports contain at least descriptions of:
@enumerate
@item Steps to reproduce the bug
@item What you expected to see
@item What you actually saw
@end enumerate

You can help us by increasing the signal to noise ratio in your
communication including your bug reports.  Including a minimal
@code{dzn} file in the canonical format as used in the test framework
(see @file{test/all/hello} is most helpful.

Before sending your bug report, please check if you found an already
known problem first at
@url{https://gitlab.com/dezyne/dezyne-issues/-/issues, dezyne bugs at
gitlab}.

@cindex gnu kind communication guidelines
@cindex kind communication guidelines
We want to provide a warm, friendly, and harassment-free environment, so
that anyone can contribute to the best of their abilities.  To this end
our project uses the ``GNU Kind Communication Guidelines,
@url{https://www.gnu.org/philosophy/kind-communication.en.html}.  You
can find a local version in the @file{GKCG} file in the source tree.

Contributors are not required to use their legal name in patches and
on-line communication; they can use any name or pseudonym of their
choice.

@menu
* Building from Git::           The latest and greatest.
* Running Dezyne Before It Is Installed::  Hacker tricks.
* The Perfect Setup::           The right tools.
* Coding Style::                Hygiene of the contributor.
* Submitting Patches::          Share your work.
* Making Decisions::            Collectively choosing the way forward.
* Commit Access::               Pushing to the official repository.
* Reviewing the Work of Others::  Some guidelines for sharing reviews.
@end menu

@node Building from Git
@section Building from Git

If you want to hack Dezyne yourself, it is recommended to use the latest
version from the Git repository:

@example
git clone git://git.savannah.nongnu.org/dezyne
@end example

To setup a development environment, we use
@url{https://gnu.org/software/guix/, GNU Guix} (@pxref{Top,,, guix, The
GNU Guix Manual}); run

@example
guix shell
@end example

If you are unable to use Guix when building Dezyne from a Git checkout,
the following are the required packages in addition to those mentioned
in the installation instructions (@pxref{Requirements}).

@itemize
@item @url{https://gnu.org/software/autoconf/, GNU Autoconf};
@item @url{https://gnu.org/software/automake/, GNU Automake};
@item @url{https://gnu.org/software/gettext/, GNU Gettext};
@item @url{https://gnu.org/software/libtool/, GNU Libtool};
@item @url{https://gnu.org/software/texinfo/, GNU Texinfo};
@item @url{https://gnu.org/software/help2man/, GNU Help2man (optional)}.
@end itemize

Run @command{./autogen.sh} to generate the build system infrastructure
using Autoconf and Automake.

Then, run @command{./configure} and @command{make} as usual.

@node Running Dezyne Before It Is Installed
@section Running Dezyne Before It Is Installed

After making changes you will want to test them.  To that end, all the
command-line tools can be used even if you have not run @code{make
install}.  To do that, you first need to have an environment with all
the dependencies available (@pxref{Building from Git}), and then simply
prefix each command with @command{./pre-inst-env}.  As an example, here
is how you would verify the trivial the @code{hello} test:

@example
$ ./pre-inst-env dzn -v verify test/all/hello/hello.dzn
@end example

See the file @file{HACKING} for some developer tips and tricks.

@node The Perfect Setup
@section The Perfect Setup

The Perfect Setup to hack on Dezyne is basically the perfect setup used
for GNU Guile hacking (@pxref{Using Guile in Emacs,,, guile, GNU Guile
Reference Manual}).  To work on real-life Dezyne projects, you need more
than an editor: you need an IDE, @pxref{Top, ,,verum-dezyne,the Verum-Dezyne
Manual}.

@table @code
@item GNU Emacs
To edit @file{.DZN} files, use @file{emacs/dzn-mode.el}.
@item ...
...
@end table

@node Coding Style
@section Coding Style

In general our code follows the GNU Coding Standards (@pxref{Top,,,
standards, GNU Coding Standards})@footnote{A notable exception is the
@code{c++} runtime and handwritten code}.  However, they do not say much
about Scheme, so here are some additional rules.

@menu
* Programming Paradigm::        How to compose your elements.
* Data Types and Pattern Matching::  Implementing data structures.
* Formatting Code::             Writing conventions.
@end menu

@node Programming Paradigm
@subsection Programming Paradigm

Scheme code in Dezyne is written in a purely functional style.  One
exception is code that involves input/output, and procedures that
implement low-level concepts, such as memoization.

@node Data Types and Pattern Matching
@subsection Data Types and Pattern Matching

The tendency in classical Lisp is to use lists to represent everything,
and then to browse them ``by hand'' using @code{car}, @code{cdr},
@code{cadr}, and co.  There are several problems with that style,
notably the fact that it is hard to read, error-prone, and a hindrance
to proper type error reports.

Dezyne code should define appropriate data types (@code{AST} or
@code{GOOPS} classes, or using @code{define-immutable-record-type})
rather than abuse lists.  In addition, it should use pattern matching,
via Guile’s @code{(ice-9 match)} module, especially when matching lists
(@pxref{Pattern Matching,,, guile, GNU Guile Reference Manual}).

@node Formatting Code
@subsection Formatting Code

@cindex formatting code
@cindex coding style
When writing Scheme code, we follow common wisdom among Scheme
programmers.  In general, we follow the
@url{https://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
Style Rules}.  This document happens to describe the conventions mostly
used in Guile’s code too.  It is very thoughtful and well written, so
please do read it.

In addition, Dezyne uses the following formatting for @code{if}

@example
(if test? trivial-case
    the-more-elaborate-case)
@end example

@cindex indentation, of code
@cindex formatting, of code
If you do not use Emacs, please make sure to let your editor knows the
proper indentation rules, or use the @file{build-aux/indent.scm} script
to fix the indentation.

@node Submitting Patches
@section Submitting Patches

Development is done using the Git distributed version control system.
Thus, access to the repository is not strictly necessary.  We welcome
contributions in the form of patches as produced by @code{git
format-patch} sent to the @email{dezyne-devels@@nongnu.org} mailing list
(@pxref{submitting patches,, Submitting patches to a project, git, Git
User Manual}).

Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
standards, GNU Coding Standards}); you can check the commit history for
examples.

@node Making Decisions
@section Making Decisions

@cindex decision making
@cindex consensus seeking
It is expected from all contributors, and even more so from committers,
to help build consensus and make decisions based on consensus.  By using
consensus, we are committed to finding solutions that everyone can live
with.  It implies that no decision is made against significant concerns
and these concerns are actively resolved with proposals that work for
everyone.

A contributor (who may or may not have commit access) wishing to block
a proposal bears a special responsibility for finding alternatives,
proposing ideas/code or explain the rationale for the status quo to
resolve the deadlock.  To learn what consensus decision making means and
understand its finer details, you are encouraged to read
@url{https://www.seedsforchange.org.uk/consensus}.

@node Commit Access
@section Commit Access

@cindex commit access, for developers
Everyone can contribute to Dezyne without having commit access
(@pxref{Submitting Patches}).  However, for frequent contributors,
having write access to the repository can be convenient.  As a rule of
thumb, a contributor should have accumulated fifty (50) reviewed commits
to be considered as a committer and have sustained their activity in the
project for at least 6 months.  This ensures enough interactions with
the contributor, which is essential for mentoring and assessing whether
they are ready to become a committer.  Commit access should not be
thought of as a ``badge of honor'' but rather as a responsibility a
contributor is willing to take to help the project.

Committers are in a position where they enact technical decisions.  Such
decisions must be made by @emph{actively building consensus} among
interested parties and stakeholders.  @xref{Making Decisions}, for more
on that.

The following sections explain how to get commit access, how to be ready
to push commits, and the policies and community expectations for commits
pushed upstream.

@subsection Applying for Commit Access

When you deem it necessary, consider applying for commit
access by following these steps:

@enumerate
@item
Find two committers who would vouch for you.  You can view the list of
committers at
@url{https://savannah.nongnu.org/project/memberlist.php?group=dezyne}.  Each
of them should email a statement to @email{maintainers@@dezyne.org} (a
private alias for the collective of maintainers), signed with their
OpenPGP key.

Committers are expected to have had some interactions with you as a
contributor and to be able to judge whether you are sufficiently
familiar with the project's practices.  It is @emph{not} a judgment on
the value of your work, so a refusal should rather be interpreted as
``let's try again later''.

@item
Send @email{maintainers@@dezyne.org} a message stating your intent,
listing the two committers who support your application, signed with
the OpenPGP key you will use to sign commits, and giving its fingerprint
(see below).  See @uref{https://emailselfdefense.fsf.org/en/}, for an
introduction to public-key cryptography with GnuPG.

@c See <https://sha-mbles.github.io/>.
Set up GnuPG such that it never uses the SHA1 hash algorithm for digital
signatures, which is known to be unsafe since 2019, for instance by
adding the following line to @file{~/.gnupg/gpg.conf} (@pxref{GPG
Esoteric Options,,, gnupg, The GNU Privacy Guard Manual}):

@example
digest-algo sha512
@end example

@item
Maintainers ultimately decide whether to grant you commit access,
usually following your referrals' recommendation.

@item
@cindex OpenPGP, signed commits
If and once you've been given access, please send a message to
@email{dezyne-devel@@nongnu.org} to say so, again signed with the OpenPGP key
you will use to sign commits (do that before pushing your first commit).
That way, everyone can notice and ensure you control that OpenPGP key.

@item
Make sure to read the rest of this section and... profit!
@end enumerate

@quotation Note
Maintainers are happy to give commit access to people who have been
contributing for some time and have a track record---don't be shy and
don't underestimate your work!
@end quotation

All commits that are pushed to the central repository on Savannah must
be signed with an OpenPGP key, and the public key should be uploaded to
your user account on Savannah and to public key servers, such as
@code{keys.openpgp.org}.  To configure Git to automatically sign
commits, run:

@example
git config commit.gpgsign true

# Substitute the fingerprint of your public PGP key.
git config user.signingkey CABBA6EA1DC0FF33
@end example

To check that commits are signed with correct key, use, for example,

@example
git show --show-signature <hash>
git log --show-signature
@end example

@subsection Commit Policy

If you get commit access, please make sure to follow the policy below
(discussions of the policy can take place on
@email{dezyne-devel@@nongnu.org}).

Ensure you're aware of how the changes should be handled
(@pxref{Managing Patches and Branches}) prior to being pushed to thegn
repository, especially for the @code{master} branch.

If you're committing and pushing your own changes, try and wait at least
one week (two weeks for more significant changes, up to one month for
large changes) after you send them for review.  After this, if no one
else is available to review them and if you're confident about the
changes, it's OK to commit.

When pushing a commit on behalf of somebody else, please add a
@code{Signed-off-by} line at the end of the commit log message---e.g.,
with @command{git am --signoff}.  This improves tracking of who did
what.

@menu
* Managing Patches and Branches::
@end menu

@node Managing Patches and Branches
@subsection Managing Patches and Branches
@cindex branching strategy

Changes should be posted to @email{dezyne-devel@@nongnu.org}.  Leave
time for a review, without committing anything.

As an exception, some changes considered ``trivial'' or ``obvious'' may
be pushed directly to the @code{staging} branch.  As Dezyne uses a
strictly linear history, and master cannot be reset on Savannah, the
staging branch is used to accumulate such commits.  This includes
changes to fix typos and reverting commits that caused immediate
problems.  This is subject to being adjusted, allowing individuals to
commit directly on non-controversial changes on parts they’re familiar
with.

@cindex feature branches, coordination
To help coordinate the rebasing of @code{wip-*} feature branches, you
must send an email to @email{dezyne-devel@@nongnu.org} each time you
create a branch, and specify which branch it is based on, which can
be another @code{wip-*} feature branch.

@enumerate
@item
The commits on the branch should be a combination of the patches
relevant to the branch.  Patches not related to the topic of the branch
should go elsewhere.

@item
Any changes that can be made on the staging branch, should be made on the
staging branch.  If a commit can be split to apply part of the changes on
staging, this is good to do.

@item
Dezyne uses a strictly linear history, which means branches are rebased
or re-created rather than merged.
@end enumerate

@subsection Addressing Issues

Peer review (@pxref{Submitting Patches}) and tools such as
@command{build-aux/indent.scm} and the test suite should catch issues
before they are pushed.  Yet, commits that ``break'' functionality might
occasionally go through.  When that happens, there are two priorities:
mitigating the impact, and understanding what happened to reduce the
chance of similar incidents in the future.  The responsibility for both
these things primarily lies with those involved, but like everything
this is a group effort.

@cindex reverting commits
The people involved in authoring, reviewing, and pushing such commit(s)
should be at the forefront to mitigate their impact in a timely fashion:
by pushing a followup commit to fix it (if possible), or by reverting it
to leave time to come up with a proper fix, and by communicating with
other developers about the problem.  A revert commit should always state
the reason for reverting.

If these persons are unavailable to address the issue in time, other
committers are entitled to revert the commit(s), explaining in the
commit log and on the mailing list what the problem was, with the goal
of leaving time to the original committer, reviewer(s), and author(s)
to propose a way forward.

Once the problem has been dealt with, it is the responsibility of
those involved to make sure the situation is understood.  If you are
working to understand what happened, focus on gathering information
and avoid assigning any blame.  Do ask those involved to describe what
happened, do not ask them to explain the situation---this would
implicitly blame them, which is unhelpful.  Accountability comes from
a consensus about the problem, learning from it and improving
processes so that it's less likely to reoccur.

@subsection Commit Revocation

In order to reduce the possibility of mistakes, committers will have
their Savannah account removed from the Dezyne Savannah project after 12
months of inactivity; they can ask to regain commit access by emailing
the maintainers, without going through the vouching process.

Maintainers@footnote{See @file{MAINTAINERS} for the current list of
maintainers.  You can email them privately at
@email{maintainers@@dezyne.org}.}  may also revoke an individual's
commit rights, as a last resort, if cooperation with the rest of the
community has caused too much friction---even within the bounds of the
project's kind communication guidelines (@pxref{Contributing}).  They
would only do so after public or private discussion with the individual
and a clear notice.  Examples of behavior that hinders cooperation and
could lead to such a decision include:

@itemize
@item repeated violation of the commit policy stated above;
@item repeated failure to take peer criticism into account;
@item breaching trust through a series of grave incidents.
@end itemize

When maintainers resort to such a decision, they notify developers on
@email{dezyne-devel@@nongnu.org}; inquiries may be sent to
@email{maintainers@@dezyne.org}.  Depending on the situation, the
individual may still be welcome to contribute.

@subsection Helping Out

One last thing: the project keeps moving forward because committers not
only push their own awesome changes, but also offer some of their time
@emph{reviewing} and pushing other people's changes.  As a committer,
you're welcome to use your expertise and commit rights to help other
contributors, too!

@node Reviewing the Work of Others
@section Reviewing the Work of Others

Perhaps the biggest action you can do to help Dezyne grow as a project
is to review the work contributed by others.  You do not need to be a
committer to do so; applying, reading the source, building, linting and
running other people's series and sharing your comments about your
experience will give some confidence to committers.  You must ensure the
check list found in the @ref{Submitting Patches} section has been
correctly followed.  A reviewed patch series should give the best
chances for the proposed change to be merged faster, so if a change you
would like to see merged hasn't yet been reviewed, this is the most
appropriate thing to do!

@cindex reviewing, guidelines
Review comments should be unambiguous; be as clear and explicit as you
can about what you think should be changed, ensuring the author can take
action on it.  Please try to keep the following guidelines in mind
during review:

@enumerate
@item
@emph{Be clear and explicit about changes you are suggesting}, ensuring
the author can take action on it.  In particular, it is a good idea to
explicitly ask for new revisions when you want it.

@item
@emph{Remain focused: do not change the scope of the work being
reviewed.}  For example, if the contribution touches code that follows a
pattern deemed unwieldy, it would be unfair to ask the submitter to fix
all occurrences of that pattern in the code; to put it simply, if a
problem unrelated to the patch at hand was already there, do not ask the
submitter to fix it.

@item
@emph{Ensure progress.}  As they respond to review, submitters may
submit new revisions of their changes; avoid requesting changes that you
did not request in the previous round of comments.  Overall, the
submitter should get a clear sense of progress; the number of items open
for discussion should clearly decrease over time.

@item
@emph{Aim for finalization.}  Reviewing code is time-consuming.  Your
goal as a reviewer is to put the process on a clear path towards
integration, possibly with agreed-upon changes, or rejection, with a
clear and mutually-understood reasoning.  Avoid leaving the review
process in a lingering state with no clear way out.

@item
@emph{Review is a discussion.}  The submitter's and reviewer's views on
how to achieve a particular change may not always be aligned.  To lead
the discussion, remain focused, ensure progress and aim for
finalization, spending time proportional to the stakes@footnote{The
tendency to discuss minute details at length is often referred to as
``bikeshedding'', where much time is spent discussing each one's
preference for the color of the shed at the expense of progress made on
the project to keep bikes dry.}.  As a reviewer, try hard to explain the
rationale for suggestions you make, and to understand and take into
account the submitter's motivation for doing things in a certain way.
In other words, build consensus with everyone involved (@pxref{Making
Decisions}).
@end enumerate

@cindex LGTM, Looks Good To Me
@cindex review tags
@cindex Reviewed-by, git trailer
When you deem the proposed change adequate and ready for inclusion
within Dezyne, the following well understood/codified
@samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>}
@footnote{The @samp{Reviewed-by} Git trailer is used by other projects
such as Linux, and is understood by third-party tools such as the
@samp{b4 am} sub-command, which is able to retrieve the complete
submission email thread from a public-inbox instance and add the Git
trailers found in replies to the commit patches.} line should be used to
sign off as a reviewer, meaning you have reviewed the change and that it
looks good to you:

@itemize
@item
If the @emph{whole} series (containing multiple commits) looks good to
you, reply with
@samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>}
to the cover page if it has one, or to the last patch of the series
otherwise, adding another @samp{(for the whole series)} comment on the
line below to explicit this fact.

@item
If you instead want to mark a @emph{single commit} as reviewed (but not
the whole series), simply reply with
@samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>}
to that commit message.
@end itemize

@node Acknowledgments
@chapter Acknowledgments

Dezyne is based on the @uref{https://gitlab.com./janneke/gaiag/, Gaiag
prototype}, which was designed and implemented by Janneke Nieuwenhuizen,
Gaiag pioneered implementation of model verification and code generation
written entirely in Guile Scheme.

Dezyne itself is a collective work with contributions from a number of
people.  See the @file{AUTHORS} file in Dezyne for more information on
these fine people.

@c *********************************************************************
@node Concept Index
@unnumbered Concept Index
@printindex cp

@c *********************************************************************
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl-1.3.texi

@bye

@c Local Variables:
@c ispell-local-dictionary: "american";
@c End:
