fluencelabs/rust-libp2p
1
0
Fork 0
mirror of https://github.com/fluencelabs/rust-libp2p synced 2025-06-14 10:31:21 +00:00
Code Issues Projects Releases Wiki Activity

swarm-derive/: Generate OutEvent if not provided (#2792)

Browse Source 
Generate `NetworkBehaviour::OutEvent` if not provided through
`#[behaviour(out_event = "MyOutEvent")]` and event processing is
disabled (default).
This commit is contained in:
Max Inden
2022-08-08 07:18:32 +02:00
committed by GitHub
parent 028decec69
commit 579b1be5d5
8 changed files with 281 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
swarm/src/behaviour.rs
View File

@ -79,16 +79,11 @@ pub(crate) type THandlerOutEvent<THandler> =
/// it will delegate to each `struct` member and return a concatenated array of all addresses
/// returned by the struct members.
///
/// When creating a custom [`NetworkBehaviour`], you must choose one of two methods to respond to
/// incoming events:
/// * One option is setting a custom `out_event` with `#[behaviour(out_event = "AnotherType")]`.
/// In this case, events generated by the custom [`NetworkBehaviour`] struct members will be
/// converted to your custom `out_event` for you to handle after polling the swarm.
/// * Alternatively, users that need access to the root [`NetworkBehaviour`] implementation while
/// processing emitted events, can specify `#[behaviour(event_process = true)]` (default is false).
/// Events generated by the behaviour's struct members are delegated to [`NetworkBehaviourEventProcess`]
/// trait implementations. Those must be provided by the user on the type that [`NetworkBehaviour`]
/// is derived on.
/// Events ([`NetworkBehaviour::OutEvent`]) returned by each `struct` member are wrapped in a new
/// `enum` event, with an `enum` variant for each `struct` member. Users can define this event
/// `enum` themselves and provide the name to the derive macro via `#[behaviour(out_event =
/// "MyCustomOutEvent")]`. If the user does not specify an `out_event`, the derive macro generates
/// the event definition itself, naming it `<STRUCT_NAME>Event`.
///
/// When setting a custom `out_event`, the aforementioned conversion of each of the event types
/// generated by the struct members to the custom `out_event` is handled by [`From`]
@ -123,14 +118,6 @@ pub(crate) type THandlerOutEvent<THandler> =
/// }
/// ```
///
/// When using `event_process = true` the [`NetworkBehaviourEventProcess`] trait implementations
/// are granted exclusive access to the [`NetworkBehaviour`], therefore
/// [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.