Skip to content

docs: add multi-module guides, benchmarks, and CI benchmark workflow#45

Merged
deepjoy merged 4 commits into
mainfrom
docs-updates
Mar 18, 2026
Merged

docs: add multi-module guides, benchmarks, and CI benchmark workflow#45
deepjoy merged 4 commits into
mainfrom
docs-updates

Conversation

@deepjoy
Copy link
Copy Markdown
Owner

@deepjoy deepjoy commented Mar 18, 2026

Summary

  • Add benchmark suites for retry, dependencies, tags, groups, and history
    (complementing the existing scheduler benchmarks)
  • Add CI workflow that tracks benchmark performance over time on a
    _benchmarks branch and posts critcmp comparison comments on PRs
  • Add multi-module and library-modules documentation guides; expand
    quick-start, query-apis, priorities, and design docs
  • Format bench files consistently

Changes

Benchmarks

  • benches/retry.rs — backoff strategies, permanent failure, dead-letter paths
  • benches/dependencies.rs — linear chains, fan-in dispatch at varying depths
  • benches/tags.rs — submit-with-tags, query/count/scan by tags at scale
  • benches/groups.rs — per-group concurrency gates, group scaling
  • benches/history.rs — paginated history, aggregate stats, filter-by-type

CI

  • .github/workflows/benchmarks.yml — runs on push to main (stores
    baseline via benchmark-action/github-action-benchmark + caches critcmp
    export) and on PRs (restores baseline, compares with critcmp, posts or
    updates a PR comment with the diff)

Docs

  • docs/multi-module-apps.md — guide for multi-module scheduler patterns
  • docs/library-modules.md — reference for per-module API surface
  • Updates to quick-start, query-apis, priorities, design, glossary,
    io-and-backpressure, persistence-and-recovery, migrating-to-0.4

deepjoy added 4 commits March 18, 2026 03:26
Adds five new Criterion benchmark suites to cover gaps identified in the
existing happy-path-only bench suite:

- benches/retry.rs     — backoff delay computation (all 4 strategies) plus
                         E2E permanent-failure and retryable dead-letter paths
- benches/dependencies.rs — chain submission cost, sequential dispatch critical
                         path, and fan-in blocked→pending transition
- benches/tags.rs      — submission overhead by tag count, tasks_by_tags /
                         count_by_tags / tag_values queries at varying depths
- benches/groups.rs    — gate-check overhead baseline, single-group lookup,
                         and group-map scaling (1–100 groups)
- benches/history.rs   — paginated history query, aggregate stats, and
                         filter-by-type at 100/1000/5000 history rows

All E2E benches use iter_custom where setup must be isolated from the
measured portion. History and tag query benches pre-populate the store
once per sample before starting the timer.
Add two new guides (multi-module-apps.md, library-modules.md) and update
existing docs to address gaps in cross-module documentation: qualified
task type names, cross-module dependencies, module pause/resume,
scheduler.modules()/active_tasks(), cancel_all() semantics,
DuplicateStrategy scoping, module concurrency gating, and new glossary
terms. Improve panic messages on Scheduler::module() and ctx.module().
Runs Criterion benchmarks on push to main (stores baseline on
_benchmarks branch for timeline tracking) and on PRs (compares
against cached baseline via critcmp, posts results as PR comment).
@deepjoy deepjoy enabled auto-merge (squash) March 18, 2026 10:40
@deepjoy deepjoy merged commit 18de1cb into main Mar 18, 2026
2 checks passed
@github-actions github-actions Bot mentioned this pull request Mar 18, 2026
deepjoy pushed a commit that referenced this pull request Mar 18, 2026
## 🤖 New release

* `taskmill`: 0.4.0 -> 0.5.0 (⚠ API breaking changes)

### ⚠ `taskmill` breaking changes

