Skip to content

Conversation

@unbalancedparentheses
Copy link
Contributor

Summary

Add Erlang-style application module for packaging and managing supervision trees as units.

Features

  • Application trait for defining applications with:
    • start() - create and start supervision tree
    • prep_stop() - cleanup hook before stopping
    • stopped() - hook after termination
  • Global registry of running applications
  • Functions:
    • start::<A>(config) - start an application
    • stop::<A>() - stop an application
    • is_running::<A>() - check if running
    • whereis::<A>() - get root supervisor PID
    • which_applications() - list all running apps
    • call::<A>(msg) - send message to supervisor
    • get_handle::<A>() - get supervisor handle

Usage

struct MyApp;

impl Application for MyApp {
    type Config = i32;

    fn name() -> &'static str { "my_app" }

    fn start(config: Self::Config) -> Result<GenServerHandle<Supervisor>, ApplicationError> {
        let spec = SupervisorSpec::new(RestartStrategy::OneForOne)
            .child(ChildSpec::worker("counter", move || {
                Counter::new(config).start(Backend::Async)
            }));
        Ok(Supervisor::start(spec))
    }
}

// Start the application
let pid = application::start::<MyApp>(42)?;

// Check status
assert!(application::is_running::<MyApp>());

// Stop the application
application::stop::<MyApp>().await?;

Test plan

  • All 164 tests pass
  • Clippy clean
  • New application tests for start/stop, multiple apps, call, get_handle

🤖 Generated with Claude Code

unbalancedparentheses and others added 19 commits January 8, 2026 16:18
Consolidate the two separate GenServer implementations (async/tokio and
threads) into a single implementation with a Backend enum parameter.
Breaking change: start() now requires a Backend argument:
- Backend::Async - tokio async tasks (default)
- Backend::Blocking - tokio's blocking thread pool
- Backend::Thread - dedicated OS thread
This provides runtime flexibility without code duplication, allowing
users to mix different execution backends in the same application.
- Add Backend enum to gen_server.rs
- Change start() signature to accept Backend parameter
- Update all examples and tests
- Remove thread-based example crates
Add 10 new tests covering:
- Backend enum traits (Default, Copy, Clone, Debug, PartialEq, Eq)
- All three backends handle call/cast correctly
- Backend::Thread isolates blocking work from async runtime
- Multiple backends can run concurrently with independent state
- Backend::default() works in start()
Document each backend option with:
- Comparison table showing execution model, best use cases, and limitations
- Code examples for each backend
- Detailed "When to Use" guide with advantages and avoid-when advice
- Per-variant documentation with specific use cases
Property-based tests (proptest):
- Counter preserves initial state
- N increments result in initial + N
- Get is idempotent (multiple calls return same value)
- All backends produce working GenServers
- Multiple GenServers maintain independent state
- Cast followed by Get reflects the cast
Fuzzing (cargo-fuzz):
- Add fuzz target for GenServer operations
- Test random sequences of call/cast operations
- Verify state consistency across all backends
- Run with: cd concurrency/fuzz && cargo fuzz run fuzz_genserver_operations
… communication

- Backend equivalence tests: verify all backends produce identical results
- Cross-backend communication: test GenServers on different backends calling each other
- Stress tests: concurrent operations, mixed call/cast
- Init/teardown: verify lifecycle hooks work on all backends
- State consistency: large operations, alternating operations
- Remove concurrency/src/threads/ directory (replaced by Backend enum)
- Move files from concurrency/src/tasks/ to concurrency/src/
- Update all imports from spawned_concurrency::tasks:: to spawned_concurrency::
- Update internal crate imports accordingly
- Update examples README to reflect current architecture

The Backend enum (Async, Blocking, Thread) now provides all the
functionality previously split between tasks and threads modules,
offering a cleaner and more unified API.
- Add Pid struct with unique process identifiers (AtomicU64)
- Add HasPid trait for types that have a process ID
- Add ExitReason enum (Normal, Shutdown, Error, Killed)
- Add MonitorRef for tracking monitors
- Add SystemMessage enum (Down, Exit, Timeout)

These are the foundational types for OTP-style process management.
- Add ProcessTable with global process tracking
- Implement bidirectional linking (link/unlink)
- Implement unidirectional monitoring (monitor/demonitor)
- Add trap_exit support for catching linked process exits
- Add SystemMessageSender trait for delivering DOWN/EXIT messages
- Handle exit propagation to linked processes

The process table is the central registry for all running processes
and manages the relationships between them.
- Add global Registry for name -> Pid mapping
- Implement register/unregister functions
- Add whereis for name lookup
- Add name_of for reverse lookup (Pid -> name)
- Prevent duplicate names and multiple names per process
- Add comprehensive tests with mutex for isolation

Enables Erlang-style named processes for easier discovery.
Integrate the Pid, link, monitor, and registry functionality into the
tasks-based GenServer:

- Add Pid field to GenServerHandle for process identification
- Implement HasPid trait for GenServerHandle
- Add system message handling via handle_info callback
- Add link/unlink methods for bidirectional process linking
- Add monitor/demonitor methods for process monitoring
- Add trap_exit/is_trapping_exit for exit signal handling
- Add register/unregister/registered_name for process registry
- Add start_linked and start_monitored convenience methods
- Update lib.rs to export link, pid, process_table, registry modules
- Add comprehensive Pid and registry tests
Implements Erlang/OTP-style supervision for fault-tolerant systems:

