Merge pull request #27 from frengor/dev

* Update version to 0.3.0
* Add cleaners and weak pointers
* Add the derive macros for `Trace` and `Finalize`
* Add no-std support
* Improve documentation
* Remove invalid `Cc`s and rework `Cc::new_cyclic` to use weak pointers
* Countless small fixes and improvements

Author: frengor

.github/workflows/bench.yml

@@ -5,7 +5,9 @@ on:
     types: [labeled]
 
 env:
+  IAI_CALLGRIND_VERSION: 0.7.3
   CARGO_TERM_COLOR: always
+  IAI_CALLGRIND_COLOR: never
   CARGO_REGISTRIES_CRATES_IO_PROTOCOL: sparse
 
 jobs:
@@ -22,20 +24,22 @@ jobs:
         with:
           ref: ${{ github.event.pull_request.base.ref }}
       - uses: dtolnay/rust-toolchain@stable
+      - uses: taiki-e/install-action@valgrind
+      - uses: taiki-e/install-action@cargo-binstall
+      - name: Install iai-callgrind-runner
+        run: cargo binstall --no-confirm --no-symlinks iai-callgrind-runner --version ${IAI_CALLGRIND_VERSION}
       - name: Bench base branch
         run: |
-          sudo apt-get update
-          sudo apt-get install -y valgrind
           cargo update
-          cargo bench -F full -q --bench bench > "${WORKSPACE}"/____old_results.txt
+          cargo bench -q --bench bench > "${WORKSPACE}"/____old_results.txt
       - uses: actions/checkout@v3
         with:
           ref: ${{ github.event.pull_request.head.ref }}
           clean: false
       - name: Bench head branch
         run: |
           cargo update
-          cargo bench -F full -q --bench bench > "${WORKSPACE}"/____results.txt
+          cargo bench -q --bench bench > "${WORKSPACE}"/____results.txt
       - uses: actions/checkout@v3
         with:
           ref: ${{ github.event.pull_request.base.ref }}
@@ -44,36 +48,44 @@ jobs:
         run: |
           cargo clean
           cargo update
-          cargo bench --no-default-features -F auto-collect -q --bench bench > "${WORKSPACE}"/____old_results_no_finalization.txt
+          cargo bench --no-default-features -F std,derive,auto-collect -q --bench bench > "${WORKSPACE}"/____old_results_no_finalization.txt
       - uses: actions/checkout@v3
         with:
           ref: ${{ github.event.pull_request.head.ref }}
           clean: false
       - name: Bench head branch no finalization
         run: |
           cargo update
-          cargo bench --no-default-features -F auto-collect -q --bench bench > "${WORKSPACE}"/____results_no_finalization.txt
+          cargo bench --no-default-features -F std,derive,auto-collect -q --bench bench > "${WORKSPACE}"/____results_no_finalization.txt
       - name: Write comment
         run: |
           {
             echo '<strong>Benchmark results:</strong>'
             echo ''
+            echo '```txt'
             cat "${WORKSPACE}"/____results.txt
+            echo '```'
             echo ''
             echo '<details><summary><strong>Old results:</strong></summary><p>'
             echo ''
+            echo '```txt'
             cat "${WORKSPACE}"/____old_results.txt
+            echo '```'
             echo '</p></details>'
             echo ''
             echo '---'
             echo ''
             echo '<details><summary><strong>Results without finalization:</strong></summary><p>'
             echo ''
+            echo '```txt'
             cat "${WORKSPACE}"/____results_no_finalization.txt
+            echo '```'
             echo ''
             echo '<details><summary><strong>Old results without finalization:</strong></summary><p>'
             echo ''
+            echo '```txt'
             cat "${WORKSPACE}"/____old_results_no_finalization.txt
+            echo '```'
             echo '</p></details></p></details>'
           } > "${WORKSPACE}"/__result.txt
       - uses: thollander/[email protected]

.github/workflows/build.yml

