sacp 10.0.0-alpha.1: ordering guarantees, docs reorganization, and compilable examples#100
Merged
Merged
Conversation
- Add new ordering module documenting dispatch loop behavior - Explain on_* callbacks block the loop for ordering guarantees - Document spawn and block_task patterns to avoid deadlocks - Improve proxy session documentation in session.rs
Consolidate response dispatch into the central dispatch loop. The incoming actor now directly manages the pending reply map and dispatches responses inline, rather than sending them through a separate actor. This simplifies the architecture and prepares for future ordering guarantees where response handling can block the dispatch loop.
When the dispatch loop sends a response to an awaiter, it now includes an optional ack channel. The dispatch loop waits for the ack before processing the next message, ensuring ordering guarantees. The ack timing differs by consumption method: - block_task(): acks immediately after receiving (spawned tasks don't need to block the dispatch loop) - on_receiving_result(): acks after the callback completes (ensures the callback runs before next message is processed) This enables true ordering guarantees for on_* callbacks - they now block further message processing until complete. ResponsePayload struct replaces the tuple for clarity, with documented fields for the result and optional ack_tx.
- Add 'Message Ordering and Concurrency' section to main lib.rs docs - Add '# Ordering' sections to all on_* methods referencing the ordering module - Update on_receiving_result docs to explain ack-after-callback behavior - Update on_session_start and on_proxy_session_start to block the dispatch loop (use on_receiving_result instead of spawn + block_task) All on_* methods now consistently block the dispatch loop until their callbacks complete, providing ordering guarantees.
- Slim down lib.rs documentation to focus on intro, quick start, and links - Create concepts module with progressive documentation: - acp_basics: clients, agents, proxies, conductors - connections: links and connection builders - sessions: multi-turn conversations - callbacks: on_receive_* methods - peers: explicit peer variants (_to, _from) - ordering: dispatch loop and ordering guarantees (moved from ordering.rs) - proxies: proxy chains and conductors - Update doc links from crate::ordering to crate::concepts::ordering - Delete standalone ordering.rs (now in concepts/)
- Fix MatchMessage links in jsonrpc.rs - Fix DynamicHandlerRegistration reference (was private) - Fix Self::connection_cx reference (method didn't exist) - Fix McpServerConnect links in mcp_server module - Fix SessionBuilder::with_mcp_server and JrConnectionBuilder links - Fix McpServerBuilder::tool_fn links in lib.rs macros
Convert 33 doc examples from ```ignore to compilable ``` blocks using sacp-test support types. Remaining 14 ignore blocks are: - Deadlock demonstration examples in ordering.rs (intentional) - Complex schema types in cookbook.rs (RequestPermission, etc.) - Derive macro examples in jsonrpc.rs (require proc-macro) - External crate examples (sacp-conductor) All 71 doc tests now pass.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR prepares sacp for 10.0.0-alpha.1 with improvements to ordering guarantees, documentation organization, and doc test coverage.
Changes
Features & Refactoring
on_receiving_resultcallbacks block the dispatch loop properly before the next message is processedDocumentation
acp_basics,connections,sessions,callbacks,peers,ordering,proxies,error_handlingon_*methods (on_session_start,on_proxy_session_start, etc.)Remaining
ignoreblocks (14 total, intentional)