Supervisor:
- Manages a static set of child processes defined at start
- Monitors children and restarts them according to restart strategy
- Supports restart strategies: OneForOne, OneForAll, RestForOne
- Child specs with: restart type, shutdown behavior, child type

DynamicSupervisor:
- Manages dynamically spawned children
- Supports start_child/terminate_child for runtime management
- Configurable max_children limit

Features:
- Automatic restart on child crash (permanent, temporary, transient)
- Max restart intensity to prevent restart loops
- Graceful shutdown with configurable timeout
- Type-safe child handle abstraction
- Full integration with GenServer Backend system
- Comprehensive test suite (unit + integration tests)
Add support for storing and retrieving typed GenServerHandle<G> by name:

- register_handle<G>(): stores both Pid and typed handle
- lookup<G>(): returns Option<GenServerHandle<G>> for direct messaging
- has_handle(): checks if name has a typed handle stored

The existing register()/whereis() functions continue to work for
Pid-only registration. The typed registry enables name-based
messaging without keeping handle references:

    registry::register_handle("counter", handle)?;
    // Later, anywhere in the code:
    if let Some(h) = registry::lookup::<Counter>("counter") {
        h.call(Increment).await;
    }

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
Add `process_table::exit(from, to, reason)` - the Erlang equivalent of
`exit(Pid, Reason)`. The behavior follows Erlang semantics:

- Kill: Unconditionally terminates the process (untrappable)
- Normal to self: Process exits normally
- Normal to other: Ignored (can't force another to exit "normally")
- Other reasons: Kills process, or sends EXIT message if trapping

Also adds `exit_self(pid, reason)` convenience function for external
shutdown requests.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
The supervision intensity feature (max_restarts within max_seconds) was
already implemented. This adds comprehensive tests to verify:

- Supervisor stops restarting after max_restarts exceeded
- Restart counter resets after max_seconds period passes
- DynamicSupervisorSpec properly accepts max_restarts config

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
Add process introspection capabilities similar to Erlang's process_info/1:

- ProcessInfo struct: Contains pid, alive status, trap_exit, links,
  monitored_by, monitoring, and registered_name
- process_info(pid): Get full info about a process
- all_processes(): List all registered PIDs
- process_count(): Count registered processes

This enables debugging and monitoring of the process system.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
Add a pg module for grouping processes together, similar to Erlang's pg:

- join(group, pid): Add process to a named group
- leave(group, pid): Remove process from a group
- leave_all(pid): Remove process from all groups (for cleanup)
- get_members(group): Get all PIDs in a group
- which_groups(pid): Get all groups a process belongs to
- is_member(group, pid): Check membership
- member_count(group): Count group members
- all_groups(): List all group names

Process groups enable pub/sub patterns and worker pool management.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
Add new showcase example demonstrating all features:
- GenServer with different Backends (Async, Blocking, Thread)
- Process registry (Pid and typed handle registration)
- Process linking and monitoring
- Process groups (pg)
- Supervisor and DynamicSupervisor
- Process introspection

Update bank example to demonstrate:
- Running same server with different backends
- Registry integration for named process lookup

Update examples README with feature coverage table.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
Add Erlang-style sys module with:
- Suspend/Resume: Pause and unpause message processing
- Statistics: Track message counts and processing times
- Tracing: Log all messages via the tracing crate

Key changes:
- New sys module with Statistics, TraceOptions structs
- GenServer automatically integrates with sys (suspend check, stats, tracing)
- Add Debug bounds to CallMsg, CastMsg, OutMsg for tracing support
- Cleanup sys state when process terminates

Usage:
```rust
sys::statistics(pid, true);  // Enable stats
sys::suspend(pid);           // Pause processing
sys::trace(pid, true);       // Enable message logging
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
Add Erlang-style application module for packaging supervision trees:
- Application trait for defining applications with start/stop lifecycle
- Global registry of running applications
- start/stop/is_running/whereis functions
- call() for sending messages to application supervisor
- get_handle() for direct supervisor access
- which_applications() to list all running apps

Usage:
```rust
struct MyApp;

impl Application for MyApp {
    type Config = i32;

    fn start(config: Self::Config) -> Result<GenServerHandle<Supervisor>, ApplicationError> {
        let spec = SupervisorSpec::new(RestartStrategy::OneForOne)
            .child(ChildSpec::worker("worker", || ...));
        Ok(Supervisor::start(spec))
    }
}

// Start/stop the application
application::start::<MyApp>(42)?;
application::stop::<MyApp>().await?;
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@unbalancedparentheses unbalancedparentheses changed the title feat: add Application behavior for managing supervision trees [14/21] feat: add Application behavior for managing supervision trees [14/24] Jan 9, 2026
@unbalancedparentheses unbalancedparentheses changed the title feat: add Application behavior for managing supervision trees [14/24] [14/24] feat: add Application behavior for managing supervision trees Jan 9, 2026
@unbalancedparentheses
Copy link
Contributor Author

Reorganizing PR sequence for coherent implementation order. This content will be included in the new PR series.

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