Refactor crate features for more control over hash-maps usage (#1265)

* refactor crate features for more control over hash-maps usage

* fix GitHub CI build job

* remove superflous docs

Docs are superflous since it is obvious where to look-up the docs.

.github/workflows/rust.yml

@@ -36,14 +36,14 @@ jobs:
             --no-default-features
             --target x86_64-unknown-none
             --verbose
-      - name: Build (no_std + no-hash-maps)
+      - name: Build (no_std + hash-collections)
         run: >-
             cargo build
             --package wasmi
             --locked
             --lib
             --no-default-features
-            --features no-hash-maps
+            --features hash-collections
             --target x86_64-unknown-none
             --verbose
       - name: Build (no_std + wasm32)

crates/cli/Cargo.toml

@@ -24,8 +24,9 @@ wat = "1"
 assert_cmd = "2.0.7"
 
 [features]
-default = ["no-hash-maps"]
-no-hash-maps = ["wasmi/no-hash-maps"]
+default = []
+hash-collections = ["wasmi/hash-collections"]
+prefer-btree-collections = ["wasmi/prefer-btree-collections"]
 
 # We need to put this [profile.release] section due to this bug in Cargo:
 # https://github.com/rust-lang/cargo/issues/8264

crates/collections/Cargo.toml

@@ -14,24 +14,44 @@ categories.workspace = true
 exclude.workspace = true
 
 [dependencies]
-hashbrown = { version = "0.14", default-features = false, features = ["ahash", "inline-more"] }
-string-interner = { version = "0.17", default-features = false, features = ["inline-more", "backends"] }
-ahash = { version = "0.8.11", default-features = false }
+hashbrown = { version = "0.14", default-features = false, optional = true, features = ["ahash", "inline-more"] }
+string-interner = { version = "0.17", default-features = false, optional = true, features = ["inline-more", "backends"] }
+ahash = { version = "0.8.11", default-features = false, optional = true }
 
 [features]
-default = ["std", "no-hash-maps"]
+default = ["std"]
 std = ["string-interner/std"]
-# Tells the `wasmi_collections` crate to avoid using hash based maps and sets.
-# 
-# Some embedded environments cannot provide a random source which is required
-# to properly initialize hashmap based data structures for resilience against
-# malious actors that control their inputs.
+
+# Hash collections usage:
+#
+# - Enable `hash-collections` to make use of hash-based collections in `wasmi_collections`.
+# - Enable `prefer-btree-collections` to still use btree-based collections even when
+#   the `hash-collections` crate feature is enabled.
+#
+# Note:
+#
+# - Not enabling `hash-collections` allows `wasmi_collections` to drop lots of
+#   hash-based dependencies and thus decrease compilation times significantly.
+# - Btree-based collections can be useful for environments without a random source.
 #
-# An example of such an environment is `wasm32-unknown-unknown`.
-no-hash-maps = []
+# Which collections will be used:
+#
+# `hash-collections` | `prefer-btree-collections` |      usage
+# ------------------ | -------------------------- | -------------------
+#            false   |                    false   |      btree
+#             true   |                    false   |      hash
+#            false   |                     true   |      btree
+#             true   |                     true   |      btree
+#
+hash-collections = [
+  'dep:hashbrown',
+  'dep:string-interner',
+  'dep:ahash',
+]
+prefer-btree-collections = []
 
 [package.metadata.cargo-udeps.ignore]
 normal = [
-    # The string-interner dependency is always specified even though it is unused when no-hash-maps is enabled.
+    # Needed to suppress weird `udep` warnings. Maybe a `cargo-udep` bug?
     "string-interner"
 ]

crates/collections/src/lib.rs

@@ -37,6 +37,7 @@ extern crate alloc as std;
 extern crate std;
 
 pub mod arena;
+#[cfg(feature = "hash-collections")]
 pub mod hash;
 mod head_vec;
 pub mod map;

crates/collections/src/map.rs

@@ -3,7 +3,10 @@
 use core::{borrow::Borrow, hash::Hash, iter::FusedIterator, ops::Index};
 use std::fmt::Debug;
 
-#[cfg(not(feature = "no-hash-maps"))]
+#[cfg(all(
+    feature = "hash-collections",
+    not(feature = "prefer-btree-collections")
+))]
 mod detail {
     use crate::hash;
     use hashbrown::hash_map;
@@ -22,7 +25,10 @@ mod detail {
     pub type IntoValuesImpl<K, V> = hash_map::IntoValues<K, V>;
 }
 
-#[cfg(feature = "no-hash-maps")]
+#[cfg(any(
+    not(feature = "hash-collections"),
+    feature = "prefer-btree-collections"
+))]
 mod detail {
     use std::collections::btree_map;
 
@@ -155,9 +161,15 @@ where
     /// Reserves capacity for at least `additional` more elements to be inserted in the [`Map`].
     #[inline]
     pub fn reserve(&mut self, additional: usize) {
-        #[cfg(not(feature = "no-hash-maps"))]
+        #[cfg(all(
+            feature = "hash-collections",
+            not(feature = "prefer-btree-collections")
+        ))]
         self.inner.reserve(additional);
-        #[cfg(feature = "no-hash-maps")]
+        #[cfg(any(
+            not(feature = "hash-collections"),
+            feature = "prefer-btree-collections"
+        ))]
         let _ = additional;
     }
 

crates/collections/src/set.rs

@@ -8,7 +8,10 @@ use core::{
     ops::{BitAnd, BitOr, BitXor, Sub},
 };
 
-#[cfg(not(feature = "no-hash-maps"))]
+#[cfg(all(
+    feature = "hash-collections",
+    not(feature = "prefer-btree-collections")
+))]
 mod detail {
     use crate::hash;
     use hashbrown::hash_set;
@@ -23,7 +26,10 @@ mod detail {
     pub type UnionImpl<'a, T> = hash_set::Union<'a, T, hash::RandomState>;
 }
 
-#[cfg(feature = "no-hash-maps")]
+#[cfg(any(
+    not(feature = "hash-collections"),
+    feature = "prefer-btree-collections"
+))]
 mod detail {
     use std::collections::btree_set;
 
@@ -105,9 +111,15 @@ where
     /// Reserves capacity for at least `additional` more elements to be inserted in the [`Set`].
     #[inline]
     pub fn reserve(&mut self, additional: usize) {
-        #[cfg(not(feature = "no-hash-maps"))]
+        #[cfg(all(
+            feature = "hash-collections",
+            not(feature = "prefer-btree-collections")
+        ))]
         self.inner.reserve(additional);
-        #[cfg(feature = "no-hash-maps")]
+        #[cfg(any(
+            not(feature = "hash-collections"),
+            feature = "prefer-btree-collections"
+        ))]
         let _ = additional;
     }
 

crates/collections/src/string_interner.rs

@@ -1,6 +1,9 @@
 //! Data structure to efficiently store and deduplicate strings.
 
-#[cfg(not(feature = "no-hash-maps"))]
+#[cfg(all(
+    feature = "hash-collections",
+    not(feature = "prefer-btree-collections")
+))]
 mod detail {
     use super::{GetOrInternWithHint, Sym};
     use crate::hash;
@@ -34,7 +37,10 @@ mod detail {
     }
 }
 
-#[cfg(feature = "no-hash-maps")]
+#[cfg(any(
+    not(feature = "hash-collections"),
+    feature = "prefer-btree-collections"
+))]
 mod detail;
 
 /// Internment hint to speed-up certain use cases.

crates/wasmi/Cargo.toml

@@ -40,22 +40,16 @@ anyhow = "1.0"
 criterion = { version = "0.5", default-features = false }
 
 [features]
-default = ["std", "no-hash-maps"]
+default = ["std"]
 std = [
     "wasmi_core/std",
     "wasmi_collections/std",
     "wasmparser/std",
     "spin/std",
     "arrayvec/std",
 ]
-# Tells the `wasmi` crate to avoid using hash based data structures.
-# 
-# Some embedded environments cannot provide a random source which is required
-# to properly initialize hashmap based data structures for resilience against
-# malious actors that control their inputs.
-#
-# An example of such an environment is `wasm32-unknown-unknown`.
-no-hash-maps = ["wasmi_collections/no-hash-maps"]
+hash-collections = ["wasmi_collections/hash-collections"]
+prefer-btree-collections = ["wasmi_collections/prefer-btree-collections"]
 
 # Enables extra checks performed during Wasmi bytecode execution.
 #