Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 semantic-release-bot
|
68a0ec9613 | ||
 asepharyana
|
e14894479d | ||
|
semantic-release-bot
|
f86abc4ce1 | ||
|
asepharyana
|
d00881c2b9 | ||
|
semantic-release-bot
|
829c5714d2 | ||
|
asepharyana
|
5df04d7512 | ||
|
asepharyana
|
a6cf58ea7f | ||
|
asepharyana
|
de54e801fb | ||
|
asepharyana
|
d03d32a923 | ||
|
asepharyana
|
c87ae760bf |
@@ -0,0 +1,33 @@
|
||||
# Implementation Spec: Round 16 — COMPLETE
|
||||
|
||||
## Goal
|
||||
Make the round-7-15 abstractions actually usable — a single, runnable, wired
|
||||
example showing high-level primitives composing together.
|
||||
|
||||
## New File
|
||||
|
||||
### examples/high_level.rs (mytheclipse-core)
|
||||
`crates/mytheclipse/examples/high_level.rs`
|
||||
- One realistic flow demoing, wired together:
|
||||
1. RuntimeConfig::auto() — auto thread/core sizing from host CPU
|
||||
2. parallel_map — bounded fan-out + AggregateError
|
||||
3. RetryExt — ergonomic .retry() on a Future
|
||||
4. ShutdownGuard — RAII exactly-once cleanup
|
||||
5. AutoReconnectPool — self-healing resource pool (dead value replaced)
|
||||
6. AutoMetricsServiceBuilder — auto latency/outcome metrics
|
||||
- Run: `cargo run -p mytheclipse --features full --example high_level`
|
||||
|
||||
## Verified Output (real run, 8-core host)
|
||||
```
|
||||
1. RuntimeConfig::auto() -> worker=8, blocking=12, compute=8, io=4
|
||||
2. parallel_map -> [10, 20, 30, 40, 50]
|
||||
3. RetryExt with 4 attempts -> 42
|
||||
4. ShutdownGuard fired 1x (exactly-once, even on unwind)
|
||||
5. AutoReconnectPool first acquire -> 999
|
||||
6. AutoMetrics -> 1 counters, 1 histograms
|
||||
```
|
||||
|
||||
## Files
|
||||
- new: crates/mytheclipse/examples/high_level.rs
|
||||
|
||||
Build: exit 0. Run: succeeds (verified above).
|
||||
@@ -0,0 +1,54 @@
|
||||
# Implementation Spec: Round 17 — Race-Safety Stress Tests + Doctests
|
||||
|
||||
## Goal
|
||||
Misi project: menghilangkan boilerplate race-condition. Bukti nyata bahwa
|
||||
primitives aman di bawah kontensi tinggi. Tambahkan:
|
||||
1. Stress/concurrency tests untuk primitives race-sensitive di core crate
|
||||
2. Doctest `# Examples` untuk fitur round 7-16 agar docs.rs langsung berguna
|
||||
|
||||
## 1. New file: crates/mytheclipse/tests/race_stress.rs
|
||||
|
||||
Integration test (tests/ dir = pakai public API saja, autentik dari luar):
|
||||
- `tokio::test(flavor = "multi_thread", worker_threads = 8)` — kontensi asli
|
||||
- High-contention tests:
|
||||
a. TokenBucket try_consume atomic — 64 tasks × 1000 consumes dari 1 bucket
|
||||
capacity 100, rate tinggi → total consume ≤ capacity per window, no double
|
||||
b. SemaphorePool acquire/release concurrent — 100 tasks acquire+release
|
||||
cycle, final available == capacity, no leak
|
||||
c. AutoReconnectPool — healthy probe retval, 50 concurrent acquire, semua
|
||||
dapat item valid
|
||||
d. RateLimitedQueue concurrent enqueue/dequeue — 8 worker × 1000 item,
|
||||
total dequeue == total enqueue
|
||||
e. ShutdownGuard exactly-once — 10 clones-ish concurrent drops → callback
|
||||
count == 1 (via Arc<AtomicUsize>)
|
||||
f. parallel_map 10k items concurrency 32 — hasil input-ordered, nilai benar
|
||||
g. parallel_for_each 10k items concurrency 32 — side-effect count == 10k
|
||||
h. AggregateError from_results merge 100 results mix ok/err — error count
|
||||
benar, values semua lolos yang ok
|
||||
- Assertions: `assert_eq!` pada counts; harness FAILS kalau race → flaky
|
||||
|
||||
## 2. Doctest `# Examples` additions
|
||||
|
||||
Untuk file baru round 9-16 (masing-masing sudah punya unit tests; tambah
|
||||
doctest singkat di doc comment pub item paling utama):
|
||||
- retry_ext.rs: `RetryExt::retry` contoh 1-liner
|
||||
- auto_metrics_service.rs: AutoMetricsServiceBuilder contoh
|
||||
- runtime_auto.rs: RuntimeConfig::auto contoh
|
||||
- shutdown_guard.rs: ShutdownGuard contoh
|
||||
- aggregate_error.rs: AggregateError::from_results contoh
|
||||
- parallel_map.rs: parallel_map + parallel_for_each contoh
|
||||
- pool.rs AutoReconnectPool: contoh
|
||||
|
||||
Doctest wajib compile: `cargo test --doc --workspace --all-features`
|
||||
|
||||
## Files
|
||||
- new: crates/mytheclipse/tests/race_stress.rs
|
||||
- edit: parallel_map.rs, retry_ext.rs, auto_metrics_service.rs, runtime_auto.rs,
|
||||
shutdown_guard.rs, aggregate_error.rs, pool.rs (doctest blocks)
|
||||
|
||||
## Verification
|
||||
1. `cargo test -p mytheclipse --tests --all-features` — 0 FAILED
|
||||
2. `cargo test -p mytheclipse --doc --all-features` — 0 FAILED
|
||||
3. `cargo build --workspace --all-features` — exit 0
|
||||
4. `cargo clippy --workspace --all-features` — 0 new warnings
|
||||
5. Commit + push
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
@@ -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,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,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,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,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,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,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,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"
|
||||
|
||||
@@ -0,0 +1,67 @@
|
||||
//! Race-safety stress tests for the queue crate's rate-limited primitives.
|
||||
|
||||
use std::sync::atomic::{AtomicUsize, Ordering};
|
||||
use std::sync::Arc;
|
||||
use std::time::Duration;
|
||||
|
||||
use mytheclipse_queue::in_memory::InMemoryQueue;
|
||||
use mytheclipse_queue::rate_limited::RateLimitedQueue;
|
||||
use mytheclipse_queue::traits::Queue;
|
||||
|
||||
const TASKS: usize = 8;
|
||||
const PER_TASK: usize = 1000;
|
||||
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
|
||||
async fn rate_limited_queue_no_item_loss_under_contention() {
|
||||
// Enqueue 8000 items, dequeue them all concurrently: nothing may vanish.
|
||||
let inner = InMemoryQueue::new();
|
||||
let q = Arc::new(RateLimitedQueue::new(inner, 1_000_000.0, 10_000));
|
||||
|
||||
let producer: tokio::task::JoinHandle<()> = tokio::spawn({
|
||||
let q = Arc::clone(&q);
|
||||
async move {
|
||||
for i in 0..(TASKS * PER_TASK) {
|
||||
q.enqueue("stress", format!("item-{i}").into_bytes())
|
||||
.await
|
||||
.unwrap();
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// Drain concurrently with the producer.
|
||||
let seen = Arc::new(AtomicUsize::new(0));
|
||||
let mut workers = Vec::new();
|
||||
for _ in 0..TASKS {
|
||||
let q = Arc::clone(&q);
|
||||
let s = Arc::clone(&seen);
|
||||
workers.push(tokio::spawn(async move {
|
||||
loop {
|
||||
match q.dequeue("stress", Duration::from_millis(50)).await.unwrap() {
|
||||
Some(job) => {
|
||||
let _ = String::from_utf8(job.payload).unwrap();
|
||||
s.fetch_add(1, Ordering::SeqCst);
|
||||
}
|
||||
None => {
|
||||
// Empty + producer done => we're finished.
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
}));
|
||||
}
|
||||
|
||||
producer.await.unwrap();
|
||||
for w in workers {
|
||||
w.await.unwrap();
|
||||
}
|
||||
|
||||
// Slight subtlety: a worker may observe None while producer still has
|
||||
// items in flight (producer finished above, but enqueue is async —
|
||||
// actually producer.await guarantees all enqueues completed). Since the
|
||||
// producer finished, any None means truly drained.
|
||||
assert_eq!(
|
||||
seen.load(Ordering::SeqCst),
|
||||
TASKS * PER_TASK,
|
||||
"items lost under contention"
|
||||
);
|
||||
}
|
||||
@@ -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,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"
|
||||
|
||||
@@ -1,3 +1,119 @@
|
||||
# [1.18.0](https://github.com/asepharyana/mytheclipse/compare/v1.17.0...v1.18.0) (2026-08-29)
|
||||
|
||||
### Documentation
|
||||
|
||||
* add `high_level` example wiring round-7-15 abstractions (RuntimeConfig, parallel_map, RetryExt, ShutdownGuard, AutoReconnectPool, AutoMetricsServiceBuilder)
|
||||
|
||||
# [1.17.0](https://github.com/asepharyana/mytheclipse/compare/v1.16.0...v1.17.0) (2026-08-29)
|
||||
|
||||
### Features
|
||||
|
||||
* **parallel_map:** add `parallel_for_each` streaming bounded fan-out (no full input materialization)
|
||||
|
||||
# [1.16.0](https://github.com/asepharyana/mytheclipse/compare/v1.15.0...v1.16.0) (2026-08-29)
|
||||
|
||||
### Features
|
||||
|
||||
* **parallel_map:** add `parallel_map` / `parallel_map_unordered` bounded fan-out with AggregateError
|
||||
|
||||
# [1.15.0](https://github.com/asepharyana/mytheclipse/compare/v1.14.0...v1.15.0) (2026-08-29)
|
||||
|
||||
### Features
|
||||
|
||||
* **aggregate_error:** add `AggregateError` for parallel/fan-out error aggregation
|
||||
|
||||
# [1.14.0](https://github.com/asepharyana/mytheclipse/compare/v1.13.0...v1.14.0) (2026-08-29)
|
||||
|
||||
### Features
|
||||
|
||||
* **pool:** add `AutoReconnectPool` + `Reconnectable` self-healing resource pool
|
||||
|
||||
# [1.13.0](https://github.com/asepharyana/mytheclipse/compare/v1.12.0...v1.13.0) (2026-08-29)
|
||||
|
||||
### Features
|
||||
|
||||
* **runtime_auto:** add `RuntimeConfig` auto thread/core allocation + `ShutdownGuard` RAII
|
||||
|
||||
# [1.12.0](https://github.com/asepharyana/mytheclipse/compare/v1.11.0...v1.12.0) (2026-08-29)
|
||||
|
||||
### Features
|
||||
|
||||
* **auto_metrics:** add `AutoMetricsServiceBuilder` (metrics + [mytheclipse-queue](crates/mytheclipse-queue) `RateLimitedWorkerPool`)
|
||||
|
||||
# [1.11.0](https://github.com/asepharyana/mytheclipse/compare/v1.10.0...v1.11.0) (2026-08-29)
|
||||
|
||||
### Features
|
||||
|
||||
* **retry_ext:** add ergonomic `RetryExt` Future extension — also covers ResilientHttpClient from [mytheclipse-http](crates/mytheclipse-http)
|
||||
|
||||
# [1.10.0](https://github.com/asepharyana/mytheclipse/compare/v1.9.0...v1.10.0) (2026-08-29)
|
||||
|
||||
### Features
|
||||
|
||||
* **http:** add `ResilientHttpClient` ([mytheclipse-http](crates/mytheclipse-http)) with retry + circuit breaker + timeout
|
||||
* **middleware:** add composable `MiddlewarePipeline`
|
||||
* **bg_join:** add `BgJoiner` graceful task joiner
|
||||
|
||||
# [1.9.0](https://github.com/asepharyana/mytheclipse/compare/v1.8.0...v1.9.0) (2026-08-28)
|
||||
|
||||
### Features
|
||||
|
||||
* **bg_join:** add `BgJoiner` graceful task joiner
|
||||
* **middleware:** add composable `MiddlewarePipeline`
|
||||
* **queue:** add `RateLimitedQueue` ([mytheclipse-queue](crates/mytheclipse-queue))
|
||||
|
||||
# [1.8.0](https://github.com/asepharyana/mytheclipse/compare/v1.7.0...v1.8.0) (2026-08-28)
|
||||
|
||||
### Features
|
||||
|
||||
* **pool_health:** add `HealthCheckedPool`
|
||||
* **crypto:** add `HkdfKeyDeriver` ([mytheclipse-crypto](crates/mytheclipse-crypto))
|
||||
* **queue:** add `BackpressureEnforcer` / `enqueue_with_backpressure`
|
||||
|
||||
# [1.7.0](https://github.com/asepharyana/mytheclipse/compare/v1.6.0...v1.7.0) (2026-08-28)
|
||||
|
||||
### Features
|
||||
|
||||
* **batch:** add `BatchProcessor` & `BatchJobHandler`
|
||||
* **health:** add `CircuitBreakerHealthCheck` / `MetricsHealthCheck`
|
||||
* **crypto:** add `TypedKeyRegistry`
|
||||
* **http:** add `MetricsHttpHandler`
|
||||
|
||||
# [1.6.0](https://github.com/asepharyana/mytheclipse/compare/v1.5.0...v1.6.0) (2026-08-28)
|
||||
|
||||
### Features
|
||||
|
||||
* **circuit_breaker:** add snapshot metrics
|
||||
* **retry:** add `RetryStats`
|
||||
* lifecycle fixes
|
||||
|
||||
# [1.5.0](https://github.com/asepharyana/mytheclipse/compare/v1.4.1...v1.5.0) (2026-08-28)
|
||||
|
||||
### Features
|
||||
|
||||
* **validation:** add `ConfigValidator`
|
||||
* **lifecycle:** add `AsyncLifecycleManager`
|
||||
* **metrics:** add `MetricsBridge`
|
||||
* **ratelimit:** rate limiter pre-acquire
|
||||
|
||||
# [1.4.0](https://github.com/asepharyana/mytheclipse/compare/v1.3.5...v1.4.0) (2026-08-28)
|
||||
|
||||
### Features
|
||||
|
||||
* add 4 new crates: [mytheclipse-queue](crates/mytheclipse-queue), [mytheclipse-tracing](crates/mytheclipse-tracing), [mytheclipse-http](crates/mytheclipse-http), [mytheclipse-cli](crates/mytheclipse-cli)
|
||||
|
||||
# [1.3.0](https://github.com/asepharyana/mytheclipse/compare/v1.2.0...v1.3.0) (2026-08-28)
|
||||
|
||||
### Features
|
||||
|
||||
* add [mytheclipse-storage](crates/mytheclipse-storage) crate for unified storage abstraction
|
||||
|
||||
# [1.2.0](https://github.com/asepharyana/mytheclipse/compare/v1.1.0...v1.2.0) (2026-08-28)
|
||||
|
||||
### Features
|
||||
|
||||
* add panic tracking and logging with `PanicTracker`
|
||||
|
||||
# [1.1.0](https://github.com/asepharyana/mytheclipse/compare/v1.0.0...v1.1.0) (2026-08-28)
|
||||
|
||||
|
||||
|
||||
@@ -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"]
|
||||
@@ -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,134 @@
|
||||
//! End-to-end demo of the high-level (round 7-15) abstractions in `mytheclipse`.
|
||||
//!
|
||||
//! Run with: `cargo run -p mytheclipse --features full --example high_level`
|
||||
//!
|
||||
//! Demonstrates, wired together in one realistic flow:
|
||||
//! - `RuntimeConfig::auto()` — auto thread/core sizing from the host CPU
|
||||
//! - `parallel_map` — bounded fan-out with AggregateError
|
||||
//! - `RetryExt` — ergonomic `.retry()` on a Future
|
||||
//! - `ShutdownGuard` — RAII cleanup guaranteed even on panic
|
||||
//! - `AutoReconnectPool` — self-healing resource pool
|
||||
//! - `AutoMetricsServiceBuilder` — service calls that auto-record metrics
|
||||
|
||||
use std::sync::atomic::{AtomicU32, Ordering};
|
||||
use std::sync::Arc;
|
||||
use std::time::Duration;
|
||||
|
||||
use mytheclipse::{
|
||||
aggregate_error::AggregateError,
|
||||
auto_metrics_service::AutoMetricsServiceBuilder,
|
||||
parallel_map::parallel_map,
|
||||
pool::{AutoReconnectPool, Pool, Reconnectable, SemaphorePool},
|
||||
retry_ext::RetryExt,
|
||||
runtime_auto::RuntimeConfig,
|
||||
shutdown_guard::ShutdownGuard,
|
||||
service_builder::ServiceConfig,
|
||||
};
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() {
|
||||
println!("== mytheclipse high-level abstractions demo ==");
|
||||
|
||||
// 1. Auto thread/core allocation from host CPU topology.
|
||||
let cfg = RuntimeConfig::auto();
|
||||
println!(
|
||||
"1. RuntimeConfig::auto() -> worker={}, blocking={}, compute={}, io={}",
|
||||
cfg.worker_threads, cfg.max_blocking_threads, cfg.compute_threads, cfg.io_threads
|
||||
);
|
||||
|
||||
// 2. Bounded parallel fan-out with automatic error aggregation.
|
||||
let results: Result<Vec<i32>, AggregateError> =
|
||||
parallel_map(vec![1, 2, 3, 4, 5], 2, |x| async move {
|
||||
tokio::time::sleep(Duration::from_millis(10)).await;
|
||||
Ok::<_, std::io::Error>(x * 10)
|
||||
})
|
||||
.await;
|
||||
println!("2. parallel_map -> {:?}", results.unwrap());
|
||||
|
||||
// 3. Ergonomic retry on a Future.
|
||||
let attempts = Arc::new(AtomicU32::new(0));
|
||||
let a = Arc::clone(&attempts);
|
||||
let cfg = mytheclipse::retry::RetryConfig {
|
||||
max_attempts: 4,
|
||||
base_delay: Duration::from_millis(1),
|
||||
..Default::default()
|
||||
};
|
||||
let fut = async { Err::<u32, String>("boom".into()) };
|
||||
let op = move || {
|
||||
let a = Arc::clone(&a);
|
||||
async move {
|
||||
let n = a.fetch_add(1, Ordering::SeqCst);
|
||||
if n < 3 {
|
||||
Err::<u32, String>("transient".into())
|
||||
} else {
|
||||
Ok(42u32)
|
||||
}
|
||||
}
|
||||
};
|
||||
let value = fut.retry(cfg, |_: &String| true, op).await.unwrap();
|
||||
println!("3. RetryExt with {} attempts -> {value}", attempts.load(Ordering::SeqCst));
|
||||
|
||||
// 4. RAII ShutdownGuard — callback runs exactly once on drop, panic-safe.
|
||||
let fired = Arc::new(AtomicU32::new(0));
|
||||
let f = Arc::clone(&fired);
|
||||
{
|
||||
let _guard = ShutdownGuard::new(move || {
|
||||
f.fetch_add(1, Ordering::SeqCst);
|
||||
});
|
||||
} // guard dropped -> callback fires
|
||||
println!(
|
||||
"4. ShutdownGuard fired {}x (exactly-once, even on unwind)",
|
||||
fired.load(Ordering::SeqCst)
|
||||
);
|
||||
|
||||
// 5. AutoReconnectPool — transparently replaces dead resources.
|
||||
let auto = AutoReconnectPool::new(SemaphorePool::new(vec![1u32, 2u32]), Probe { dead: 1 });
|
||||
let first = auto.acquire().await.unwrap().resource;
|
||||
// Never the dead value (1) once the probe rejects it.
|
||||
println!("5. AutoReconnectPool first acquire -> {first}");
|
||||
|
||||
// 6. AutoMetricsServiceBuilder — auto records latency + outcome counters.
|
||||
let mut svc_cfg = ServiceConfig::default();
|
||||
svc_cfg.max_attempts = 2;
|
||||
let svc = AutoMetricsServiceBuilder::new("demo_op", svc_cfg);
|
||||
let n = Arc::new(AtomicU32::new(0));
|
||||
let n2 = Arc::clone(&n);
|
||||
let _: Result<u32, mytheclipse::service_builder::RunError<()>> = svc.run(|| {
|
||||
let n2 = Arc::clone(&n2);
|
||||
Box::pin(async move {
|
||||
tokio::time::sleep(Duration::from_millis(5)).await;
|
||||
let v = n2.fetch_add(1, Ordering::SeqCst);
|
||||
if v < 1 {
|
||||
Err(())
|
||||
} else {
|
||||
Ok(7u32)
|
||||
}
|
||||
})
|
||||
}).await;
|
||||
let snap = svc.collector().snapshot();
|
||||
println!(
|
||||
"6. AutoMetrics -> {} counters, {} histograms",
|
||||
snap.counters.len(),
|
||||
snap.histograms.len()
|
||||
);
|
||||
|
||||
println!("== demo complete ==");
|
||||
}
|
||||
|
||||
/// A [`Reconnectable`] probe that rejects any value matching `dead`.
|
||||
struct Probe {
|
||||
dead: u32,
|
||||
}
|
||||
|
||||
#[async_trait::async_trait]
|
||||
impl Reconnectable for Probe {
|
||||
type Item = u32;
|
||||
|
||||
fn is_healthy(&self, item: &Self::Item) -> bool {
|
||||
*item != self.dead
|
||||
}
|
||||
|
||||
async fn reconnect(&self) -> Result<Self::Item, Box<dyn std::error::Error + Send + Sync>> {
|
||||
Ok(999)
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
@@ -10,6 +10,27 @@
|
||||
use std::fmt;
|
||||
|
||||
/// An error that groups one or more underlying errors.
|
||||
///
|
||||
/// ```
|
||||
/// use mytheclipse::aggregate_error::AggregateError;
|
||||
///
|
||||
/// // Collect errors from N parallel results — all of them, not just the first:
|
||||
/// let results = vec![
|
||||
/// Ok::<_, std::io::Error>(1),
|
||||
/// Err(std::io::Error::other("boom")),
|
||||
/// Ok::<_, std::io::Error>(3),
|
||||
/// Err(std::io::Error::other("bam")),
|
||||
/// ];
|
||||
/// let out = AggregateError::from_results(results);
|
||||
/// let err = out.unwrap_err();
|
||||
/// assert_eq!(err.len(), 2); // both errors collected
|
||||
///
|
||||
/// // Build one incrementally too:
|
||||
/// let mut agg = AggregateError::with_context("fan-out");
|
||||
/// agg.push(std::io::Error::other("first"));
|
||||
/// agg.push(std::io::Error::other("second"));
|
||||
/// assert_eq!(agg.len(), 2);
|
||||
/// ```
|
||||
#[derive(Debug)]
|
||||
pub struct AggregateError {
|
||||
errors: Vec<Box<dyn std::error::Error + Send + Sync>>,
|
||||
|
||||
@@ -19,6 +19,22 @@ use crate::metrics::MetricsCollector;
|
||||
use crate::service_builder::{RunError, ServiceBuilder, ServiceConfig};
|
||||
|
||||
/// A [`ServiceBuilder`] wrapper that auto-records latency and outcome metrics.
|
||||
///
|
||||
/// ```
|
||||
/// use std::time::Duration;
|
||||
/// use mytheclipse::auto_metrics_service::AutoMetricsServiceBuilder;
|
||||
/// use mytheclipse::service_builder::ServiceConfig;
|
||||
///
|
||||
/// let cfg = ServiceConfig {
|
||||
/// max_attempts: 2,
|
||||
/// timeout: Duration::from_millis(1),
|
||||
/// ..ServiceConfig::default()
|
||||
/// };
|
||||
/// let svc = AutoMetricsServiceBuilder::new("checkout", cfg);
|
||||
/// // Every `.run()` call now auto-records outcome + latency on the shared
|
||||
/// // MetricsCollector (retrievable via `collector()`).
|
||||
/// let _ = svc.collector();
|
||||
/// ```
|
||||
pub struct AutoMetricsServiceBuilder {
|
||||
inner: ServiceBuilder,
|
||||
metrics: MetricsCollector,
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -128,6 +128,10 @@ pub use backpressure::{BackpressureError, BackpressureQueue, OverflowPolicy};
|
||||
pub use concurrency::{ConcurrencyLimiter, ConcurrencyPermit};
|
||||
#[cfg(feature = "traffic")]
|
||||
pub use pool::{Pool, PoolError, Pooled, SemaphorePool, AutoReconnectPool, Reconnectable};
|
||||
/// Re-export of `async-trait` so implementing [`pool::Reconnectable`] (and
|
||||
/// other async traits) doesn't require users to add their own `async-trait`
|
||||
/// dependency.
|
||||
pub use async_trait::async_trait;
|
||||
|
||||
#[cfg(feature = "lifecycle")]
|
||||
pub use shutdown::{ShutdownManager, ShutdownSignal};
|
||||
|
||||
@@ -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**.
|
||||
///
|
||||
@@ -22,9 +58,26 @@ 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).
|
||||
pub async fn parallel_map<I, T, F, Fut, E>(
|
||||
///
|
||||
/// `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];
|
||||
/// // 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, C>(
|
||||
items: I,
|
||||
concurrency: usize,
|
||||
concurrency: C,
|
||||
f: F,
|
||||
) -> Result<Vec<T>, AggregateError>
|
||||
where
|
||||
@@ -34,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());
|
||||
@@ -70,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
|
||||
@@ -82,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());
|
||||
@@ -125,9 +185,34 @@ where
|
||||
/// task and never gets ahead.
|
||||
///
|
||||
/// Errors are aggregated into a single [`AggregateError`].
|
||||
pub async fn parallel_for_each<I, F, Fut, E>(
|
||||
///
|
||||
/// `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;
|
||||
/// use mytheclipse::parallel_map::parallel_for_each;
|
||||
///
|
||||
/// #[tokio::main]
|
||||
/// async fn main() {
|
||||
/// let seen = Arc::new(AtomicUsize::new(0));
|
||||
/// let s = Arc::clone(&seen);
|
||||
/// parallel_for_each(0u32..100, (), move |x| {
|
||||
/// let s = Arc::clone(&s);
|
||||
/// async move {
|
||||
/// s.fetch_add(x as usize, Ordering::SeqCst);
|
||||
/// Ok::<_, std::io::Error>(())
|
||||
/// }
|
||||
/// })
|
||||
/// .await
|
||||
/// .unwrap();
|
||||
/// assert_eq!(seen.load(Ordering::SeqCst), 4950); // sum 0..100
|
||||
/// }
|
||||
/// ```
|
||||
pub async fn parallel_for_each<I, F, Fut, E, C>(
|
||||
items: I,
|
||||
concurrency: usize,
|
||||
concurrency: C,
|
||||
f: F,
|
||||
) -> Result<(), AggregateError>
|
||||
where
|
||||
@@ -137,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));
|
||||
|
||||
@@ -94,6 +94,36 @@ pub trait Reconnectable {
|
||||
/// [`Reconnectable::is_healthy`]; if unhealthy, a replacement is produced via
|
||||
/// [`Reconnectable::reconnect`] and handed back instead. This removes the
|
||||
/// per-call-site "is my connection dead? rebuild it" boilerplate.
|
||||
///
|
||||
/// ```
|
||||
/// use mytheclipse::pool::{AutoReconnectPool, Pool, Reconnectable, SemaphorePool};
|
||||
/// use mytheclipse::async_trait;
|
||||
///
|
||||
/// // A "connection" that's dead when its value equals 0.
|
||||
/// #[derive(Clone)]
|
||||
/// struct Conn { alive: bool }
|
||||
/// impl Default for Conn { fn default() -> Self { Self { alive: true } } }
|
||||
///
|
||||
/// #[derive(Default)]
|
||||
/// struct ConnReconnector;
|
||||
///
|
||||
/// #[async_trait]
|
||||
/// impl Reconnectable for ConnReconnector {
|
||||
/// type Item = Conn;
|
||||
/// fn is_healthy(&self, c: &Conn) -> bool { c.alive }
|
||||
/// async fn reconnect(&self) -> Result<Conn, Box<dyn std::error::Error + Send + Sync>> {
|
||||
/// Ok(Conn::default())
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// #[tokio::main]
|
||||
/// async fn main() {
|
||||
/// let pool = SemaphorePool::new(vec![Conn { alive: false }, Conn::default()]);
|
||||
/// let pool = AutoReconnectPool::new(pool, ConnReconnector);
|
||||
/// let first = pool.acquire().await.unwrap();
|
||||
/// assert!(first.resource.alive); // dead one was transparently replaced
|
||||
/// }
|
||||
/// ```
|
||||
pub struct AutoReconnectPool<P, R> {
|
||||
inner: P,
|
||||
reconnect: R,
|
||||
|
||||
@@ -9,6 +9,36 @@ use std::pin::Pin;
|
||||
use crate::retry::{retry, RetryConfig, RetryError};
|
||||
|
||||
/// Extension trait adding ergonomic `.retry()` to any fallible future.
|
||||
///
|
||||
/// ```
|
||||
/// use std::time::Duration;
|
||||
/// use mytheclipse::retry_ext::RetryExt;
|
||||
/// use mytheclipse::retry::RetryConfig;
|
||||
///
|
||||
/// #[tokio::main]
|
||||
/// async fn main() {
|
||||
/// let cfg = RetryConfig { max_attempts: 3, base_delay: Duration::from_millis(1), ..RetryConfig::default() };
|
||||
/// let attempts = std::sync::Arc::new(std::sync::atomic::AtomicU32::new(0));
|
||||
/// let a = std::sync::Arc::clone(&attempts);
|
||||
///
|
||||
/// let op = move || {
|
||||
/// let a = std::sync::Arc::clone(&a);
|
||||
/// async move {
|
||||
/// if a.fetch_add(1, std::sync::atomic::Ordering::SeqCst) < 2 {
|
||||
/// Err::<(), String>("transient".into())
|
||||
/// } else {
|
||||
/// Ok(())
|
||||
/// }
|
||||
/// }
|
||||
/// };
|
||||
///
|
||||
/// let result = async { Err::<(), String>("first".into()) }
|
||||
/// .retry(cfg, |_: &String| true, op)
|
||||
/// .await;
|
||||
/// assert!(result.is_ok());
|
||||
/// assert_eq!(attempts.load(std::sync::atomic::Ordering::SeqCst), 3);
|
||||
/// }
|
||||
/// ```
|
||||
pub trait RetryExt<T, E>: Future<Output = Result<T, E>> + Sized + 'static
|
||||
where
|
||||
E: std::fmt::Debug + Send + 'static,
|
||||
|
||||
@@ -20,6 +20,22 @@ use std::num::NonZeroUsize;
|
||||
///
|
||||
/// Each field is a concrete `usize` (never zero) so it can be fed directly
|
||||
/// into a tokio/rayon/std-thread builder with no further `max(1)` guards.
|
||||
///
|
||||
/// ```
|
||||
/// use mytheclipse::runtime_auto::RuntimeConfig;
|
||||
///
|
||||
/// let cfg = RuntimeConfig::auto(); // from the host CPU
|
||||
/// let sized = RuntimeConfig::from_cores(4); // or explicit
|
||||
///
|
||||
/// // Feed straight into a tokio builder:
|
||||
/// let rt = tokio::runtime::Builder::new_multi_thread()
|
||||
/// .worker_threads(cfg.worker_threads)
|
||||
/// .max_blocking_threads(cfg.max_blocking_threads)
|
||||
/// .build()
|
||||
/// .unwrap();
|
||||
/// let _ = sized.compute_threads;
|
||||
/// rt.shutdown_timeout(std::time::Duration::from_millis(1));
|
||||
/// ```
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct RuntimeConfig {
|
||||
/// Worker threads for the main async runtime (default: one per core).
|
||||
|
||||
@@ -18,6 +18,25 @@ use std::sync::{Arc, Mutex};
|
||||
/// The callback is wrapped in a `Mutex<Option<_>>` so it can be taken out and
|
||||
/// run exactly once — even on a `panic!`-unwound drop — guaranteeing at-most-
|
||||
/// once semantics (no double-shutdown race).
|
||||
///
|
||||
/// ```
|
||||
/// use std::sync::atomic::{AtomicUsize, Ordering};
|
||||
/// use std::sync::Arc;
|
||||
/// use mytheclipse::shutdown_guard::ShutdownGuard;
|
||||
///
|
||||
/// let done = Arc::new(AtomicUsize::new(0));
|
||||
/// let d = Arc::clone(&done);
|
||||
/// {
|
||||
/// let _guard = ShutdownGuard::new(move || { d.fetch_add(1, Ordering::SeqCst); });
|
||||
/// // do work...
|
||||
/// } // guard dropped here -> callback fires exactly once
|
||||
/// assert_eq!(done.load(Ordering::SeqCst), 1);
|
||||
///
|
||||
/// // Or fire early with `finish()` (disarms the drop):
|
||||
/// let d2 = Arc::clone(&done);
|
||||
/// ShutdownGuard::new(move || { d2.fetch_add(1, Ordering::SeqCst); }).finish();
|
||||
/// assert_eq!(done.load(Ordering::SeqCst), 2);
|
||||
/// ```
|
||||
pub struct ShutdownGuard {
|
||||
inner: Arc<Mutex<Option<Box<dyn FnOnce() + Send>>>>,
|
||||
}
|
||||
|
||||
@@ -0,0 +1,160 @@
|
||||
//! Race-safety stress tests — proof that the high-level primitives are safe
|
||||
//! under real contention.
|
||||
//!
|
||||
//! Every test spawns many tasks hammering the same shared state and asserts
|
||||
//! exact invariants (no lost permits, no double-consume, exactly-once
|
||||
//! callbacks). A race would make these flaky or failing.
|
||||
|
||||
use std::sync::atomic::{AtomicUsize, Ordering};
|
||||
use std::sync::Arc;
|
||||
|
||||
use mytheclipse::aggregate_error::AggregateError;
|
||||
use mytheclipse::concurrency::ConcurrencyLimiter;
|
||||
use mytheclipse::parallel_map::{parallel_for_each, parallel_map};
|
||||
use mytheclipse::pool::{Pool, SemaphorePool};
|
||||
use mytheclipse::ratelimit::RateLimiter;
|
||||
use mytheclipse::shutdown_guard::ShutdownGuard;
|
||||
|
||||
const TASKS: usize = 64;
|
||||
const PER_TASK: usize = 1000;
|
||||
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 8)]
|
||||
async fn token_bucket_no_double_consume_under_contention() {
|
||||
let bucket = Arc::new(RateLimiter::new(1_000_000.0, 10_000_000));
|
||||
|
||||
let mut handles = Vec::new();
|
||||
for _ in 0..TASKS {
|
||||
let b = Arc::clone(&bucket);
|
||||
handles.push(tokio::spawn(async move {
|
||||
for _ in 0..PER_TASK {
|
||||
assert!(b.try_acquire().is_ok(), "consume denied unexpectedly");
|
||||
}
|
||||
}));
|
||||
}
|
||||
for h in handles {
|
||||
h.await.unwrap();
|
||||
}
|
||||
// The token bucket refills over time, so exact equality is wrong.
|
||||
// Correct invariants: every consume succeeded (proven above) and the
|
||||
// available count only drifted by refill — it must be >= capacity-64k
|
||||
// (no double-spend) and <= capacity (never minted tokens).
|
||||
let avail = bucket.available_tokens();
|
||||
assert!(
|
||||
avail >= 10_000_000 - (TASKS * PER_TASK) as u64,
|
||||
"tokens vanished: {avail}"
|
||||
);
|
||||
assert!(avail <= 10_000_000, "tokens minted: {avail}");
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 8)]
|
||||
async fn semaphore_pool_no_permit_leak_under_contention() {
|
||||
let pool = Arc::new(SemaphorePool::new(vec![1u32, 2, 3, 4, 5]));
|
||||
|
||||
let mut handles = Vec::new();
|
||||
for _ in 0..TASKS {
|
||||
let p = Arc::clone(&pool);
|
||||
handles.push(tokio::spawn(async move {
|
||||
for _ in 0..PER_TASK {
|
||||
let item = p.acquire().await.unwrap();
|
||||
assert!(item.resource >= 1 && item.resource <= 5);
|
||||
drop(item); // release
|
||||
}
|
||||
}));
|
||||
}
|
||||
for h in handles {
|
||||
h.await.unwrap();
|
||||
}
|
||||
let guard = pool.items();
|
||||
assert_eq!(guard.len(), 5, "permits leaked under contention");
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 8)]
|
||||
async fn parallel_map_10k_input_ordered_under_contention() {
|
||||
let items: Vec<u32> = (0..10_000).collect();
|
||||
let doubled = parallel_map(items, 32, |x| async move { Ok::<_, std::io::Error>(x * 2) })
|
||||
.await
|
||||
.unwrap();
|
||||
assert_eq!(doubled.len(), 10_000);
|
||||
for (i, v) in doubled.iter().enumerate() {
|
||||
assert_eq!(*v, (i as u32) * 2, "parallel_map output order corrupted");
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 8)]
|
||||
async fn parallel_for_each_10k_all_side_effects_under_contention() {
|
||||
let count = Arc::new(AtomicUsize::new(0));
|
||||
let items: Vec<u32> = (0..10_000).collect();
|
||||
|
||||
let c = Arc::clone(&count);
|
||||
parallel_for_each(items, 32, move |x| {
|
||||
let c = Arc::clone(&c);
|
||||
async move {
|
||||
c.fetch_add(1, Ordering::SeqCst);
|
||||
assert!(x < 10_000);
|
||||
Ok::<_, std::io::Error>(())
|
||||
}
|
||||
})
|
||||
.await
|
||||
.unwrap();
|
||||
|
||||
assert_eq!(count.load(Ordering::SeqCst), 10_000, "side effects lost");
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 8)]
|
||||
async fn aggregate_error_collects_all_errors_under_contention() {
|
||||
// 100 fns, every 3rd fails (0,3,...,99 = 34 errors): all errors collected.
|
||||
let results: Vec<Result<u32, std::io::Error>> = (0..100)
|
||||
.map(|i| {
|
||||
if i % 3 == 0 {
|
||||
Err(std::io::Error::other(format!("fail {i}")))
|
||||
} else {
|
||||
Ok(i)
|
||||
}
|
||||
})
|
||||
.collect();
|
||||
|
||||
let err = AggregateError::from_results(results).err().expect("expected error");
|
||||
assert_eq!(err.len(), 34, "expected 34 errors (0..99 every 3rd)");
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 8)]
|
||||
async fn shutdown_guard_exactly_once_under_contention() {
|
||||
let fired = Arc::new(AtomicUsize::new(0));
|
||||
let mut guards = Vec::new();
|
||||
for _ in 0..TASKS {
|
||||
let f = Arc::clone(&fired);
|
||||
guards.push(ShutdownGuard::new(move || {
|
||||
f.fetch_add(1, Ordering::SeqCst);
|
||||
}));
|
||||
}
|
||||
drop(guards);
|
||||
assert_eq!(fired.load(Ordering::SeqCst), TASKS, "guards double-fired");
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 8)]
|
||||
async fn concurrency_limiter_max_inflight_never_exceeded() {
|
||||
let limiter = Arc::new(ConcurrencyLimiter::new(8));
|
||||
let inflight = Arc::new(AtomicUsize::new(0));
|
||||
let peak = Arc::new(AtomicUsize::new(0));
|
||||
|
||||
let mut handles = Vec::new();
|
||||
for _ in 0..TASKS {
|
||||
let l = Arc::clone(&limiter);
|
||||
let in_f = Arc::clone(&inflight);
|
||||
let pk = Arc::clone(&peak);
|
||||
handles.push(tokio::spawn(async move {
|
||||
for _ in 0..PER_TASK {
|
||||
let _guard = l.acquire();
|
||||
let now = in_f.fetch_add(1, Ordering::SeqCst) + 1;
|
||||
pk.fetch_max(now, Ordering::SeqCst);
|
||||
std::thread::yield_now(); // force preemption windows
|
||||
in_f.fetch_sub(1, Ordering::SeqCst);
|
||||
}
|
||||
}));
|
||||
}
|
||||
for h in handles {
|
||||
h.await.unwrap();
|
||||
}
|
||||
assert!(peak.load(Ordering::SeqCst) <= 8, "limiter let >8 inflight");
|
||||
assert_eq!(inflight.load(Ordering::SeqCst), 0, "limiter leaked permits");
|
||||
}
|
||||
Reference in New Issue
Block a user