Atmos

This is the unstable (probably broken) main branch towards v0.3.

For a stable release, please switch to v0.2.1.

[ v0.3 | v0.2.1 | v0.1 ]

Structured Event-Driven Concurrency for Lua

[ About | Install | Hello World! | Documentation | Resources ]

About

Atmos is a programming library for Lua that reconciles Structured Concurrency, [Event-Driven Programming][events], and Functional Streams, extending classical structured programming with three main functionalities:

• Structured Deterministic Concurrency:
  • A task primitive with deterministic scheduling provides predictable behavior and safe abortion.
  • Structured primitives compose concurrent tasks with lexical scope (e.g., watching, every, par_or).
  • A tasks container primitive holds attached tasks and control their lifecycle.
• Event Signaling Mechanisms:
  • An await primitive suspends a task and wait for events.
  • An emit primitive signal events and awake awaiting tasks.
• Pull-Based Streams (à la JavaStreams):
  • Functional combinators for lazy (infinite) lists.
  • Interoperability with tasks & events: streams can have tasks and awaits as sources, streams can signal events (TODO), and tasks can await streams (TODO).
  • Proper finalization of stateful (task-based) streams.

Atmos is inspired by synchronous programming languages like Ceu and Esterel.

Hello World!

During 5 seconds, displays Hello World! every second:

require "atmos.env.clock"

call(function ()
    watching(clock{s=5}, function ()
        every(clock{s=1}, function ()
            print("Hello World!")
        end)
    end)
end)

We first the builtin clock environment, which provides timers to applications. The call primitive receives a function with the application logic in Atmos, as follows:

• The watching command will execute its inner function during 5 seconds.
• The every loop will execute its inner function every second.
• Once the watching terminates, the call returns back to Lua.

Now, the same specification, but using streams:

require "atmos.env.clock"
local S = require "atmos.streams"

call(function ()
    local s1 = S.from(clock{s=5}):take(1)
    local s2 = S.from(clock{s=1})
    s1:paror(s2)
        :to_each(function()
            print("Hello World!")
        end)
end)

Install & Run

sudo luarocks install atmos --lua-version=5.4
lua5.4 <lua-path>/atmos/env/clock/exs/hello.lua

You may also clone the repository and copy part of the source tree, as follows, into your Lua path (e.g., /usr/local/share/lua/5.4):

atmos
├── env/
│   ├── clock/
│   │   ├── exs/
│   │   │   ├── hello.lua
│   │   │   └── hello-rx.lua
│   │   └── init.lua
│   ├── iup/
│   │   ├── exs/
│   │   │   ├── button-counter.lua
│   │   └── init.lua
│   ├── sdl/
│   │   ├── exs/
│   │   │   ├── click-drag-cancel.lua
│   │   │   └── DejaVuSans.ttf
│   │   └── init.lua
│   └── socket/
│       ├── exs/
│       │   └── cli-srv.lua
│       └── init.lua
├── init.lua
├── run.lua
├── streams.lua
└── util.lua

Atmos depends on f-streams.

Documentation

• Guide
• API

Environments

An environment is an external component that bridges input events from the real world into an Atmos application.

The standard distribution of Atmos provides the following environments:

• atmos.env.clock: A simple pure-Lua environment that uses os.clock to issue timer events.
• atmos.env.socket: An environment that relies on luasocket to provide network communication.
• atmos.env.sdl: An environment that relies on lua-sdl2 to provide window, mouse, key, and timer events.
• atmos.env.iup: An environment that relies on IUP (iup-lua) to provide graphical user interfaces (GUIs).

Resources

• A toy problem: Drag, Click, or Cancel
  • click-drag-cancel.lua
• A simple but complete 2D game in Atmos:
  • https://github.com/lua-atmos/sdl-rocks/
• Academic publications (Ceu):
  • http://ceu-lang.org/chico/#ceu
• Mailing list (Ceu):
  • https://groups.google.com/g/ceu-lang