@@ -5,25 +5,42 @@ on: [push, pull_request, workflow_dispatch]
 env:
   CARGO_TERM_COLOR: always
   CARGO_REGISTRIES_CRATES_IO_PROTOCOL: sparse
+  RUSTDOCFLAGS: -D warnings
 
 jobs:
-  build-on-stable:
+  on-stable:
     runs-on: ubuntu-latest
+    env:
+      RUSTFLAGS: -D warnings
     steps:
       - uses: actions/checkout@v3
       - uses: dtolnay/rust-toolchain@stable
-      - name: Build
+        with:
+          components: clippy
+      - uses: taiki-e/install-action@cargo-hack
+      - name: Check and Clippy
+        # Keep "std" feature always enabled on stable to avoid needing the no-std related nightly features
         run: |
-          cargo build --no-default-features --verbose --workspace
-          cargo build --verbose --workspace
-          cargo build -F full --verbose --workspace
-  build-on-nightly:
+          cargo hack check --all-targets --feature-powerset --ignore-unknown-features --workspace --skip nightly --clean-per-run --verbose -F std
+          cargo hack check --all-targets --feature-powerset --ignore-unknown-features --workspace --skip nightly --clean-per-run --verbose -F std --release
+          cargo hack clippy --all-targets --feature-powerset --ignore-unknown-features --workspace --skip nightly --clean-per-run --verbose -F std -- -D warnings
+  on-nightly:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
       - uses: dtolnay/rust-toolchain@nightly
-      - name: Build
+        with:
+          components: clippy
+      - uses: taiki-e/install-action@cargo-hack
+      - name: Check and Clippy (nightly)
         run: |
-          cargo build --no-default-features -F nightly --verbose --workspace
-          cargo build -F nightly --verbose --workspace
-          cargo build -F full,nightly --verbose --workspace
+          cargo hack check --all-targets --feature-powerset --ignore-unknown-features --workspace --clean-per-run --verbose -F nightly
+          cargo hack clippy --all-targets --feature-powerset --ignore-unknown-features --workspace --clean-per-run --verbose -F nightly
+        # cargo hack clippy --all-targets --feature-powerset --ignore-unknown-features --workspace --clean-per-run --verbose -F nightly -- -D warnings
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: dtolnay/rust-toolchain@nightly
+      - name: Build docs
+        run: cargo doc --no-deps --all-features --verbose

.github/workflows/miri.yml

@@ -17,11 +17,12 @@ jobs:
           rustup toolchain install nightly --component miri
           rustup override set nightly
           cargo miri setup
-      - name: Run tests (no features)
-        run: cargo miri test --no-default-features -F pedantic-debug-assertions --verbose --workspace
-      - name: Run tests (default features)
-        run: cargo miri test -F pedantic-debug-assertions --verbose --workspace
-      - name: Run tests (feature full)
-        run: cargo miri test -F full,pedantic-debug-assertions --verbose --workspace
-      - name: Run tests (every feature)
-        run: cargo miri test --all-features --verbose --workspace
+      - uses: taiki-e/install-action@cargo-hack
+      # Always skip "derive" since derive macro tests are skipped on Miri
+      # Also always keep "pedantic-debug-assertions" enabled to reduce build times
+      # Note: no need to use --workspace here, since there's no unsafe in rust-cc-derive
+      - name: Run tests
+        # Keep "std" feature always enabled here to avoid needing the no-std related nightly features
+        run: cargo hack miri test --feature-powerset --skip nightly,derive --verbose -F std,pedantic-debug-assertions
+      - name: Run tests (nightly)
+        run: cargo hack miri test --feature-powerset --skip derive --verbose -F nightly,pedantic-debug-assertions

.github/workflows/test.yml

@@ -7,24 +7,21 @@ env:
   CARGO_REGISTRIES_CRATES_IO_PROTOCOL: sparse
 
 jobs:
