diff --git a/docs/coding-guidelines.md b/docs/coding-guidelines.md index 70a1ef53009..935e26f6854 100644 --- a/docs/coding-guidelines.md +++ b/docs/coding-guidelines.md @@ -19,6 +19,7 @@ - [Further Reading](#further-reading) - [Use iteration not recursion](#use-iteration-not-recursion) - [Further Reading](#further-reading-1) + - [Allow Correlating Asynchronous Responses to Their Requests](#allow-correlating-asynchronous-responses-to-their-requests) @@ -299,3 +300,26 @@ stack potentially unboundedly. Instead use iteration e.g. via `loop` or `for`. - https://en.wikipedia.org/wiki/Tail_call - https://stackoverflow.com/questions/65948553/why-is-recursion-not-suggested-in-rust - https://stackoverflow.com/questions/59257543/when-is-tail-recursion-guaranteed-in-rust + +## Allow Correlating Asynchronous Responses to Their Requests + +In an asynchronous context, it is important to enable users to determine the correlation between a +response and a previous request. For example, if a user requests two new connections to the same +peer, they should be able to match each new connection to the corresponding previous connection +request without having to guess. + +When accepting a **command** that eventually results in a response through an event require that +command to contain a unique ID, which is later on contained in the asynchronous response event. One +such example is the `Swarm` accepting a `NetworkBehaviourAction::Dial` from the `NetworkBehaviour`. + +``` rust +struct Command { + id: Id, + // ... +} + +struct Response { + command_id: Id, + // ... +} +```