diff --git a/.github/labels.json b/.github/labels.json index b7b8fa7a37d..b2a74a7ba89 100644 --- a/.github/labels.json +++ b/.github/labels.json @@ -15,15 +15,20 @@ "description": "Area: Compile-time features or attributes." }, { - "name": "A-hash-table", + "name": "A-data-structure", "color": "f7e101", - "description": "Area: st_table." + "description": "Area: StHashMap and StHashSet." }, { "name": "A-deps", "color": "f7e101", "description": "Area: Source and library dependencies." }, + { + "name": "A-hash-table", + "color": "f7e101", + "description": "Area: st_table." + }, { "name": "A-performance", "color": "f7e101", @@ -39,6 +44,11 @@ "color": "f7e101", "description": "Area: crates.io releases and version bumps." }, + { + "name": "A-Rust-API", + "color": "f7e101", + "description": "Area: Rust API wrapper around core data structure." + }, { "name": "A-security", "color": "f7e101", diff --git a/README.md b/README.md index 1c7bb526a82..42afa405272 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,16 @@ Insertion-ordered hash table suitable for embedding via FFI. -Drop-in replacement for `st_hash` originally written by Peter Moore @ UCB and -used in [Ruby]'s [implementation][st.c] of the [`Hash`][hash] core class. +Status: Work in progress. + +Strudel was conceived as a drop-in replacement for `st_hash`, a hash map +implemented in C originally written by Peter Moore @ UCB and used in [Ruby]'s +[implementation][st.c] of the [`Hash`][hash] core class. + +This crate is an exercise in implementing an insertion-ordered hash map in Rust +that cannot use the built-in `Hasher` infrastructure. The implementation uses +[Ruby's `Hash` backend][sthash-notes] and [Python's dict][pydict-notes] as prior +art. `StHashMap` is designed to implement the `st_hash` C API and be FFI-friendly. @@ -47,6 +55,32 @@ All features are enabled by default. - **capi-specialized-init** - Enables additional `st_init_table` C APIs with known `st_hash_type`s for tables with numeric and string keys. +## Building Ruby with Strudel + +Strudel exports most of the symbols implemented by `st.c` in MRI 2.6.3. The +[included patch](strudelify-mri.patch) and some +[`configure` arguments](build.sh) can build the bootstrapping phase of MRI 2.6.3 +with Strudel as the hash backend. + +To build `miniruby` with Strudel, run: + +```sh +./build.sh +``` + +The resulting Ruby is in `./build/ruby-strudel-build-root/miniruby`. `miniruby` +can run simple scripts involving `Hash`, for example: + +```console +$ ./build/ruby-strudel-build-root/miniruby -e 'h = {}' -e '1000.times { |i| h[i] = i }' -e 'puts h.length' +1000 +``` + +`miniruby` successfully executes the benchmarks in [`benches`](benches). + +NOTE: Strudel cannot build a full Ruby due to bugs in the implementation of the +`st_hash` API. + ## License `strudel` is licensed under the [MIT License](LICENSE) (c) Ryan Lopopolo. @@ -67,6 +101,9 @@ The `st_hash` implementation in Ruby includes the following notice: [ruby]: https://github.com/ruby/ruby [st.c]: https://github.com/ruby/ruby/blob/v2_6_3/st.c [hash]: https://ruby-doc.org/core-2.6.3/Hash.html +[sthash-notes]: https://github.com/ruby/ruby/blob/v2_6_3/st.c#L1-L101 +[pydict-notes]: + https://github.com/python/cpython/blob/v3.8.4/Objects/dictobject.c#L1-L110 [`hashmap`]: https://doc.rust-lang.org/std/collections/struct.HashMap.html [`vec`]: https://doc.rust-lang.org/std/vec/struct.Vec.html [`libc`]: https://crates.io/crates/libc