[11/12] feat: add process groups (pg) for pub/sub patterns #80

unbalancedparentheses · 2026-01-08T22:42:25Z

Summary

Adds a pg module for grouping processes together, similar to Erlang's pg module. This enables pub/sub patterns and worker pool management.

API

Function	Description
`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
`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

Example Usage

use spawned_concurrency::pg;

// Join groups
pg::join("workers", handle.pid())?;
pg::join("logging", handle.pid())?;

// Get all workers
let workers = pg::get_members("workers");
for pid in workers {
    // broadcast to each worker
}

// Check membership
if pg::is_member("workers", handle.pid()) {
    // ...
}

// Cleanup when process exits
pg::leave_all(handle.pid());

Test plan

PR Chain

PR #11 in the stacked PR chain, building on PR #10 (process info).

🤖 Generated with Claude Code

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]>

unbalancedparentheses · 2026-01-09T20:26:54Z

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

unbalancedparentheses added 5 commits January 8, 2026 16:18

unbalancedparentheses mentioned this pull request Jan 8, 2026

[12/12] feat: add comprehensive examples and improve existing ones #81

Closed

4 tasks

unbalancedparentheses and others added 11 commits January 8, 2026 19:55

unbalancedparentheses force-pushed the pr/11-process-groups branch from fa7f6b5 to 1ce7f7c Compare January 8, 2026 23:05

unbalancedparentheses closed this Jan 9, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[11/12] feat: add process groups (pg) for pub/sub patterns #80

[11/12] feat: add process groups (pg) for pub/sub patterns #80

Uh oh!

unbalancedparentheses commented Jan 8, 2026

Uh oh!

unbalancedparentheses commented Jan 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

[11/12] feat: add process groups (pg) for pub/sub patterns #80

[11/12] feat: add process groups (pg) for pub/sub patterns #80

Uh oh!

Conversation

unbalancedparentheses commented Jan 8, 2026

Summary

API

Example Usage

Test plan

PR Chain

Uh oh!

unbalancedparentheses commented Jan 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant