Compare commits

...
6 Commits
Author SHA1 Message Date
semantic-release-bot 68a0ec9613 chore(release): 1.21.0 [skip ci]
# [1.21.0](https://github.com/asepharyana/mytheclipse/compare/v1.20.0...v1.21.0) (2026-08-29)

### Features

* CPU parallel compute primitives — compute_map, compute_join, compute_par_for_each ([e148944](https://github.com/asepharyana/mytheclipse/commit/e14894479d8ca716a9decf2c1403359fdc376717))
2026-08-29 17:00:18 +00:00
asepharyana e14894479d feat: CPU parallel compute primitives — compute_map, compute_join, compute_par_for_each 2026-08-29 23:59:23 +07:00
semantic-release-bot f86abc4ce1 chore(release): 1.20.0 [skip ci]
# [1.20.0](https://github.com/asepharyana/mytheclipse/compare/v1.19.0...v1.20.0) (2026-08-29)

### Features

* ParallelConcurrency — auto-size concurrency from CPU cores ([d00881c](https://github.com/asepharyana/mytheclipse/commit/d00881c2b96fa29ee0eaa5f43a7c7af90983e802))
2026-08-29 16:41:52 +00:00
asepharyana d00881c2b9 feat: ParallelConcurrency — auto-size concurrency from CPU cores
CI / Rustfmt (push) Canceled after 0s
CI / Clippy (push) Canceled after 0s
CI / Test (workspace all features) (push) Canceled after 0s
CI / Test (workspace default features) (push) Canceled after 0s
CI / Test (mytheclipse / bg only) (push) Canceled after 0s
CI / Test (mytheclipse / compute only) (push) Canceled after 0s
CI / Test (mytheclipse / io only) (push) Canceled after 0s
CI / Test (mytheclipse / lifecycle only) (push) Canceled after 0s
CI / Test (mytheclipse / observability only) (push) Canceled after 0s
CI / Test (mytheclipse / resiliency only) (push) Canceled after 0s
CI / Test (mytheclipse / traffic only) (push) Canceled after 0s
CI / Test (mytheclipse-cache / l2-redis) (push) Canceled after 0s
CI / Test (mytheclipse-cache / l1-moka) (push) Canceled after 0s
CI / Test (mytheclipse-cache / default) (push) Canceled after 0s
CI / Test (mytheclipse-config / default) (push) Canceled after 0s
CI / Test (mytheclipse-crypto / default) (push) Canceled after 0s
CI / Test (mytheclipse-event / amqp) (push) Canceled after 0s
CI / Test (mytheclipse-event / nats) (push) Canceled after 0s
CI / Test (mytheclipse-event / default (mem)) (push) Canceled after 0s
CI / Test (mytheclipse-storage / gcs) (push) Canceled after 0s
CI / Test (mytheclipse-storage / s3) (push) Canceled after 0s
CI / Test (mytheclipse-storage / default (local)) (push) Canceled after 0s
CI / Run mytheclipse example (push) Canceled after 0s
CI / Docs check (push) Canceled after 0s
CI / Cargo package dry-run (mytheclipse) (push) Canceled after 0s
CI / Cargo package dry-run (mytheclipse-cache) (push) Canceled after 0s
CI / Cargo package dry-run (mytheclipse-config) (push) Canceled after 0s
CI / Cargo package dry-run (mytheclipse-crypto) (push) Canceled after 0s
CI / Cargo package dry-run (mytheclipse-event) (push) Canceled after 0s
CI / Cargo package dry-run (mytheclipse-storage) (push) Canceled after 0s
Release / Semantic Release (push) Canceled after 0s
2026-08-29 23:40:54 +07:00
semantic-release-bot 829c5714d2 chore(release): 1.19.0 [skip ci]
# [1.19.0](https://github.com/asepharyana/mytheclipse/compare/v1.18.0...v1.19.0) (2026-08-29)

### Features

* criterion benchmarks proving primitive overhead is negligible ([5df04d7](https://github.com/asepharyana/mytheclipse/commit/5df04d75126d71d0790028c4a215acb571f25616))
2026-08-29 15:15:05 +00:00
asepharyana 5df04d7512 feat: criterion benchmarks proving primitive overhead is negligible 2026-08-29 22:14:01 +07:00
20 changed files with 889 additions and 34 deletions

No files matched your search

+34
View File
@@ -0,0 +1,34 @@
# Implementation Spec: Round 19 — Criterion Benchmarks
## Goal
Buktikan klaim "secepat mungkin" (tujuan awal project) dengan benchmark
nyata. Ukur overhead primitives race-safe vs baseline naif, supaya user
tahu trade-off dan bisa memilih fitur dengan data.
## New files
### crates/mytheclipse/benches/primitives.rs
Criterion bench untuk primitives core (feature `full`):
- `parallel_map`: throughput 1000 item, concurrency 8 vs sequential loop
(pakai `black_box`)
- `retry_ext`: overhead `.retry()` success-first vs 2 retries
- `rate_limiter`: `RateLimiter::try_acquire` throughput (atomic CAS)
- `semaphore_pool`: acquire/release cycle throughput — bukti no-leak + low
overhead
- `aggregate_error`: `from_results` 1000 results all-ok vs 50% err
- `shutdown_guard`: new + drop cost
## Dependency
- dev-deps: `criterion = "0.5"` + `[[bench]]` harness = false
- `harness = false` di Cargo.toml bench section (criterion punya main sendiri)
## Verification
1. `cargo bench -p mytheclipse --bench primitives --all-features` — runs,
reports times
2. `cargo build --workspace --all-features` — exit 0
3. `cargo clippy --workspace --all-features` — 0 new warnings
4. Spec + commit + push
## Notes
- Criterion 0.5 mendukung MSRV 1.60 — aman untuk rust-version 1.75.
- Bench tidak jalan di CI (hanya manual) — tidak mempengaruhi pipeline.
+35
View File
@@ -0,0 +1,35 @@
# Implementation Spec: Round 20 — Auto Concurrency
## Goal
`parallel_map` / `parallel_map_unordered` / `parallel_for_each` terima
`usize` (eksplisit, existing) ATAU `()` (auto dari host CPU cores). Tidak
perlu nama API baru — trait `ParallelConcurrency` resolve di call-site.
## Design
- Trait `ParallelConcurrency`: `fn resolve(self) -> usize`
- impl `usize` → `self.max(1)` (behavior lama, backward compatible)
- impl `()` → `std::thread::available_parallelism()` fallback 1
- 3 fungsi berubah: `concurrency: usize` → `concurrency: C where C: ParallelConcurrency`
- `let n = concurrency.resolve();`
- Body tidak berubah (pakai `n`)
- Export trait di lib.rs
## Backward compat
Caller existing `parallel_map(items, 4, f)` tetap compile — `4` resolve ke
`usize` (satu-satunya impl integer). Literal inference OK karena trait bound
memaksa `usize`.
## Files
- crates/mytheclipse/src/parallel_map.rs (trait + 3 signature)
- crates/mytheclipse/src/lib.rs (export ParallelConcurrency)
- crates/mytheclipse/examples/scaling_demo.rs (demo auto run)
- doctests: tambah contoh auto `()` di parallel_map & parallel_for_each
- tests: `auto_concurrency_uses_cpu_cores` (peak ≤ cores), hasil benar
## Verification
1. `cargo test -p mytheclipse parallel --all-features` — 0 FAILED
2. `cargo test -p mytheclipse --test race_stress --all-features` — 0 FAILED
3. `cargo build --workspace --all-features` — exit 0
4. `cargo clippy --workspace --all-features` — 0 new
5. `cargo run --example scaling_demo` — auto run peak == cores
6. spec + commit + push
+48
View File
@@ -0,0 +1,48 @@
# Implementation Spec: Round 21 — CPU Parallel Compute Primitives
## Goal
Fitur parallel khusus CPU (rayon) yang bounded, panic-isolated, error-aggregated.
Melengkapi `compute()` (single call) dengan batch parallel + fork-join.
## New API (crates/mytheclipse/src/compute.rs, feature `compute`)
### 1. `compute_map<I, T, F>(items, f) -> Result<Vec<T>, ComputeErrors>`
- `pack_items` di rayon compute pool: `par_iter().map(f)` — bounded concurrency
otomatis (rayon work-stealing sizing = CPU cores), ordered output.
- `f: Fn(I::Item) -> Result<T, ComputeMapItemError>`:
- item error string → dikumpulkan
- panic per item di-catch (catch_unwind) → jadi error, pool survive
- `ComputeErrors { errors: Vec<String> }` — Display, Error, len, is_empty.
(Tidak pakai AggregateError — feature `compute` harus compile tanpa resiliency.)
- `I: IntoParallelIterator` (rayon) — work langsung di pool, tanpa materialize.
### 2. `compute_join<A, B, RA, RB>(a, b) -> Result<(RA, RB), MytheclipseError>`
- `rayon::join` wrapper di compute pool: 2 heavy closures run parallel.
- Panic-isolated (catch_unwind per branch) — pool survive, error jadi
ComputePanic.
### 3. `compute_par_for_each<I>(items, f) -> Result<(), ComputeErrors>`
- `par_iter().for_each` idiom — fire side-effects parallel di pool.
- Panic isolation per item.
## Design notes
- Reuse `context().compute_pool` (existing sizing: compute_threads dari
RuntimeConfig / available_parallelism) — konsisten dengan `compute()`.
- `rayon::ThreadPool::install` untuk semua — force run di pool.
- Panic isolation: `std::panic::catch_unwind` + AssertUnwindSafe per item
(sama seperti `compute()` yang sudah proven).
- Bounded = rayon work-stealing — concurrency = pool threads (CPU cores),
bukan item count. Tidak perlu semaphore.
## Files
- crates/mytheclipse/src/compute.rs (3 fungsi + error type)
- crates/mytheclipse/src/lib.rs (export)
- doctests: compute_map, compute_join, compute_par_for_each
- tests: unit di compute.rs
## Verification
1. `cargo build --workspace --all-features` — exit 0
2. `cargo test -p mytheclipse compute --all-features` — 0 FAILED
3. `cargo test -p mytheclipse --doc --all-features` — 0 FAILED
4. `cargo clippy --workspace --all-features` — 0 new
5. spec + commit + push
+21
View File
@@ -1,3 +1,24 @@
# [1.21.0](https://github.com/asepharyana/mytheclipse/compare/v1.20.0...v1.21.0) (2026-08-29)
### Features
* CPU parallel compute primitives — compute_map, compute_join, compute_par_for_each ([e148944](https://github.com/asepharyana/mytheclipse/commit/e14894479d8ca716a9decf2c1403359fdc376717))
# [1.20.0](https://github.com/asepharyana/mytheclipse/compare/v1.19.0...v1.20.0) (2026-08-29)
### Features
* ParallelConcurrency — auto-size concurrency from CPU cores ([d00881c](https://github.com/asepharyana/mytheclipse/commit/d00881c2b96fa29ee0eaa5f43a7c7af90983e802))
# [1.19.0](https://github.com/asepharyana/mytheclipse/compare/v1.18.0...v1.19.0) (2026-08-29)
### Features
* criterion benchmarks proving primitive overhead is negligible ([5df04d7](https://github.com/asepharyana/mytheclipse/commit/5df04d75126d71d0790028c4a215acb571f25616))
# [1.18.0](https://github.com/asepharyana/mytheclipse/compare/v1.17.0...v1.18.0) (2026-08-29)
Generated
+170 -11
View File
@@ -100,6 +100,12 @@ dependencies = [
"url",
]
[[package]]
name = "anes"
version = "0.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4b46cbb362ab8752921c97e041f5e366ee6297bd428a31275b9fcf1e380f7299"
[[package]]
name = "anstream"
version = "1.0.0"
@@ -1086,6 +1092,12 @@ dependencies = [
"either",
]
[[package]]
name = "cast"
version = "0.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5"
[[package]]
name = "cbc"
version = "0.1.2"
@@ -1130,6 +1142,33 @@ dependencies = [
"rand_core 0.10.1",
]
[[package]]
name = "ciborium"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "42e69ffd6f0917f5c029256a24d0161db17cea3997d185db0d35926308770f0e"
dependencies = [
"ciborium-io",
"ciborium-ll",
"serde",
]
[[package]]
name = "ciborium-io"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "05afea1e0a06c9be33d539b876f1ce3692f4afea2cb41f740e7743225ed1c757"
[[package]]
name = "ciborium-ll"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "57663b653d948a338bfb3eeba9bb2fd5fcfaecb9e199e87e1eda4d9e8b240fd9"
dependencies = [
"ciborium-io",
"half",
]
[[package]]
name = "cipher"
version = "0.4.4"
@@ -1317,6 +1356,44 @@ dependencies = [
"cfg-if",
]
[[package]]
name = "criterion"
version = "0.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f2b12d017a929603d80db1831cd3a24082f8137ce19c69e6447f54f5fc8d692f"
dependencies = [
"anes",
"cast",
"ciborium",
"clap",
"criterion-plot",
"futures",
"is-terminal",
"itertools 0.10.5",
"num-traits",
"once_cell",
"oorandom",
"plotters",
"rayon",
"regex",
"serde",
"serde_derive",
"serde_json",
"tinytemplate",
"tokio",
"walkdir",
]
[[package]]
name = "criterion-plot"
version = "0.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6b50826342786a51a89e2da3a28f1c32b06e387201bc2d19791f622c673706b1"
dependencies = [
"cast",
"itertools 0.10.5",
]
[[package]]
name = "crossbeam-channel"
version = "0.5.16"
@@ -1351,6 +1428,12 @@ version = "0.8.22"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "61803da095bee82a81bb1a452ecc25d3b2f1416d1897eb86430c6159ef717c17"
[[package]]
name = "crunchy"
version = "0.2.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
[[package]]
name = "crypto-bigint"
version = "0.5.5"
@@ -2116,6 +2199,17 @@ dependencies = [
"tracing",
]
[[package]]
name = "half"
version = "2.7.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b"
dependencies = [
"cfg-if",
"crunchy",
"zerocopy",
]
[[package]]
name = "hashbrown"
version = "0.15.5"
@@ -2561,12 +2655,32 @@ version = "2.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6a756c3fac73139e83f14c2d742155dd2b78d3ee56597b419a0579b7bdd6dd78"
[[package]]
name = "is-terminal"
version = "0.4.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
dependencies = [
"hermit-abi 0.5.2",
"libc",
"windows-sys 0.61.2",
]
[[package]]
name = "is_terminal_polyfill"
version = "1.70.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
[[package]]
name = "itertools"
version = "0.10.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b0fd2260e829bddf4cb6ea802289de2f86d6a7a690192fbe91b3f46e0f2c8473"
dependencies = [
"either",
]
[[package]]
name = "itertools"
version = "0.13.0"
@@ -2827,9 +2941,10 @@ dependencies = [
[[package]]
name = "mytheclipse"
version = "1.18.0"
version = "1.21.0"
dependencies = [
"async-trait",
"criterion",
"num_cpus",
"rand 0.8.8",
"rayon",
@@ -2841,7 +2956,7 @@ dependencies = [
[[package]]
name = "mytheclipse-cache"
version = "1.18.0"
version = "1.21.0"
dependencies = [
"async-trait",
"moka",
@@ -2854,7 +2969,7 @@ dependencies = [
[[package]]
name = "mytheclipse-cli"
version = "1.18.0"
version = "1.21.0"
dependencies = [
"clap",
"tokio",
@@ -2863,7 +2978,7 @@ dependencies = [
[[package]]
name = "mytheclipse-config"
version = "1.18.0"
version = "1.21.0"
dependencies = [
"dotenvy",
"notify",
@@ -2878,7 +2993,7 @@ dependencies = [
[[package]]
name = "mytheclipse-crypto"
version = "1.18.0"
version = "1.21.0"
dependencies = [
"aead",
"aes-gcm",
@@ -2900,7 +3015,7 @@ dependencies = [
[[package]]
name = "mytheclipse-event"
version = "1.18.0"
version = "1.21.0"
dependencies = [
"async-nats",
"async-trait",
@@ -2916,7 +3031,7 @@ dependencies = [
[[package]]
name = "mytheclipse-http"
version = "1.18.0"
version = "1.21.0"
dependencies = [
"async-trait",
"axum",
@@ -2932,7 +3047,7 @@ dependencies = [
[[package]]
name = "mytheclipse-queue"
version = "1.18.0"
version = "1.21.0"
dependencies = [
"async-nats",
"async-trait",
@@ -2948,7 +3063,7 @@ dependencies = [
[[package]]
name = "mytheclipse-storage"
version = "1.18.0"
version = "1.21.0"
dependencies = [
"async-trait",
"aws-config",
@@ -2964,7 +3079,7 @@ dependencies = [
[[package]]
name = "mytheclipse-tracing"
version = "1.18.0"
version = "1.21.0"
dependencies = [
"opentelemetry 0.25.0",
"tokio",
@@ -3136,6 +3251,12 @@ version = "1.70.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
[[package]]
name = "oorandom"
version = "11.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"
[[package]]
name = "opaque-debug"
version = "0.3.1"
@@ -3494,6 +3615,34 @@ version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548"
[[package]]
name = "plotters"
version = "0.3.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5aeb6f403d7a4911efb1e33402027fc44f29b5bf6def3effcc22d7bb75f2b747"
dependencies = [
"num-traits",
"plotters-backend",
"plotters-svg",
"wasm-bindgen",
"web-sys",
]
[[package]]
name = "plotters-backend"
version = "0.3.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "df42e13c12958a16b3f7f4386b9ab1f3e7933914ecea48da7139435263a4172a"
[[package]]
name = "plotters-svg"
version = "0.3.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "51bae2ac328883f7acdfea3d66a7c35751187f870bc81f94563733a154d7a670"
dependencies = [
"plotters-backend",
]
[[package]]
name = "polling"
version = "2.8.0"
@@ -3826,7 +3975,7 @@ dependencies = [
"bytes",
"combine",
"futures-util",
"itertools",
"itertools 0.13.0",
"itoa",
"num-bigint",
"percent-encoding",
@@ -4732,6 +4881,16 @@ dependencies = [
"zerovec",
]
[[package]]
name = "tinytemplate"
version = "1.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "be4d6b5f19ff7664e8c98d03e2139cb510db9b0a60b55f8e8709b689d939b6bc"
dependencies = [
"serde",
"serde_json",
]
[[package]]
name = "tinyvec"
version = "1.12.0"
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "mytheclipse-cache"
version = "1.18.0"
version = "1.21.0"
edition = "2021"
rust-version = "1.75"
license = "MIT OR Apache-2.0"
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "mytheclipse-cli"
version = "1.18.0"
version = "1.21.0"
edition = "2021"
rust-version = "1.75"
license = "MIT OR Apache-2.0"
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "mytheclipse-config"
version = "1.18.0"
version = "1.21.0"
edition = "2021"
rust-version = "1.75"
license = "MIT OR Apache-2.0"
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "mytheclipse-crypto"
version = "1.18.0"
version = "1.21.0"
edition = "2021"
rust-version = "1.75"
license = "MIT OR Apache-2.0"
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "mytheclipse-event"
version = "1.18.0"
version = "1.21.0"
edition = "2021"
rust-version = "1.75"
license = "MIT OR Apache-2.0"
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "mytheclipse-http"
version = "1.18.0"
version = "1.21.0"
edition = "2021"
rust-version = "1.75"
license = "MIT OR Apache-2.0"
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "mytheclipse-queue"
version = "1.18.0"
version = "1.21.0"
edition = "2021"
rust-version = "1.75"
license = "MIT OR Apache-2.0"
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "mytheclipse-storage"
version = "1.18.0"
version = "1.21.0"
edition = "2021"
rust-version = "1.75"
license = "MIT OR Apache-2.0"
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "mytheclipse-tracing"
version = "1.18.0"
version = "1.21.0"
edition = "2021"
rust-version = "1.75"
license = "MIT OR Apache-2.0"
+13 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "mytheclipse"
version = "1.18.0"
version = "1.21.0"
edition = "2021"
rust-version = "1.75"
license = "MIT OR Apache-2.0"
@@ -25,6 +25,7 @@ thiserror = "2"
[dev-dependencies]
tokio = { version = "1.53", features = ["full"] }
tracing-subscriber = "0.3"
criterion = { version = "0.5", features = ["async_tokio"] }
[features]
default = []
@@ -42,6 +43,17 @@ name = "main"
path = "examples/main.rs"
required-features = ["full"]
[[example]]
name = "scaling_demo"
path = "examples/scaling_demo.rs"
required-features = ["full"]
[[bench]]
name = "primitives"
path = "benches/primitives.rs"
harness = false
required-features = ["full"]
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
+180
View File
@@ -0,0 +1,180 @@
//! Criterion benchmarks for the high-level primitives.
//!
//! Run: `cargo bench -p mytheclipse --bench primitives --all-features`
//!
//! These measure the *overhead* of the race-safe abstractions — the cost you
//! pay for auto thread/core allocation, bounded fan-out, and exactly-once
//! cleanup. Numbers (per-op) should be tiny; anything in the µs+ range for a
//! single primitive would signal a regression.
use std::sync::atomic::{AtomicU32, Ordering};
use std::sync::Arc;
use std::time::Duration;
use criterion::{black_box, criterion_group, criterion_main, Bencher, Criterion};
use tokio::runtime::Runtime;
use mytheclipse::aggregate_error::AggregateError;
use mytheclipse::parallel_map::{parallel_for_each, parallel_map};
use mytheclipse::pool::{Pool, SemaphorePool};
use mytheclipse::ratelimit::RateLimiter;
use mytheclipse::retry_ext::RetryExt;
use mytheclipse::retry::RetryConfig;
use mytheclipse::shutdown_guard::ShutdownGuard;
fn rt() -> Runtime {
Runtime::new().expect("tokio runtime")
}
fn bench_parallel_map(c: &mut Criterion) {
let rt = rt();
c.bench_function("parallel_map/1000x8", |b| {
b.to_async(&rt).iter(|| async {
let items: Vec<u32> = (0..1000).collect();
let out = parallel_map(items, 8, |x| async move { Ok::<_, std::io::Error>(x * 2) })
.await
.unwrap();
black_box(out);
});
});
// Sequential baseline for comparison.
c.bench_function("sequential/map_1000", |b| {
b.iter(|| {
let items: Vec<u32> = (0..1000).collect();
let out: Vec<u32> = items.into_iter().map(|x| x * 2).collect();
black_box(out);
});
});
}
fn bench_parallel_for_each(c: &mut Criterion) {
let rt = rt();
c.bench_function("parallel_for_each/1000x8", |b| {
b.to_async(&rt).iter(|| async {
parallel_for_each(0u32..1000, 8, |_| async move { Ok::<_, std::io::Error>(()) })
.await
.unwrap();
black_box(());
});
});
}
fn bench_retry_ext(c: &mut Criterion) {
let rt = rt();
c.bench_function("retry_ext/success_first", |b| {
b.to_async(&rt).iter(|| async {
let op = || async { Ok::<u32, std::io::Error>(42) };
let out = async { Ok::<u32, std::io::Error>(42) }
.retry(
RetryConfig {
max_attempts: 3,
base_delay: Duration::from_millis(1),
..RetryConfig::default()
},
|_: &std::io::Error| true,
op,
)
.await
.unwrap();
black_box(out);
});
});
c.bench_function("retry_ext/retries_twice", |b| {
b.to_async(&rt).iter(|| async {
let attempts = Arc::new(AtomicU32::new(0));
let a = Arc::clone(&attempts);
let op = move || {
let a = Arc::clone(&a);
async move {
if a.fetch_add(1, Ordering::SeqCst) < 2 {
Err::<u32, std::io::Error>(std::io::Error::other("x"))
} else {
Ok(42)
}
}
};
let out = async { Err::<u32, std::io::Error>(std::io::Error::other("first")) }
.retry(
RetryConfig {
max_attempts: 3,
base_delay: Duration::from_millis(1),
..RetryConfig::default()
},
|_: &std::io::Error| true,
op,
)
.await
.unwrap();
black_box(out);
});
});
}
fn bench_rate_limiter(c: &mut Criterion) {
c.bench_function("rate_limiter/try_acquire", |b| {
let rl = RateLimiter::new(1_000_000.0, 10_000_000);
b.iter(|| {
let _ = black_box(rl.try_acquire());
});
});
}
fn bench_semaphore_pool(c: &mut Criterion) {
let rt = rt();
c.bench_function("semaphore_pool/acquire_release", |b| {
b.to_async(&rt).iter(|| async {
let pool = SemaphorePool::new(vec![1u32, 2, 3, 4, 5]);
let item = pool.acquire().await.unwrap();
black_box(item.resource);
});
});
}
fn bench_aggregate_error(c: &mut Criterion) {
c.bench_function("aggregate_error/all_ok_1000", |b| {
b.iter(|| {
let results: Vec<Result<u32, std::io::Error>> = (0..1000).map(Ok).collect();
let out = AggregateError::from_results(black_box(results)).unwrap();
black_box(out);
});
});
c.bench_function("aggregate_error/500err_1000", |b| {
b.iter(|| {
let results: Vec<Result<u32, std::io::Error>> = (0..1000)
.map(|i| {
if i % 2 == 0 {
Err(std::io::Error::other("x"))
} else {
Ok(i)
}
})
.collect();
let out = AggregateError::from_results(black_box(results));
black_box(out);
});
});
}
fn bench_shutdown_guard(c: &mut Criterion) {
c.bench_function("shutdown_guard/new_drop", |b| {
b.iter(|| {
let g = ShutdownGuard::new(|| {});
black_box(&g);
});
});
}
criterion_group!(
benches,
bench_parallel_map,
bench_parallel_for_each,
bench_retry_ext,
bench_rate_limiter,
bench_semaphore_pool,
bench_aggregate_error,
bench_shutdown_guard,
);
criterion_main!(benches);
@@ -0,0 +1,54 @@
//! Demonstrates the scaling model: bounded concurrency, no over-allocation.
//!
//! Run: `cargo run -p mytheclipse --features full --example scaling_demo`
//!
//! Shows both modes:
//! 1. Explicit concurrency (`4`) — never more than 4 futures in flight.
//! 2. Auto concurrency (`()`) — sized from host CPU (`available_parallelism`),
//! still bounded (it never spawns one task per item).
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Arc;
use std::time::{Duration, Instant};
use mytheclipse::parallel_map::{parallel_for_each, ParallelConcurrency};
#[tokio::main]
async fn main() {
let total = 100u32;
println!("host available_parallelism = {}", <() as ParallelConcurrency>::resolve(()));
println!("total items = {total}");
println!();
run("explicit concurrency=4", 4, total).await;
println!();
run("auto concurrency=()", (), total).await;
}
async fn run(label: &str, concurrency: impl ParallelConcurrency + Copy, total: u32) {
let in_flight = Arc::new(AtomicUsize::new(0));
let peak = Arc::new(AtomicUsize::new(0));
let resolved = concurrency.resolve();
let t = Arc::clone(&in_flight);
let p = Arc::clone(&peak);
let start = Instant::now();
parallel_for_each(0..total, concurrency, move |_| {
let t = Arc::clone(&t);
let p = Arc::clone(&p);
async move {
let now = t.fetch_add(1, Ordering::SeqCst) + 1;
p.fetch_max(now, Ordering::SeqCst);
tokio::time::sleep(Duration::from_millis(1)).await;
t.fetch_sub(1, Ordering::SeqCst);
Ok::<_, std::io::Error>(())
}
})
.await
.unwrap();
let elapsed = start.elapsed();
println!("{label} resolved={resolved}");
println!(" peak in-flight = {} (bounded, never {total})", peak.load(Ordering::SeqCst));
println!(" elapsed = {elapsed:?} (sequential ~{}ms)", total * 1);
}
+261
View File
@@ -2,6 +2,8 @@
use std::panic::{catch_unwind, AssertUnwindSafe};
use rayon::iter::{IntoParallelIterator, ParallelIterator};
use crate::context::context;
use crate::error::MytheclipseError;
@@ -45,6 +47,195 @@ fn panic_payload_to_string(payload: Box<dyn std::any::Any + Send>) -> String {
}
}
/// Errors collected while mapping over items on the CPU compute pool.
///
/// Each entry is one item's error message (from an `Err` return or a panic).
/// Unlike [`crate::aggregate_error::AggregateError`], this lives under the
/// `compute` feature only and carries plain strings, so the compute pool
/// primitives compile without the `resiliency` feature.
#[derive(Debug, Default)]
pub struct ComputeErrors {
errors: Vec<String>,
}
impl ComputeErrors {
/// Number of items that failed (returned `Err` or panicked).
pub fn len(&self) -> usize {
self.errors.len()
}
/// `true` when every item succeeded.
pub fn is_empty(&self) -> bool {
self.errors.is_empty()
}
/// Iterate over the error messages.
pub fn iter(&self) -> impl Iterator<Item = &str> {
self.errors.iter().map(String::as_str)
}
}
impl std::fmt::Display for ComputeErrors {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{} compute item(s) failed:", self.errors.len())?;
for e in &self.errors {
write!(f, "\n - {e}")?;
}
Ok(())
}
}
impl std::error::Error for ComputeErrors {}
/// Runs `f` over every item **on the rayon compute pool**, in parallel,
/// returning the results **in input order**.
///
/// This is the CPU-specific counterpart to [`crate::parallel_map::parallel_map`]:
/// work is distributed across the compute pool's worker threads (sized from
/// [`crate::runtime_auto::RuntimeConfig::auto`] — one per logical core) by
/// rayon's work-stealing scheduler, so concurrency is bounded by the pool and
/// **auto-scales to the host CPU** without a manual `concurrency` parameter.
///
/// Each item's closure runs inside [`std::panic::catch_unwind`]: a panic is
/// caught and recorded as an error instead of unwinding across the pool. All
/// errors (returned or panicked) are collected into a single
/// [`ComputeErrors`].
///
/// ```
/// use mytheclipse::compute::compute_map;
///
/// let squares = compute_map(vec![1u32, 2, 3, 4], |x| Ok::<_, String>(x * x)).unwrap();
/// assert_eq!(squares, vec![1, 4, 9, 16]);
///
/// // Failures are aggregated, order is preserved:
/// let out = compute_map(vec![1, 2, 3], |x| {
/// if x == 2 { Err("boom".to_string()) } else { Ok(x * 10) }
/// }).unwrap_err();
/// assert_eq!(out.len(), 1);
/// ```
pub fn compute_map<I, T, F>(items: I, f: F) -> Result<Vec<T>, ComputeErrors>
where
I: IntoParallelIterator + Send,
I::Item: Send,
T: Send,
F: Fn(I::Item) -> Result<T, String> + Send + Sync,
{
let wrapped = AssertUnwindSafe(f);
let collected: Vec<Result<T, String>> = context()
.compute_pool
.install(move || {
let f = wrapped;
items
.into_par_iter()
.map(|item| {
catch_unwind(AssertUnwindSafe(|| f(item)))
.unwrap_or_else(|payload| Err(panic_payload_to_string(payload)))
})
.collect()
});
let mut values = Vec::with_capacity(collected.len());
let mut errors = Vec::new();
for r in collected {
match r {
Ok(v) => values.push(v),
Err(e) => errors.push(e),
}
}
if errors.is_empty() {
Ok(values)
} else {
Err(ComputeErrors { errors })
}
}
/// Runs two heavy closures in parallel on the compute pool, returning both
/// results.
///
/// This wraps [`rayon::join`] with panic isolation: if either branch panics,
/// its panic is converted into a [`MytheclipseError::ComputePanic`] and the
/// other branch still completes. The pool remains usable afterward.
///
/// ```
/// use mytheclipse::compute::compute_join;
///
/// let (a, b) = compute_join(
/// || (0..1_000_000u64).sum::<u64>(),
/// || (1_000_000..2_000_000u64).sum::<u64>(),
/// ).unwrap();
/// assert_eq!(a + b, (0..2_000_000u64).sum::<u64>());
/// ```
pub fn compute_join<A, RA, B, RB>(
a: A,
b: B,
) -> Result<(RA, RB), MytheclipseError>
where
A: FnOnce() -> RA + Send,
RA: Send,
B: FnOnce() -> RB + Send,
RB: Send,
{
let a = AssertUnwindSafe(a);
let b = AssertUnwindSafe(b);
context()
.compute_pool
.install(|| {
let (ra, rb) = rayon::join(
move || catch_unwind(a).map_err(|p| MytheclipseError::ComputePanic(panic_payload_to_string(p))),
move || catch_unwind(b).map_err(|p| MytheclipseError::ComputePanic(panic_payload_to_string(p))),
);
Ok((ra?, rb?))
})
}
/// Runs `f` over every item on the compute pool in parallel, discarding
/// return values (side effects only), collecting errors and panics.
///
/// ```
/// use std::sync::atomic::{AtomicUsize, Ordering};
/// use std::sync::Arc;
/// use mytheclipse::compute::compute_par_for_each;
///
/// let count = Arc::new(AtomicUsize::new(0));
/// let c = Arc::clone(&count);
/// compute_par_for_each(0..100, move |x| {
/// c.fetch_add(x as usize, Ordering::SeqCst);
/// Ok::<_, String>(())
/// }).unwrap();
/// assert_eq!(count.load(Ordering::SeqCst), 4950);
/// ```
pub fn compute_par_for_each<I, F>(items: I, f: F) -> Result<(), ComputeErrors>
where
I: IntoParallelIterator + Send,
I::Item: Send,
F: Fn(I::Item) -> Result<(), String> + Send + Sync,
{
let wrapped = AssertUnwindSafe(f);
let collected: Vec<Result<(), String>> = context()
.compute_pool
.install(move || {
let f = wrapped;
items
.into_par_iter()
.map(|item| {
catch_unwind(AssertUnwindSafe(|| f(item)))
.unwrap_or_else(|payload| Err(panic_payload_to_string(payload)))
})
.collect()
});
if collected.iter().any(|r| r.is_err()) {
Err(ComputeErrors {
errors: collected
.into_iter()
.filter_map(|r| r.err())
.collect(),
})
} else {
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
@@ -57,4 +248,74 @@ mod tests {
let recovered = compute(|| 1 + 1);
assert_eq!(recovered.unwrap(), 2);
}
#[test]
fn compute_map_ordered_and_aggregates_errors() {
let squares = compute_map(vec![1u32, 2, 3, 4], |x| Ok::<_, String>(x * x)).unwrap();
assert_eq!(squares, vec![1, 4, 9, 16]);
let err = compute_map(vec![1u32, 2, 3], |x| {
if x == 2 {
Err("boom".to_string())
} else {
Ok(x * 10)
}
})
.unwrap_err();
assert_eq!(err.len(), 1);
assert_eq!(err.iter().next().unwrap(), "boom");
}
#[test]
fn compute_map_panic_is_isolated_and_collected() {
let err = compute_map(vec![1u32, 2, 3], |x| {
if x == 2 {
panic!("item panic")
} else {
Ok::<_, String>(x)
}
})
.unwrap_err();
assert_eq!(err.len(), 1);
assert!(err.iter().next().unwrap().contains("item panic"));
// pool still usable
let recovered = compute_map(vec![1u32], |x| Ok::<_, String>(x + 1)).unwrap();
assert_eq!(recovered, vec![2]);
}
#[test]
fn compute_join_runs_both_branches() {
let (a, b) = compute_join(
|| (0..100_000u64).sum::<u64>(),
|| (100_000..200_000u64).sum::<u64>(),
)
.unwrap();
assert_eq!(a + b, (0..200_000u64).sum::<u64>());
}
#[test]
fn compute_join_panic_is_isolated() {
let a = compute_join(|| panic!("branch a"), || 42u32);
assert!(matches!(a, Err(MytheclipseError::ComputePanic(_))));
// pool still usable
let ok = compute_join(|| 1u32, || 2u32).unwrap();
assert_eq!(ok, (1, 2));
}
#[test]
fn compute_par_for_each_runs_all_side_effects() {
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Arc;
let count = Arc::new(AtomicUsize::new(0));
let c = Arc::clone(&count);
compute_par_for_each(0..100, move |x| {
c.fetch_add(x as usize, Ordering::SeqCst);
Ok::<_, String>(())
})
.unwrap();
assert_eq!(count.load(Ordering::SeqCst), 4950);
}
}
+2 -2
View File
@@ -44,7 +44,7 @@ pub use retry_ext::RetryExt;
#[cfg(feature = "resiliency")]
pub use aggregate_error::AggregateError;
#[cfg(feature = "resiliency")]
pub use parallel_map::{parallel_map, parallel_map_unordered, parallel_for_each};
pub use parallel_map::{parallel_map, parallel_map_unordered, parallel_for_each, ParallelConcurrency};
#[cfg(feature = "observability")]
pub mod auto_metrics_service;
#[cfg(feature = "observability")]
@@ -109,7 +109,7 @@ pub use error::MytheclipseError;
#[cfg(feature = "io")]
pub use io::spawn_io;
#[cfg(feature = "compute")]
pub use compute::compute;
pub use compute::{compute, compute_join, compute_map, compute_par_for_each, ComputeErrors};
#[cfg(feature = "bg")]
pub use bg::spawn_bg;
+62 -11
View File
@@ -13,6 +13,42 @@ use tokio::sync::Semaphore;
use crate::aggregate_error::AggregateError;
/// Resolves a concurrency hint into an actual bound.
///
/// Pass an explicit `usize` for a fixed bound, or `()` to auto-size from the
/// host CPU (`std::thread::available_parallelism`).
///
/// ```
/// use mytheclipse::parallel_map::{parallel_map, ParallelConcurrency};
///
/// #[tokio::main]
/// async fn main() {
/// let items = vec![1u32, 2, 3, 4];
/// let out = parallel_map(items, (), |x| async move { Ok::<_, std::io::Error>(x * 2) })
/// .await
/// .unwrap();
/// assert_eq!(out, vec![2, 4, 6, 8]);
/// }
/// ```
pub trait ParallelConcurrency {
/// Turns the hint into a concrete positive concurrency bound.
fn resolve(self) -> usize;
}
impl ParallelConcurrency for usize {
fn resolve(self) -> usize {
self.max(1)
}
}
impl ParallelConcurrency for () {
fn resolve(self) -> usize {
std::thread::available_parallelism()
.map(|n| n.get())
.unwrap_or(1)
}
}
/// Runs `f` over every element of `items`, with at most `concurrency`
/// futures in flight, and returns the results **in input order**.
///
@@ -23,21 +59,25 @@ use crate::aggregate_error::AggregateError;
/// Note: `items` is fully collected into memory up front (see
/// [`parallel_for_each`] for a streaming variant that avoids materializing).
///
/// `concurrency` accepts an explicit `usize` or `()` to auto-size from the
/// host CPU (see [`ParallelConcurrency`]).
///
/// ```
/// use mytheclipse::parallel_map::parallel_map;
///
/// #[tokio::main]
/// async fn main() {
/// let items = vec![1u32, 2, 3, 4, 5];
/// let doubled = parallel_map(items, 4, |x| async move { Ok::<_, std::io::Error>(x * 2) })
/// // Auto concurrency: `()` resolved to available_parallelism().
/// let doubled = parallel_map(items, (), |x| async move { Ok::<_, std::io::Error>(x * 2) })
/// .await
/// .unwrap();
/// assert_eq!(doubled, vec![2, 4, 6, 8, 10]);
/// }
/// ```
pub async fn parallel_map<I, T, F, Fut, E>(
pub async fn parallel_map<I, T, F, Fut, E, C>(
items: I,
concurrency: usize,
concurrency: C,
f: F,
) -> Result<Vec<T>, AggregateError>
where
@@ -47,9 +87,11 @@ where
F: Fn(I::Item) -> Fut + Send + Sync + 'static,
Fut: Future<Output = Result<T, E>> + Send + 'static,
E: std::error::Error + Send + Sync + 'static,
C: ParallelConcurrency,
{
let n = concurrency.resolve();
let items: Vec<I::Item> = items.into_iter().collect();
let sem = Arc::new(Semaphore::new(concurrency.max(1)));
let sem = Arc::new(Semaphore::new(n));
let f = Arc::new(f);
let mut tasks = Vec::with_capacity(items.len());
@@ -83,9 +125,12 @@ where
/// futures are polled in spawn order here, results come back in input order.
/// (True completion-order collection would require a `futures` dependency, so
/// this name is provided for API symmetry and documented as input-ordered.)
pub async fn parallel_map_unordered<I, T, F, Fut, E>(
///
/// `concurrency` accepts an explicit `usize` or `()` to auto-size from the
/// host CPU (see [`ParallelConcurrency`]).
pub async fn parallel_map_unordered<I, T, F, Fut, E, C>(
items: I,
concurrency: usize,
concurrency: C,
f: F,
) -> Result<Vec<T>, AggregateError>
where
@@ -95,9 +140,11 @@ where
F: Fn(I::Item) -> Fut + Send + Sync + 'static,
Fut: Future<Output = Result<T, E>> + Send + 'static,
E: std::error::Error + Send + Sync + 'static,
C: ParallelConcurrency,
{
let n = concurrency.resolve();
let items: Vec<I::Item> = items.into_iter().collect();
let sem = Arc::new(Semaphore::new(concurrency.max(1)));
let sem = Arc::new(Semaphore::new(n));
let f = Arc::new(f);
let mut tasks = Vec::with_capacity(items.len());
@@ -139,6 +186,9 @@ where
///
/// Errors are aggregated into a single [`AggregateError`].
///
/// `concurrency` accepts an explicit `usize` or `()` to auto-size from the
/// host CPU (see [`ParallelConcurrency`]).
///
/// ```
/// use std::sync::atomic::{AtomicUsize, Ordering};
/// use std::sync::Arc;
@@ -148,7 +198,7 @@ where
/// async fn main() {
/// let seen = Arc::new(AtomicUsize::new(0));
/// let s = Arc::clone(&seen);
/// parallel_for_each(0u32..100, 8, move |x| {
/// parallel_for_each(0u32..100, (), move |x| {
/// let s = Arc::clone(&s);
/// async move {
/// s.fetch_add(x as usize, Ordering::SeqCst);
@@ -160,9 +210,9 @@ where
/// assert_eq!(seen.load(Ordering::SeqCst), 4950); // sum 0..100
/// }
/// ```
pub async fn parallel_for_each<I, F, Fut, E>(
pub async fn parallel_for_each<I, F, Fut, E, C>(
items: I,
concurrency: usize,
concurrency: C,
f: F,
) -> Result<(), AggregateError>
where
@@ -172,10 +222,11 @@ where
F: Fn(I::Item) -> Fut + Send + Sync + 'static,
Fut: Future<Output = Result<(), E>> + Send + 'static,
E: std::error::Error + Send + Sync + 'static,
C: ParallelConcurrency,
{
use tokio::sync::{mpsc, Mutex};
let n = concurrency.max(1);
let n = concurrency.resolve();
let (tx, rx) = mpsc::channel::<I::Item>(n * 2);
let f = Arc::new(f);
let sem = Arc::new(Semaphore::new(n));