```text
--- failure inherent_method_missing: pub method removed or renamed ---

Description:
A publicly-visible method or associated fn is no longer available under its prior name. It may have been renamed or removed entirely.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.46.0/src/lints/inherent_method_missing.ron

Failed in:
  TaskContext::current_module, previously in file /tmp/.tmpIFcAXT/taskmill/src/registry/context.rs:196
  TaskContext::module, previously in file /tmp/.tmpIFcAXT/taskmill/src/registry/context.rs:211
  TaskContext::try_module, previously in file /tmp/.tmpIFcAXT/taskmill/src/registry/context.rs:218
  TaskContext::current_module, previously in file /tmp/.tmpIFcAXT/taskmill/src/registry/context.rs:196
  TaskContext::module, previously in file /tmp/.tmpIFcAXT/taskmill/src/registry/context.rs:211
  TaskContext::try_module, previously in file /tmp/.tmpIFcAXT/taskmill/src/registry/context.rs:218
  SchedulerBuilder::module, previously in file /tmp/.tmpIFcAXT/taskmill/src/scheduler/builder.rs:102
  SchedulerBuilder::module, previously in file /tmp/.tmpIFcAXT/taskmill/src/scheduler/builder.rs:102
  Scheduler::module, previously in file /tmp/.tmpIFcAXT/taskmill/src/scheduler/mod.rs:270
  Scheduler::try_module, previously in file /tmp/.tmpIFcAXT/taskmill/src/scheduler/mod.rs:276
  Scheduler::modules, previously in file /tmp/.tmpIFcAXT/taskmill/src/scheduler/mod.rs:286
  Scheduler::module, previously in file /tmp/.tmpIFcAXT/taskmill/src/scheduler/mod.rs:270
  Scheduler::try_module, previously in file /tmp/.tmpIFcAXT/taskmill/src/scheduler/mod.rs:276
  Scheduler::modules, previously in file /tmp/.tmpIFcAXT/taskmill/src/scheduler/mod.rs:286

--- failure module_missing: pub module removed or renamed ---

Description:
A publicly-visible module cannot be imported by its prior path. A `pub use` may have been removed, or the module may have been renamed, removed, or made non-public.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.46.0/src/lints/module_missing.ron

Failed in:
  mod taskmill::module, previously in file /tmp/.tmpIFcAXT/taskmill/src/module.rs:1

--- failure struct_missing: pub struct removed or renamed ---

Description:
A publicly-visible struct cannot be imported by its prior path. A `pub use` may have been removed, or the struct itself may have been renamed or removed entirely.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#item-remove
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.46.0/src/lints/struct_missing.ron

Failed in:
  struct taskmill::module::ModuleHandle, previously in file /tmp/.tmpIFcAXT/taskmill/src/module.rs:396
  struct taskmill::ModuleHandle, previously in file /tmp/.tmpIFcAXT/taskmill/src/module.rs:396
  struct taskmill::module::ModuleReceiver, previously in file /tmp/.tmpIFcAXT/taskmill/src/module.rs:336
  struct taskmill::ModuleReceiver, previously in file /tmp/.tmpIFcAXT/taskmill/src/module.rs:336
  struct taskmill::module::ModuleSnapshot, previously in file /tmp/.tmpIFcAXT/taskmill/src/module.rs:313
  struct taskmill::ModuleSnapshot, previously in file /tmp/.tmpIFcAXT/taskmill/src/module.rs:313
  struct taskmill::module::ModuleEntry, previously in file /tmp/.tmpIFcAXT/taskmill/src/module.rs:264
  struct taskmill::SubmitBuilder, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/submit_builder.rs:81
  struct taskmill::module::Module, previously in file /tmp/.tmpIFcAXT/taskmill/src/module.rs:79
  struct taskmill::Module, previously in file /tmp/.tmpIFcAXT/taskmill/src/module.rs:79
  struct taskmill::module::ExecutorOptions, previously in file /tmp/.tmpIFcAXT/taskmill/src/module.rs:28
  struct taskmill::module::ModuleRegistry, previously in file /tmp/.tmpIFcAXT/taskmill/src/module.rs:282
  struct taskmill::ModuleRegistry, previously in file /tmp/.tmpIFcAXT/taskmill/src/module.rs:282
  struct taskmill::ModuleSubmitDefaults, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/submit_builder.rs:42

--- failure trait_associated_type_added: non-sealed public trait added associated type without default value ---

Description:
A non-sealed trait has gained an associated type without a default value, which breaks downstream implementations of the trait
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#trait-new-item-no-default
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.46.0/src/lints/trait_associated_type_added.ron

Failed in:
  trait associated type taskmill::task::typed::TypedTask::Domain in file /tmp/.tmpUI6vfZ/taskmill/src/task/typed.rs:58
  trait associated type taskmill::task::TypedTask::Domain in file /tmp/.tmpUI6vfZ/taskmill/src/task/typed.rs:58
  trait associated type taskmill::TypedTask::Domain in file /tmp/.tmpUI6vfZ/taskmill/src/task/typed.rs:58

--- failure trait_method_missing: pub trait method removed or renamed ---

Description:
A trait method is no longer callable, and may have been renamed or removed entirely.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#major-any-change-to-trait-item-signatures
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.46.0/src/lints/trait_method_missing.ron

Failed in:
  method expected_io of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:47
  method priority of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:52
  method group_key of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:67
  method on_duplicate of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:72
  method ttl of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:77
  method ttl_from of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:82
  method run_after of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:87
  method recurring of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:92
  method expected_io of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:47
  method priority of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:52
  method group_key of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:67
  method on_duplicate of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:72
  method ttl of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:77
  method ttl_from of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:82
  method run_after of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:87
  method recurring of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:92
  method expected_io of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:47
  method priority of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:52
  method group_key of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:67
  method on_duplicate of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:72
  method ttl of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:77
  method ttl_from of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:82
  method run_after of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:87
  method recurring of trait TypedTask, previously in file /tmp/.tmpIFcAXT/taskmill/src/task/typed.rs:92
```

<details><summary><i><b>Changelog</b></i></summary><p>

<blockquote>

## [0.5.0](v0.4.0...v0.5.0)
- 2026-03-18

### Added

- [**breaking**] domain-centric API with typed event streams
([#48](#48))

### Fixed

- *(ci)* capture benchmark output from stderr in workflow
([#47](#47))

### Other

- add multi-module guides, benchmarks, and CI benchmark workflow
([#45](#45))
</blockquote>


</p></details>

---
This PR was generated with
[release-plz](https://github.com/release-plz/release-plz/).

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant