Documentation	Build Status

Rocket.jl is a Julia package for reactive programming using Observables, to make it easier to work with asynchronous data.

In order to achieve best performance and convenient API Rocket.jl combines Observer pattern, Actor model and Functional programming.

Inspired by RxJS and ReactiveX communities.

Rocket.jl has been designed with a focus on performance and modularity.

The essential concepts in Rocket.jl are:

• Observable: represents a collection of future messages (data or/and events).
• Actor: is an object that knows how to react on incoming messages delivered by the Observable.
• Subscription: represents a teardown logic which might be useful for cancelling the execution of an Observable.
• Operators: are objects that enable a functional programming style to dealing with collections with operations like map, filter, reduce, etc.
• Subject: the way of multicasting a message to multiple Observers.

For a quick start and basic introduction take a look at the demo folder and Quick Start notebook.

using Rocket, Compose, IJulia ; set_default_graphic_size(35cm, 2cm)

function draw_ball(t)
    IJulia.clear_output(true)
    x = -exp(-0.01t) + 1                     # x coordinate
    y = -abs(exp(-0.04t)*(cos(0.1t))) + 0.83 # y coordinate
    display(compose(context(), circle(x, y, 0.01)))
end

source = interval(20) |> take(200) # Take only first 200 emissions

subscription = subscribe!(source, draw_ball)

unsubscribe!(subscription) # It is possible to unsubscribe before the stream ends    
IJulia.clear_output(false);

Full documentation is available at reactivebayes website.

It is also possible to build a documentation locally. Just execute

$ julia make.jl

in the docs/ directory to build a local version of the documentation.

Normally you use an arrays for processing some data.

for value in array_of_values
    doSomethingWithMyData(value)
end

In Rocket.jl you will use an observable.

subscription = subscribe!(source_of_values, lambda(
    on_next     = (data)  -> doSomethingWithMyData(data),
    on_error    = (error) -> doSomethingWithAnError(error),
    on_complete = ()      -> println("Completed!")
))

At some point of time you may decide to stop listening for new messages.

unsubscribe!(subscription)

To process messages from an observable you have to define an Actor that know how to react on incoming messages.

struct MyActor <: Rocket.Actor{Int} end

Rocket.on_next!(actor::MyActor, data::Int) = doSomethingWithMyData(data)
Rocket.on_error!(actor::MyActor, error)    = doSomethingWithAnError(error)
Rocket.on_complete!(actor::MyActor)        = println("Completed!")

Actor can also have its own local state

struct StoreActor{D} <: Rocket.Actor{D}
    values :: Vector{D}

    StoreActor{D}() where D = new(Vector{D}())
end

Rocket.on_next!(actor::StoreActor{D}, data::D) where D = push!(actor.values, data)
Rocket.on_error!(actor::StoreActor, error)             = doSomethingWithAnError(error)
Rocket.on_complete!(actor::StoreActor)                 = println("Completed: $(actor.values)")

For debugging purposes you can use a general LambdaActor actor or just pass a function object as an actor in subscribe! function.

What makes Rocket.jl powerful is its ability to help you process, transform and modify the messages flow through your observables using Operators.

List of all available operators can be found in the documentation (link).

squared_int_values = source_of_int_values |> map(Int, (d) -> d ^ 2)
subscribe!(squared_int_values, lambda(
    on_next = (data) -> println(data)
))

Rocket.jl has been designed with a focus on efficiency, scalability and maximum performance. Below is a benchmark comparison between Rocket.jl, Signals.jl, Reactive.jl and Observables.jl in Julia v1.9.3 (see versioninfo below).

We test map and filter operators latency in application to a finite stream of integers. Code is available in demo folder.

Rocket.jl outperforms Observables.jl, Reactive.jl and Signals.jl significantly in terms of execution times and memory consumption both in synchronous and asynchronous modes.

versioninfo()

Julia Version 1.9.3
Commit bed2cd540a1 (2023-08-24 14:43 UTC)
Build Info:
  Official https://julialang.org/ release
Platform Info:
  OS: macOS (arm64-apple-darwin22.4.0)
  CPU: 10 × Apple M2 Pro
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-14.0.6 (ORCJIT, apple-m1)
  Threads: 1 on 6 virtual cores
Environment:
  JULIA_NUM_THREADS = 

] status

  [6e4b80f9] BenchmarkTools v1.3.2
  [510215fc] Observables v0.5.4
  [a223df75] Reactive v0.8.3
  [df971d30] Rocket v1.7.2
  [6303bc30] Signals v1.2.0

MIT License Copyright (c) 2021-2024 BIASlab, 2024-present ReactiveBayes