chore(maitake): change name to maitake, add docs (#180)

* chore(async): rename to `maitake` * chore: update CI config * docs(maitake): add README, etc Signed-off-by: Eliza Weisman <[email protected]> Co-authored-by: James Munns <[email protected]>
hawkw · May 31, 2022 · 7bb3180 · 7bb3180
1 parent afd1ce2
commit 7bb3180
Show file tree

Hide file tree

Showing 16 changed files with 106 additions and 29 deletions.
diff --git a/.github/workflows/async.yml → .github/workflows/maitake.yml b/.github/workflows/async.yml → .github/workflows/maitake.yml
@@ -1,20 +1,19 @@
 # CI workflow for running `loom` tests
 #
 # This is factored out from the main workflow so that it can be triggered only
-# by changes to `mycelium-util`, `mycelium-async`, and `cordyceps`, which are
+# by changes to `mycelium-util`, `maitake`, and `cordyceps`, which are
 # the only crates that currently contain loom tests.
 #
 # Note that if other crates add loom tests in the future, they will need to be
 # added to this workflow!
-name: mycelium-async
+name: maitake
 
 on:
   pull_request:
   workflow_dispatch:
   push:
     branches: ["main"]
 
-
 env:
   # disable incremental compilation.
   #
@@ -47,7 +46,7 @@ jobs:
       - id: skip_check
         uses: fkirc/skip-duplicate-actions@master
         with:
-          paths: '["async/**.rs", "async/Cargo.toml", ".github/workflows/async.yml"]'
+          paths: '["maitake/**.rs", "maitake/Cargo.toml", ".github/workflows/maitake.yml"]'
           do_not_skip: '["workflow_dispatch"]'
 
 
@@ -56,13 +55,13 @@ jobs:
     needs: is_enabled
     if: ${{ needs.is_enabled.outputs.should_skip != 'true' }}
     runs-on: ubuntu-latest
-    name: Loom tests (mycelium-async)
+    name: Loom tests (maitake)
     steps:
     - name: install rust toolchain
       run: rustup show
     - uses: actions/checkout@v2
     - name: run loom tests
-      run: cargo test --profile loom --lib -p mycelium-async
+      run: cargo test --profile loom --lib -p maitake
       env:
         LOOM_MAX_PREEMPTIONS: 2
         LOOM_LOG: loom=trace

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,13 +1,13 @@
 [workspace]
 members = [
     "alloc",
-    "async",
     "bitfield",
     "cordyceps",
     "util",
     "hal-core",
     "hal-x86_64",
     "inoculate",
+    "maitake",
     "mycotest",
     "trace",
 ]
@@ -35,7 +35,7 @@ opt-level = 3
 [dependencies]
 hal-core = { path = "hal-core", features = ["embedded-graphics-core"] }
 mycelium-alloc = { path = "alloc", features = ["buddy", "bump"] }
-mycelium-async = { path = "async" }
+maitake = { path = "maitake" }
 mycelium-util = { path = "util" }
 mycelium-trace = { path = "trace", features = ["embedded-graphics"] }
 rlibc = "1.0"

diff --git a/async/Cargo.toml → maitake/Cargo.toml b/async/Cargo.toml → maitake/Cargo.toml
@@ -1,11 +1,20 @@
 [package]
-name = "mycelium-async"
+name = "maitake"
 version = "0.1.0"
-edition = "2021"
 authors = [
     "Eliza Weisman <[email protected]>",
+    "James Munns <[email protected]>"
 ]
+description = "Async runtime construction kit"
+repository = "https://github.com/hawkw/mycelium"
 license = "MIT"
+readme = "./README.md"
+categories = [
+    "no-std",
+    "async",
+]
+edition = "2021"
+rust-version = "1.61.0"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
@@ -27,4 +36,8 @@ futures-util = "0.3"
 [target.'cfg(loom)'.dev-dependencies]
 loom = { version = "0.5.5", features = ["futures"] }
 tracing_01 = { package = "tracing", version = "0.1", default_features = false }
-tracing_subscriber_03 = { package = "tracing-subscriber", version = "0.3.11", features = ["fmt"] }
+tracing_subscriber_03 = { package = "tracing-subscriber", version = "0.3.11", features = ["fmt"] }
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
diff --git a/async/LICENSE → maitake/LICENSE b/async/LICENSE → maitake/LICENSE
diff --git a/maitake/README.md b/maitake/README.md
@@ -0,0 +1,63 @@
+# maitake
+
+["Dancing mushroom"][maitake-wiki] &mdash; an async runtime construction kit.
+
+[![crates.io][crates-badge]][crates-url]
+[![Documentation][docs-badge]][docs-url]
+[![Documentation (HEAD)][docs-main-badge]][docs-main-url]
+[![MIT licensed][mit-badge]][mit-url]
+[![Test Status][tests-badge]][tests-url]
+[![Loom Models][loom-badge]][loom-url]
+[![Sponsor @hawkw on GitHub Sponsors][sponsor-badge]][sponsor-url]
+
+[crates-badge]: https://img.shields.io/crates/v/maitake.svg
+[crates-url]: https://crates.io/crates/maitake
+[docs-badge]: https://docs.rs/maitake/badge.svg
+[docs-url]: https://docs.rs/maitake
+[docs-main-badge]: https://img.shields.io/netlify/3ec00bb5-251a-4f83-ac7f-3799d95db0e6?label=docs%20%28main%20branch%29
+[docs-main-url]: https://mycelium.elizas.website/maitake
+[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
+[mit-url]: ../LICENSE
+[tests-badge]: https://github.com/hawkw/mycelium/actions/workflows/ci.yml/badge.svg?branch=main
+[tests-url]: https://github.com/hawkw/mycelium/actions/workflows/ci.yml
+[loom-badge]: https://github.com/hawkw/mycelium/actions/workflows/maitake.yml/badge.svg?branch=main
+[loom-url]: https://github.com/hawkw/mycelium/actions/workflows/maitake.yml
+[sponsor-badge]: https://img.shields.io/badge/sponsor-%F0%9F%A4%8D-ff69b4
+[sponsor-url]: https://github.com/sponsors/hawkw
+[maitake-wiki]: https://en.wikipedia.org/wiki/Grifola_frondosa
+
+## what is it?
+
+This library is a collection of modular components for building a Rust
+async runtime based on [`core::task`] and [`core::future`], with a focus on
+supporting `#![no_std]` projects.
+
+Unlike other async runtime implementations, `maitake` does *not* provide a
+complete, fully-functional runtime implementation. Instead, it provides reusable
+implementations of common functionality, including a [task system],
+[scheduling], and [notification primitives][wait]. These components may be
+combined with other runtime services, such as timers and I/O resources, to
+produce a complete, application-specific async runtime.
+
+`maitake` was initially designed for use in the [mycelium] and [mnemOS]
+operating systems, but may be useful for other projects as well.
+
+[`core::task`]: https://doc.rust-lang.org/stable/core/task/index.html
+[`core::future`]: https://doc.rust-lang.org/stable/core/future/index.html
+[task system]: task
+[scheduling]: scheduler
+[wait]: wait
+[mycelium]: https://github.com/hawkw/mycelium
+[mnemOS]: https://mnemos.jamesmunns.com
+
+## features
+
+The following features are available (this list is incomplete; you can help by [expanding it].)
+
+[expanding it]: https://github.com/hawkw/mycelium/edit/main/maitake/README.md
+
+| Feature | Default | Explanation |
+| :---    | :---    | :---        |
+| `alloc` | `true`  | Enables [`liballoc`] dependency |
+
+[`liballoc`]: https://doc.rust-lang.org/alloc/
diff --git a/async/src/lib.rs → maitake/src/lib.rs b/async/src/lib.rs → maitake/src/lib.rs
@@ -1,3 +1,5 @@
+#![cfg_attr(docsrs, doc = include_str!("../README.md"))]
+#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg, doc_cfg_hide))]
 #![cfg_attr(not(test), no_std)]
 extern crate alloc;
 

diff --git a/async/src/loom.rs → maitake/src/loom.rs b/async/src/loom.rs → maitake/src/loom.rs
diff --git a/async/src/scheduler.rs → maitake/src/scheduler.rs b/async/src/scheduler.rs → maitake/src/scheduler.rs
diff --git a/async/src/task.rs → maitake/src/task.rs b/async/src/task.rs → maitake/src/task.rs
diff --git a/async/src/task/state.rs → maitake/src/task/state.rs b/async/src/task/state.rs → maitake/src/task/state.rs
diff --git a/async/src/task/task_list.rs → maitake/src/task/task_list.rs b/async/src/task/task_list.rs → maitake/src/task/task_list.rs
diff --git a/async/src/util.rs → maitake/src/util.rs b/async/src/util.rs → maitake/src/util.rs
diff --git a/async/src/wait.rs → maitake/src/wait.rs b/async/src/wait.rs → maitake/src/wait.rs
diff --git a/async/src/wait/cell.rs → maitake/src/wait/cell.rs b/async/src/wait/cell.rs → maitake/src/wait/cell.rs
diff --git a/src/tests.rs b/src/tests.rs
@@ -46,7 +46,7 @@ mod myco_async {
         sync::atomic::{AtomicBool, AtomicUsize, Ordering},
         task::{Context, Poll},
     };
-    use mycelium_async::scheduler::StaticScheduler;
+    use maitake::scheduler::StaticScheduler;
     use mycelium_util::sync::Lazy;
 
     struct Yield {