artichoke/cactusref

🌵 Cycle-Aware Reference Counting in Rust

Artichoke Ruby

Artichoke is a Ruby implementation written in Rust and Ruby. Artichoke intends to be MRI-compatible and targets recent MRI Ruby. Artichoke provides a Ruby runtime implemented in Rust and Ruby.

Try Artichoke

Artichoke Ruby Wasm Playground

You can try Artichoke in your browser. The Artichoke Playground runs a WebAssembly build of Artichoke.

Install Artichoke

Prebuilt nightly binaries

Download a prebuilt binary from artichoke/nightly. Binaries are available for Linux, Linux/musl, macOS, and Windows.

These daily binaries track the latest trunk branch of Artichoke.

Binaries are also distributed through ruby-build. To install with rbenv:

$ rbenv install artichoke-dev

Cargo

You can install a pre-release build of Artichoke using cargo, Rust's package manager, by running:

$ cargo install --git https://github.com/artichoke/artichoke --branch trunk --locked artichoke

To install via cargo install or to checkout and build locally, you'll need Rust and clang. BUILD.md has more detail on how to set up the compiler toolchain.

Docker

Artichoke is available on Docker Hub.

You can launch a REPL by running:

docker run -it docker.io/artichokeruby/artichoke airb

Usage

Artichoke ships with two binaries: airb and artichoke.

airb

airb is the Artichoke implementation of irb and is an interactive Ruby shell and REPL.

airb is a readline-enabled shell, although it does not persist history.

artichoke

artichoke is the ruby binary frontend to Artichoke.

artichoke supports executing programs via files, stdin, or inline with one or more -e flags.

Artichoke can require, require_relative, and load files from the local file system, but otherwise does not yet support local file system access. A temporary workaround is to inject data into the interpreter with the --with-fixture flag, which reads file contents into a $fixture global.

$ artichoke --help
Artichoke is a Ruby made with Rust.

Usage: artichoke [OPTIONS] [programfile] [arguments]...

Arguments:
  [programfile]
  [arguments]...

Options:
      --copyright               print the copyright
  -e <commands>                 one line of script. Several -e's allowed. Omit [programfile]
      --with-fixture <fixture>  file whose contents will be read into the `$fixture` global
  -h, --help                    Print help
  -V, --version                 Print version

Design and Goals

Artichoke is designed to enable experimentation. The top goals of the project are:

• Support WebAssembly as a build target.
• Support embedding and executing Ruby in untrusted environments.
• Distribute Ruby applications as single-binary artifacts.
• Implement Ruby with state-of-the-art dependencies.
• Experiment with VMs to support dynamic codegen, ahead of time compilation, parallelism and eliminating the GIL, and novel memory management and garbage collection techniques.

Contributing

Artichoke aspires to be an MRI Ruby-compatible implementation of the Ruby programming language. There is lots to do.

If Artichoke does not run Ruby source code in the same way that MRI does, it is a bug and we would appreciate if you filed an issue so we can fix it.

If you would like to contribute code 👩‍💻👨‍💻, find an issue that looks interesting and leave a comment that you're beginning to investigate. If there is no issue, please file one before beginning to work on a PR. Good first issues are labeled E-easy.

Discussion

If you'd like to engage in a discussion outside of GitHub, you can join Artichoke's public Discord server.

License

artichoke is licensed with the MIT License (c) Ryan Lopopolo.

Some portions of Artichoke are derived from third party sources. The READMEs in each workspace crate discuss which third party licenses are applicable to the sources and derived works in Artichoke.

cactusref's Issues

Add a `CONTRIBUTING.md`

Using the one in intaglio as a template should be sufficient.

https://github.com/artichoke/intaglio/blob/5fe9b5e7203472aa0be73fd24b23e3f4d2031435/CONTRIBUTING.md

Can the dropck_eyepatch nightly feature be removed?

The code compiles without the may_dangle annotation. Is that all that is needed?

Add Docs on Unsafety to Crate Root and README

The Rc implementation of Adoptable includes some docs on the safety implications of using these APIs incorrectly. This documentation should exist prominently in the crate root and the README

cactusref/src/adoptable.rs

Lines 42 to 50 in 3870a4e

	/// # Safety
	///
	/// Modifying the object graph by removing links after calling `adopt`
	/// requires updating the bookkeeping with [`unadopt`](Adoptable::unadopt).
	/// Failure to properly remove links from the object graph may cause `Drop`
	/// to detect a cycle is not externally reachable, reulting in prematurely
	/// deallocating the entire cycle and turning all reachable [`Rc`]s into
	/// dangling pointers. `CactusRef` makes a best-effort attempt to abort the
	/// program if an access to a dead `Rc` occurs.

Re-enable cargo bench build step

Disabled in GH-2 because it segfaults in the circleci environment.

Add GitHub labels

Add labels to match the conventions used in Artichoke and playground.

`Rc::adopt` requires both `T`s to be the same

Say I'm making a structure that contains something else - this does not work:

impl Container{
	fn new(contained: Rc<Contained>) -> Rc<Self> {
		let new = Rc::new(Self { contained });
		unsafe { Rc::adopt(&new, &new.contained) };
		new
	}
}

That's because Rc::adopt requires both Ts to be the same. Is this intended? I looked at the linked list example, and it looks like it's calling adopt like Rc::adopt(&parent, &child) for every Rc<Node<T>> that contains an Rc<Node<T>>, and that only works because Node<T> is itself.

Add a LeakSanitizer workflow to CI

The last time I tried this, leaks were detected. I think related to dropping the embedded hashmap?

Update to 2021 edition

This library hasn't been updated in almost a year, so it's still on the 2018 edition. 2021 is stable now, so it should be safe to use now.

Resync `Rc` fork from upstream `std`

Upstream PRs to library/alloc/src/rc.rs since cactusref forked from rust-lang/rust@f586d79:

• rust-lang/rust#87467
• rust-lang/rust#87530
• rust-lang/rust#88226
• rust-lang/rust#89741
• rust-lang/rust#89833
• rust-lang/rust#90666
• rust-lang/rust#91589
• rust-lang/rust#93109
• rust-lang/rust#94991
• rust-lang/rust#95241

Add cargo-spellcheck config

See this example PR in intaglio:

• artichoke/intaglio#142

Add .editorconfig

An .editorconfig is a cross-editor and cross-ide format configuration mechanism which and enforce Artichoke code formatting conventions.

Specify:

• utf-8 charset
• strip trailing whitespace except diff and markdown
• eol = lf
• spacing

for file types:

• rs
• md
• sh
• h, c, cc, cpp
• Makefile, .make
• diff
• json
• js
• ts
• css
• html
• svg
• xml
• yml, yaml
• erb
• rb
• json
• toml
• Dockerfile

Add tests to assert cycles are fully dropped

Using a custom inner T that increments / decrements an AtomicU64 on new / drop.

To make sure these are useful under LeakSanitizer too – #102 – let's shove a String field with something like "abc".repeat(100) into the T as well.

Test with LeakSanitizer

Add a CI job to run tests under leak sanitizer.

What would be needed to also support a threadsafe Arc-like?

I didn't find this in the docs so I thought about asking! Is cactusref's approach fundamentally incompatible with multithreading, or it's just that currently the implementation is focusing in single-threaded Rc?