Document the protocols and state machines - #77
Merged
Merged
Conversation
Every message, frame and status code now has one page saying who sends it, what answers it and which files must change together, and every long-lived process and thread has its states, triggers and timers written down next to the invariants a change must keep.
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.
Until now the message shapes lived in the code and in the memory of whoever wrote them; a reader tracing a hang had to reassemble the frame formats from three C files, two Erlang modules and the child. The protocols page puts every boundary in one place, from the caller's message to the byte layout on the pipe and the socket, with the response body rule the three writers and two parsers share and a checklist of what to touch when adding a request, a control or an event. The state machines page does the same for behaviour over time: the runtime, the embedded context thread and its process, a request's refcount, the isolated gen_statem with what each state dispatches, postpones or refuses, the child's execution stack, and the invariants underneath. Both are linked from the architecture page and listed under Internals in ex_doc.