Skip to content

Document actor state consolidation #134

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

Merged
leynos merged 3 commits into from
Jun 26, 2025
Merged

Document actor state consolidation #134

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
62155c3
Document actor state consolidation
leynos Jun 25, 2025
23abd59
Refine actor state section
leynos Jun 26, 2025
b069e8d
Merge branch 'main' into codex/propose-design-for-improved-state-mana…
leynos Jun 26, 2025
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
26 changes: 26 additions & 0 deletions docs/asynchronous-outbound-messaging-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,32 @@ sequenceDiagram
Note over Outbox: Holds frames while the socket is busy.
```

### 3.4 Actor state management

The connection actor polls four sources: a shutdown token, high- and
low-priority push channels, and an optional response stream. Earlier drafts
tracked a boolean for each source, leading to verbose state updates. The actor
now stores each receiver as an `Option` and counts how many sources have closed.

Comment on lines +183 to +187
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Jun 26, 2025

Choose a reason for hiding this comment

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

🧹 Nitpick (assertive)

Wrap paragraph to 80 cols for guideline compliance

The two sentences currently exceed the mandated 80-character wrap for prose in
Markdown docs. Re-flowing keeps the style consistent with the rest of the
document.

🤖 Prompt for AI Agents 
In docs/asynchronous-outbound-messaging-design.md around lines 183 to 187, the
paragraph exceeds the 80-character line length guideline for Markdown prose.
Reformat the paragraph by wrapping the text so that no line exceeds 80
characters, ensuring consistent style with the rest of the document.

```rust
enum RunState {
Active,
ShuttingDown,
Finished,
}

struct ActorState {
run_state: RunState,
closed_sources: usize,
total_sources: usize,
}
```

`total_sources` is calculated when the actor starts. Whenever a receiver returns
`None`, it is set to `None` and `closed_sources` increments. When
`closed_sources == total_sources` the loop exits. This consolidation clarifies
progress through the actor lifecycle and reduces manual flag management.
Comment on lines +202 to +205
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Jun 26, 2025

Choose a reason for hiding this comment

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

🧹 Nitpick (assertive)

Missing comma after the dependent ‘When…’ clause

Add a comma after the introductory clause to avoid a garden-path read and satisfy
standard punctuation rules.

-When `closed_sources == total_sources` the loop exits.
+When `closed_sources == total_sources`, the loop exits.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
`total_sources` is calculated when the actor starts. Whenever a receiver returns
`None`, it is set to `None` and `closed_sources` increments. When
`closed_sources == total_sources` the loop exits. This consolidation clarifies
progress through the actor lifecycle and reduces manual flag management.
`total_sources` is calculated when the actor starts. Whenever a receiver returns
`None`, it is set to `None` and `closed_sources` increments. When
`closed_sources == total_sources`, the loop exits. This consolidation clarifies
progress through the actor lifecycle and reduces manual flag management.
🧰 Tools
🪛 LanguageTool

[typographical] ~204-~204: The word ‘When’ starts a question. Add a question mark (“?”) at the end of the sentence.
Context: ...sources == total_sources` the loop exits. This consolidation clarifies progress t...

(WRB_QUESTION_MARK)

🤖 Prompt for AI Agents 
In docs/asynchronous-outbound-messaging-design.md around lines 202 to 205, add a
comma after the introductory clause "Whenever a receiver returns `None`" to
correctly separate it from the main clause and improve readability by following
standard punctuation rules.


## 4. Public API Surface

The public API is designed for ergonomics, safety, and extensibility.
Expand Down
5 changes: 4 additions & 1 deletion docs/asynchronous-outbound-messaging-roadmap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,9 @@ design documents.
- [x] **Connection actor** with a biased `select!` loop that polls for shutdown,
high/low queues and response streams as described in
[Design §3.2][design-write-loop].
- [x] **Internal protocol hooks** `before_send` and `on_command_end` invoked
- [ ] **Run state consolidation** using `Option` receivers and a closed source
counter ([Design §3.4][design-actor-state]).
Comment on lines +16 to +17
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Jun 26, 2025

Choose a reason for hiding this comment

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

🧹 Nitpick (assertive)

Hyphenate compound modifier ‘closed-source’

Treat “closed-source” as a compound adjective to mirror the earlier “high- and
low-priority” fix and avoid a garden-path read.

-counter ([Design §3.4][design-actor-state]).
+counter ([Design §3.4][design-actor-state]).

(Only the hyphenation changes; line length preserved.)

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents 
In docs/asynchronous-outbound-messaging-roadmap.md around lines 16 to 17, the
phrase "closed source counter" should be hyphenated as "closed-source counter"
to correctly treat it as a compound adjective. Update the text to include the
hyphen between "closed" and "source" without changing the line length.

- [X] **Internal protocol hooks** `before_send` and `on_command_end` invoked
from the actor ([Design §4.3][design-hooks]).

## 2. Public API and Ergonomics
Expand Down Expand Up @@ -52,6 +54,7 @@ design documents.
- [ ] **User guides and examples** demonstrating server-initiated messaging
([Design §7][design-use-cases]).

[design-actor-state]: asynchronous-outbound-messaging-design.md#34-actor-state-management
[design-dlq]: asynchronous-outbound-messaging-design.md#52-optional-dead-letter-queue-dlq-for-critical-messages
[design-errors]: asynchronous-outbound-messaging-design.md#5-error-handling--resilience
[design-hooks]: asynchronous-outbound-messaging-design.md#43-configuration-via-the-wireframeprotocol-trait
Expand Down