Release Day 🎉

[Tamschi]

🌱 Hello flourish!

Well, that's another OSS project launched, finally. This time I'm trying to make signals intuitive, remove boilerplate, improve flexibility and encourage performance-aware application code.

Quick quick-start:

# for apps and testing; libraries should be generic over `SR: SignalsRuntimeRef`.
cargo add flourish --features global_signals_runtime

use flourish::{shadow_clone, GlobalSignalsRuntime};

// Choose a runtime:
type Signal<T, S> = flourish::Signal<T, S, GlobalSignalsRuntime>;

let a = Signal::cell("a");
let b = Signal::cell("b");
let c = Signal::cell("c");
let d = Signal::cell("d");
let e = Signal::cell("e");
let f = Signal::cell("f");
let g = Signal::cell("g");
let index = Signal::cell(0);

// With side-effect for demo purposes. Normally you'd use an `Effect`.
let signal = Signal::computed({
  shadow_clone!(a, b, c, d, e, f, g, index);
  move || println!("{}", match index.get() {
    1 => a.get(),
    2 => b.get(),
    3 => c.get(),
    4 => d.get(),
    5 => e.get(),
    6 => f.get(),
    7 => g.get(),
    _ => "",
  })
}); // nothing

// For demo purposes, the original `SignalArc` is preserved here.
// To consume it, write `.into_subscription()`, which is more efficient.
let subscription = signal.to_subscription(); // ""

// Note: `change` and `replace` may be deferred (but are safe to use in callbacks)!
//        Use the `…_blocking` and `…_async` variants as needed.
a.replace("a"); b.replace("b"); // nothing
index.change(1); // "a" ("change" methods don't replace or propagate if the value is equal)
a.change("aa"); // "aa"
b.change("bb"); // nothing
index.change(2); // "bb"
a.change("a"); // nothing
b.change("b"); // "b"

drop(subscription);
index.change(3); // nothing, even though `signal` still exists

drop(signal);

You can also use unmanaged, locally-pinned signals, which don't allocate (given a runtime that doesn't. The included one is unbounded).
See the README and docs.rs for that and much¹ more.

To be honest, this library came about as just a building block towards another, long-running project, but since flourish seems useful more generally, I decided to polish it up and release it properly as stand-alone crate. After all, if it's already a standard proposal for another programming language then the design is likely at least somewhat sought for 😉

Note that I've taken a lot of liberties in the adaption to make it overall more idiomatic in Rust, so if there's strangeness, that's likely on my part. I also haven't implemented containers-that-are-signals, but doing so should be fairly straightforward with my approach.

In any case, if you try out this library here, please let me know what you think! 🙇
To me the API is intuitive, but I've worked on this on-and-off for a few months, so it's difficult for me to tell how it would look like with fresh eyes. There are a few areas I'd like feedback on specifically:

• Is the onboarding intuitive? Did you notice you can expand the README is the crate root docs?
• Do the documentation tests works as usage examples? Are they not verbose enough? Too verbose?
• Is the behaviour of the different Propagation variants easy to understand?
• Did you hit any roadblocks where you tried to do something in one way but it didn't work out?

If you have any other comments, do let me know about those also!
You can do that either directly here in the comments or by making a new thread in one of the other categories.
(Requests for breaking changes are fine too! I'd like to get those sorted before v1.0.0, even though flourish itself contains no statics.)

🌬️ Hello isoprenoid!

isoprenoid (README) is the signals runtime interface, default implementation, and safe-Rust raw signal abstraction that underlies flourish. You can use this library to make alternative but compatible signal APIs that don't rely on mine:

• Implement SignalsRuntimeRef for custom runtimes with different refresh schedules.
  You could make a bounded, non-allocating runtime or one that propagates only once per outside (game) tick, too.
• Wrap RawSignal to create your own signal abstractions in safe-Rust. (All of flourish is made this way.)
  Alternatively, call into SignalsRuntimeRef::start directly to set your signal's callbacks.

Footnotes

1. type-erasure, weak references, async/eager/blocking accessors, shared-from-ref, cell update via transactional callbacks, subscription-reactive cells, Future and Option interop, flushing resource release, … ↩