Skip to content

docs: add API redesign plan for v0.5 #147

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

Closed
ElFantasma wants to merge 4 commits into from
Closed

docs: add API redesign plan for v0.5 #147

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
41e4b62
docs: add API redesign plan for v0.5
ElFantasma Feb 4, 2026
a39ce76
fix: use Receiver trait with Recipient alias for consistent naming
ElFantasma Feb 5, 2026
fa724c8
docs: use Actix-style object-safe Receiver trait in API plan
ElFantasma Feb 5, 2026
1ef33bf
docs: address PR review comments on Supervisable and Handler traits
ElFantasma Feb 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
docs: address PR review comments on Supervisable and Handler traits
  • Loading branch information
@ElFantasma
ElFantasma committed Feb 6, 2026
commit 1ef33bf0c463543dca379463c554ccc5914c86ff
12 changes: 9 additions & 3 deletions docs/API_REDESIGN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,14 +187,17 @@ pub enum ExitReason {
**New file:** `concurrency/src/traits.rs`

```rust
/// Trait for actors that can be supervised
/// Trait for actors that can be supervised.
/// Provides actor_id() for identity comparison with trait objects.
pub trait Supervisable: Send + Sync {
fn actor_id(&self) -> ActorId;
fn stop(&self);
fn is_alive(&self) -> bool;
fn on_exit(&self, callback: Box<dyn FnOnce(ExitReason) + Send>);
}

/// Trait for actors that can be linked
/// Trait for actors that can be linked.
/// Uses actor_id() (from Supervisable) to track links internally.
pub trait Linkable: Supervisable {
fn link(&self, other: &dyn Linkable);
fn unlink(&self, other: &dyn Linkable);
Comment on lines +202 to +203
Copy link
Contributor

@greptile-apps greptile-apps bot Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The link and unlink methods take &dyn Linkable, which requires identity comparison to track links. Consider documenting how actor identity/equality works with trait objects, or including an actor_id() method in the trait for proper tracking.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Prompt To Fix With AI 
This is a comment left during a code review.
Path: docs/API_REDESIGN.md
Line: 159:160

Comment:
The `link` and `unlink` methods take `&dyn Linkable`, which requires identity comparison to track links. Consider documenting how actor identity/equality works with trait objects, or including an `actor_id()` method in the trait for proper tracking.

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.

Copy link
Collaborator Author

@ElFantasma ElFantasma Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added actor_id() to Supervisable trait. Linkable::link/unlink use this for identity tracking internally.

Expand Down Expand Up @@ -240,7 +243,10 @@ pub trait Message: Send + 'static {
type Result: Send;
}

/// Handler for a specific message type
/// Handler for a specific message type.
/// Uses RPITIT (Rust 1.75+) — this is fine since Handler is never used as dyn.
/// &mut self is safe: actors process messages sequentially (one at a time),
/// so there is no concurrent access to self.
pub trait Handler<M: Message>: Actor {
fn handle(&mut self, msg: M, ctx: &Context<Self>) -> impl Future<Output = M::Result> + Send;
Copy link
Contributor

@greptile-apps greptile-apps bot Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Handler::handle signature uses RPITIT. Also note that using &mut self in async contexts may cause issues with concurrent message handling. Consider documenting that messages are processed sequentially per actor to clarify this design choice.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Prompt To Fix With AI 
This is a comment left during a code review.
Path: docs/API_REDESIGN.md
Line: 205:205

Comment:
The `Handler::handle` signature uses RPITIT. Also note that using `&mut self` in async contexts may cause issues with concurrent message handling. Consider documenting that messages are processed sequentially per actor to clarify this design choice.

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.

Copy link
Collaborator Author

@ElFantasma ElFantasma Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a doc comment clarifying: RPITIT is fine here since Handler is never used as dyn, and &mut self is safe because actors process messages sequentially (one at a time, no concurrent access).

}
Expand Down