From b39770b8e9bfb113235c9ab8f7f2df2392482073 Mon Sep 17 00:00:00 2001 From: Frederik-Baetens Date: Wed, 9 Feb 2022 20:26:59 +0100 Subject: [PATCH] swarm/src/behaviour: Document impact of blocking code (#2482) Co-authored-by: Max Inden --- swarm/src/behaviour.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/swarm/src/behaviour.rs b/swarm/src/behaviour.rs index 48ccf1fa..75404d29 100644 --- a/swarm/src/behaviour.rs +++ b/swarm/src/behaviour.rs @@ -152,6 +152,13 @@ type THandlerInEvent = /// struct members are delegated to [`NetworkBehaviourEventProcess`] implementations. Those must be /// provided by the user on the type that [`NetworkBehaviour`] is derived on. /// +/// Because these implementations are granted exclusive access to the [`NetworkBehaviour`], +/// [blocking code](https://ryhl.io/blog/async-what-is-blocking/) in these implementations will +/// block the entire [`Swarm`](crate::Swarm) from processing new events, since the swarm cannot progress +/// without also having exclusive access to the [`NetworkBehaviour`]. A better alternative is to execute +/// blocking or asynchronous logic on a separate task, perhaps with the help of a bounded channel to +/// maintain backpressure. The sender for the channel could be included in the NetworkBehaviours constructor. +/// /// Optionally one can provide a custom `poll` function through the `#[behaviour(poll_method = /// "poll")]` attribute. This function must have the same signature as the [`NetworkBehaviour#poll`] /// function and will be called last within the generated [`NetworkBehaviour`] implementation.