Getting Started

Welcome to Xronos! This guide will walk you through everything you need to get up and running, from installation to your first working application.

System Requirements

Before you begin, make sure your environment meets the following requirements:

• A manylinux_2_35 compliant Linux distribution. We recommend Ubuntu 22.04 or newer.

• Python 3, in one of the versions shown by the Python badge above

Installation

We recommend working in a virtual environment to keep your project dependencies isolated. Use the following commands to create and activate a new environment called .venv.

$ python -m venv .venv
$ source .venv/bin/activate

Then install the xronos package:

$ pip install xronos

Hello World

Let’s write your first Xronos application. Create a file called hello.py and paste the following content into it.

plainwith type hints

import xronos


class Hello(xronos.Reactor):
    @xronos.reaction
    def hello(self, ctx):
        ctx.add_trigger(self.startup)
        return lambda: print("Hello, World!")


def main():
    env = xronos.Environment()
    env.create_reactor("hello", Hello)
    env.execute()


if __name__ == "__main__":
    main()

Run the application:

$ python hello.py
Hello, World!

Now let’s walk through what this application does. The building blocks of the Xronos SDK are called reactors. You can define a new reactor by subclassing the xronos.Reactor base class. The example above defines a new reactor class called Hello.

The behavior of a reactor is defined by its reactions. A new reaction can be defined using the @xronos.reaction decorator on a reactor method. The decorated method accepts a single argument of type xronos.ReactionContext and returns a callable object (e.g. a function) that implements an event handler. Our example reactor defines a single reaction called hello:

plainwith type hints

@xronos.reaction
def hello(self, ctx):
    ctx.add_trigger(self.startup)
    return lambda: print("Hello, World!")

Xronos applications are event-driven. The runtime invokes a reaction handler once per timestamp at which any of the reaction’s triggers emits an event. The reaction context (named ctx in our examples) is how you declare which events trigger a reaction. In our example, hello is triggered by the builtin startup event source, which emits one event as execution begins. As we will discuss later, the context can also be used to define effects, which allow reactions to trigger new events, and to read the current time via current_time. The reaction handler returned by hello is a simple lambda function that prints “Hello, World!”.

Finally, the main() function assembles and executes the application.

def main() -> None:
    env = xronos.Environment()
    env.create_reactor("hello", Hello)
    env.execute()

We start by creating a xronos.Environment object, which we call env. The environment creates and contains top-level reactors, connects them, and executes the application. Reactors are created with the create_reactor() factory method. In our example, we create a reactor called “hello” that is an instance of the Hello class. Once your reactors are set up, execute() runs the application.

Every Xronos application can be rendered into a diagram that visualizes its reactors, elements, and connections. Here is the diagram for our hello world example.

See Diagram View for instructions on how to generate a diagram view.

Suggested development setup

Once you have the basics working, the following tools can make your development experience more productive.

Editor integration

We recommend Visual Studio Code for editing Xronos projects. It works well with diagram generation and supports on-target development or development on a remote machine over SSH.

See Installation for instructions on how to install the Xronos VS Code extension and for the VS Code extension’s system requirements.

Telemetry dashboard

See Dashboard for setup instructions and system requirements for viewing telemetry data from Xronos applications.

Enabling type checking

To get the most out of the Xronos SDK, we recommend enabling type checking using Pyright or Mypy. Both are well supported, and there are a few ways to configure them.

Microsoft’s Pylance VS Code extension provides Pyright-based type checking, which can be enabled by placing a pyrightconfig.json file such as the following in the root of your project:

{
    "typeCheckingMode": "strict"
}

Alternatively, you can use the following configuration in your pyproject.toml:

[tool.pyright]
typeCheckingMode = "strict"