docs: document custom type support throughout project

Update all documentation to reflect that custom types work automatically
with the #[task] macro, requiring only Clone + Send + Sync + 'static.

Documentation updates:
- README: Add custom types to features, new Custom Types section
- CHANGELOG: Document custom type improvement in [Unreleased]
- src/lib.rs: Add custom types example to main API docs
- src/task.rs: Update Task trait docs to mention macro-generated extraction
- src/extract.rs: Clarify ExtractInput is now internal-only (for task_fn)
- dagx-macros: Update macro docs to emphasize automatic type handling

New example:
- examples/custom_types.rs: Simple 120-line example showing User type
  flowing through DAG with fan-out pattern (one output → two consumers)
  demonstrating Arc wrapping is automatic and transparent

This makes the custom type capability discoverable and prominent for users,
turning a previous limitation into a headline feature.
This commit is contained in:
swaits committed 2025-10-10 17:22:59 -06:00
1 parent 8ee4092f9a
commit 979232bd67
8 files changed
+366 -7

No files matched your search

+18 -5
View File
@@ -1,15 +1,28 @@
//! Input extraction for task dependencies via oneshot channels.
//!
//! This module handles extracting typed inputs from task dependencies via oneshot channels.
//! # Legacy Trait for Internal Use Only
//!
//! **NOTE**: This module is now primarily for internal use. The `ExtractInput` trait is only
//! used by the internal `task_fn` test helper function.
//!
//! **For regular tasks**: The `#[task]` macro generates inline `extract_and_run()` methods with
//! type-specific extraction logic. This means **ANY type** implementing `Clone + Send + Sync`
//! works automatically without needing `ExtractInput` implementations!
//!
//! # How it works
//!
//! When a task executes, it needs to extract its inputs from type-erased oneshot receivers.
//! Outputs are wrapped in Arc for efficient fanout (cheap Arc clones instead of data clones).
//! This module provides the ExtractInput trait with implementations for:
//! - `()` for tasks with no dependencies
//! - Common types (`i32`, `String`, etc.) for tasks with a single dependency
//! - `(A, B, ...)` tuples for tasks with multiple dependencies (awaited concurrently)
//!
//! **Modern approach (via `#[task]` macro)**:
//! - The macro generates custom extraction logic inline in `extract_and_run()`
//! - Works with ANY type (just needs `Clone + Send + Sync`)
//! - No trait implementations needed!
//!
//! **Legacy approach (via `ExtractInput` trait)**:
//! - Used only by the internal `task_fn` test helper
//! - Provides implementations for primitives, standard types, and tuples
//! - Requires explicit trait implementations for custom types (not recommended)
//!
//! # Why macros?
//!