-  test:
+  on-stable:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: taiki-e/install-action@cargo-hack
+      - name: Run tests
+        # Keep "std" feature always enabled on stable to avoid needing the no-std related nightly features
+        run: |
+          cargo hack test --feature-powerset --ignore-unknown-features --workspace --skip nightly --verbose -F std
+  on-nightly:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
       - uses: dtolnay/rust-toolchain@nightly
-      - name: Build (no features)
-        run: cargo build --no-default-features -F pedantic-debug-assertions --verbose --workspace
-      - name: Run tests (no features)
-        run: cargo test --no-default-features -F pedantic-debug-assertions --verbose --workspace
-      - name: Build (default features)
-        run: cargo build -F pedantic-debug-assertions --verbose --workspace
-      - name: Run tests (default features)
-        run: cargo test -F pedantic-debug-assertions --verbose --workspace
-      - name: Build (feature full)
-        run: cargo build -F full,pedantic-debug-assertions --verbose --workspace
-      - name: Run tests (feature full)
-        run: cargo test -F full,pedantic-debug-assertions --verbose --workspace
-      - name: Build (every feature)
-        run: cargo build --all-features --verbose --workspace
-      - name: Run tests (every feature)
-        run: cargo test --all-features --verbose --workspace
+      - uses: taiki-e/install-action@cargo-hack
+      - name: Run tests
+        run: cargo hack test --feature-powerset --ignore-unknown-features --workspace --verbose -F nightly

CONTRIBUTING.md

@@ -12,19 +12,20 @@ The core idea behind the algorithm is the same as the one presented by Lins in [
 and by Bacon and Rajan in ["Concurrent Cycle Collection in Reference Counted Systems"](https://pages.cs.wisc.edu/~cymen/misc/interests/Bacon01Concurrent.pdf).  
 However, the implementation differs in order to make the collector faster and more resilient to random panics and failures in general.
 
-> **N.B.:** `rust-cc` is *not* strictly an implementation of the algorithm shown in the linked papers and it's never been
+> [!IMPORTANT]  
+> `rust-cc` is *not* strictly an implementation of the algorithm shown in the linked papers and it's never been
 > intended as such. Feel free to propose any kind of improvement!
 
 The following is a summarized version of the collection algorithm:  
 When a `Cc` smart pointer is dropped, the reference count (RC) is decreased by 1. If it reaches 0, then the allocated
-object pointed by the `Cc` (called `CcOnHeap`) is dropped, otherwise the `Cc` is put into the `POSSIBLE_CYCLES` list.  
+object pointed by the `Cc` (called `CcBox`) is dropped, otherwise the `Cc` is put into the `POSSIBLE_CYCLES` list.  
 The `POSSIBLE_CYCLES` is an (intrusive) list which contains the possible roots of cyclic garbage.  
 Sometimes (see [`crate::trigger_collection`](./src/lib.rs)), when creating a new `Cc` or when `collect_cycles` is called,
 the objects inside the `POSSIBLE_CYCLES` list are checked to see if they are part of a garbage cycle.
 
 Therefore, they undergo two tracing passes:
 - **Trace Counting:** during this phase, starting from the elements inside `POSSIBLE_CYCLES`,
-  objects are traced to count the amount of pointers to each `CcOnHeap` that are reachable from the list's `Cc`s.  
+  objects are traced to count the amount of pointers to each `CcBox` that is reachable from the list's `Cc`s.  
   The `tracing_counter` "field" (see the [`counter_marker` module](./src/counter_marker.rs) for more info) is used to keep track of this number.
   <details>
   <summary>About tracing_counter</summary>
@@ -33,20 +34,32 @@ Therefore, they undergo two tracing passes:
      The invariant regarding this second counter is that it must always be between 0 and RC inclusively. 
   </p>
   </details>
-- **Trace Roots:** now, every `CcOnHeap` which has the RC strictly greater than `tracing_counter` can be considered a root,
+- **Trace Roots:** now, every `CcBox` which has the RC strictly greater than `tracing_counter` can be considered a root,
   since it must exist a `Cc` pointer which points at it that hasn't been traced before. Thus, a trace is started from these roots,
   and all objects not reached during this trace are finalized/deallocated (the story is more complicated because of possible
-  object resurrections, see comments at the end of the [`collect` function](./src/lib.rs)).  
+  object resurrections, see the comments in [lib.rs](./src/lib.rs)).  
   Note that this second phase is correct only if the graph formed by the pointers is not changed between the two phases. Thus,
   this is a key requirement of the `Trace` trait and one of the reasons it is marked `unsafe`.
 
-### Future improvements
+# Writing documentation
 
-If you're interested in the project, there are some additions which would be nice to have:
-- weak pointers
-- cleaners (https://docs.oracle.com/javase/9/docs/api/java/lang/ref/Cleaner.html)
-- weak pointers and cleaners as optional features to explicitly enable
-- `Cc::new_cyclic` as optional feature (enabled by default) maybe?
+Docs are always built with every feature enabled. This makes it easier to write and maintain the documentation.
 
-**Already done:**
-- finalization as optional feature
+However, this also makes it more difficult to write examples, as those must pass CI even when some of the features they 
+require are disabled. As such, examples are marked as `ignore`d if a feature they need is missing:
+```rust
+#![cfg_attr(
+    feature = "derive",
+    doc = r"```rust"
+)]
+#![cfg_attr(
+    not(feature = "derive"),
+    doc = r"```rust,ignore"
+)]
+#![doc = r"# use rust_cc::*;
+# use rust_cc_derive::*;
+
+// Example code
+
+```"]
+```

Cargo.toml

@@ -6,38 +6,64 @@ authors.workspace = true
 readme = "README.md"
 repository.workspace = true
 categories.workspace = true
-keywords = ["cycle", "cycles", "collector", "garbage", "memory"]
+keywords = ["cycle-collector", "garbage-collector", "gc", "reference-counting", "memory"]
 license.workspace = true
 edition.workspace = true
 
 [workspace]
 members = ["derive"]
 
 [workspace.package]
-version = "0.2.0"
+version = "0.3.0" # Also update in [dependencies.rust-cc-derive.version]
 authors = ["fren_gor <[email protected]>"]
 repository = "https://github.com/frengor/rust-cc"
-categories = ["memory-management"]
+categories = ["memory-management", "no-std"]
 license = "MIT OR Apache-2.0"
 edition = "2021"
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
 [features]
-default = ["auto-collect", "finalization"]
-full = ["auto-collect", "finalization"] # Every feature except for "nightly" and "pedantic-debug-assertions"
+default = ["auto-collect", "finalization", "derive", "std"]
+
+# Enables support for nightly-only features
 nightly = []
+
+# Enables the derive macros for the Trace and Finalize traits
+derive = ["dep:rust-cc-derive"]
+
+# Enables automatic executions of the collection algorithm
 auto-collect = []
+
+# Enables finalization
 finalization = []
+
+# Enables weak pointers
+weak-ptr = []
+
+# Enables cleaners
+cleaners = ["dep:slotmap", "weak-ptr"]
+
+# Enables support for stdlib, disable for no-std support (requires ELF TLS and nightly)
+std = ["slotmap?/std", "thiserror/std"]
+
+# (Internal use only) Enables more debug assertions useful for debugging
 pedantic-debug-assertions = []
 
 [dependencies]
-thiserror = "1.0.37"
+rust-cc-derive = { path = "./derive", version = "=0.3.0", optional = true }
+slotmap = {  version = "1.0", optional = true }
+thiserror = { version = "1.0", package = "thiserror-core", default-features = false }
 
 [dev-dependencies]
-iai = "0.1.1"
+iai-callgrind = "=0.7.3" # Also update IAI_CALLGRIND_VERSION in .github/workflows/bench.yml
 rand = "0.8.3"
+trybuild = "1.0.85"
+test-case = "3.3.1"
 
 [[bench]]
 name = "bench"
 harness = false
+required-features = ["std", "derive"]
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "doc_auto_cfg", "--generate-link-to-definition"]