Skip to content

[23/24] refactor: simplify codebase following suckless principles #91

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
unbalancedparentheses wants to merge 14 commits into from
Closed

[23/24] refactor: simplify codebase following suckless principles #91

unbalancedparentheses wants to merge 14 commits into from

Conversation

@unbalancedparentheses
Copy link
Contributor

@unbalancedparentheses unbalancedparentheses commented Jan 9, 2026 •
edited
Loading

Note: This PR depends on #90 ([22/24] docs) and should be merged after it.

Summary

  • Remove unnecessary abstractions and reduce API surface
  • Move tests to separate files for cleaner implementation files
  • Follow suckless and OpenBSD principles: simple, minimal, easy to understand

Changes

Removed Unnecessary Abstractions

  • Remove CallResponse::Unused and CastResponse::Unused: Default implementations now panic with clear message instead of returning confusing "Unused" variants
  • Remove ChildPidWrapper: Added impl HasPid for Pid instead, eliminating wrapper indirection
  • Delete messages.rs module: Use () instead of Unused type throughout

Reduced API Surface

  • Reduce lib.rs exports: Move 8 supervisor internal types (SupervisorCall, SupervisorCast, SupervisorResponse, DynamicSupervisorCall, DynamicSupervisorCast, DynamicSupervisorResponse, SupervisorCounts, ChildInfo) to supervisor:: namespace

Separated Tests from Implementation

  • Move gen_server tests to gen_server_tests.rs (1431 lines)
  • Move supervisor tests to supervisor_tests.rs (768 lines)

Backend Initialization (from previous commit)

  • Extracted common initialization code into GenServerInit struct
  • Added run_and_cleanup() helper method shared by all three backends

Implementation File Size Reductions

File Before After Change
gen_server.rs 2,245 lines 808 lines -64%
supervisor.rs 2,111 lines 1,389 lines -34%
messages.rs 2 lines deleted -100%

Test plan

  • All 109 tests pass
  • cargo check passes
  • Examples compile and work

🤖 Generated with Claude Code

unbalancedparentheses and others added 12 commits January 8, 2026 16:18
@unbalancedparentheses
feat: unify GenServer with Backend enum for runtime selection
ce09417 
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
@unbalancedparentheses
test: add comprehensive tests for Backend enum
34b0ae3 
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()
@unbalancedparentheses
docs: add comprehensive Backend enum documentation
27ed72e 
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
@unbalancedparentheses
test: add property-based testing and fuzzing for GenServer
143d5f3 
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
@unbalancedparentheses
test: add integration tests for backend equivalence and cross-backend…
e57754e 
… 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
@unbalancedparentheses
refactor: flatten module structure, remove threads directory
5c08565 
- 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.
@unbalancedparentheses
feat: add Pid and process linking primitives
eb45d5c 
- 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.
@unbalancedparentheses
feat: add global process table for link/monitor management
3270156 
- 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.
@unbalancedparentheses
feat: add process registry for name-based lookup
5e831f2 
- 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.
@unbalancedparentheses
feat: add link/monitor/registry integration to tasks GenServer
bbb6aa8 
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
@unbalancedparentheses
feat: add Supervisor and DynamicSupervisor
10d4a45 
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)
@unbalancedparentheses @claude
docs: add comprehensive crate and module documentation [21/24]
d6457e9 
Add documentation to improve crate usability:

- Crate-level documentation in lib.rs with:
  - Overview of main types (GenServer, Supervisor, Process)
  - Core concepts (Pid, links, monitors, registry)
  - Quick start examples for GenServer and Supervision
  - Backend documentation

- Process module documentation with:
  - Overview of Process trait
  - Example Echo process implementation

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

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@unbalancedparentheses unbalancedparentheses changed the title [23/24] refactor: simplify GenServer backend initialization [23/24] refactor: simplify codebase following suckless principles Jan 9, 2026
unbalancedparentheses and others added 2 commits January 9, 2026 15:51
@unbalancedparentheses @claude
refactor: simplify GenServer backend initialization and fix test race…
b779010 
… condition

- Extract common initialization code into GenServerInit struct
- Add run_and_cleanup() helper method to reduce duplication across backends
- Fix registry test race condition by using unique PID-based names

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

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@unbalancedparentheses @claude
refactor: simplify codebase following suckless principles
7d7557e 
- Remove CallResponse::Unused and CastResponse::Unused variants
  Default implementations now panic with clear message
- Remove ChildPidWrapper, add impl HasPid for Pid instead
- Delete messages.rs module, use () instead of Unused type
- Reduce lib.rs exports, move supervisor internals to supervisor:: namespace
- Move gen_server tests to gen_server_tests.rs (1431 lines)
- Move supervisor tests to supervisor_tests.rs (768 lines)

Implementation file reductions:
- gen_server.rs: 2245 → 808 lines (-64%)
- supervisor.rs: 2111 → 1389 lines (-34%)

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

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@unbalancedparentheses
Copy link
Contributor Author

unbalancedparentheses commented Jan 9, 2026

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

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@unbalancedparentheses