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

Allow users to opt out of the NetworkBehaviourEventProcess mechanism (#1630)

Browse Source 
* Allow users to opt-out of the NetworkBehaviourEventProcess mechanism

* Add CHANGELOG entry

* Prepare release.

Co-authored-by: Roman Borschel <romanb@users.noreply.github.com>
Co-authored-by: Roman S. Borschel <roman@parity.io>
This commit is contained in:
Thomas Eizinger
2020-07-08 19:32:47 +10:00
committed by GitHub
parent d645ccb0df
commit c4a5497d2d
8 changed files with 137 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
swarm/src/behaviour.rs
View File

@ -31,18 +31,27 @@ use std::{error, task::Context, task::Poll};
///
/// Crate users can implement this trait by using the the `#[derive(NetworkBehaviour)]`
/// proc macro re-exported by the `libp2p` crate. The macro generates a delegating `trait`
/// implementation for the `struct`, which delegates method calls to all trait members. Any events
/// generated by struct members are delegated to [`NetworkBehaviourEventProcess`] implementations
/// which are expected to be provided by the user.
/// implementation for the `struct`, which delegates method calls to all trait members.
///
/// Optionally one can implement a custom `poll` function, which needs to be tagged with the
/// `#[behaviour(poll_method = "poll")]` attribute, and would be called last with no parameters.
///
/// By default the derive sets the `NetworkBehaviour::OutEvent` as `()` but this can be overriden
/// By default the derive sets the [`NetworkBehaviour::OutEvent`] as `()` but this can be overridden
/// with `#[behaviour(out_event = "AnotherType")]`.
///
/// `#[behaviour(ignore)]` can be added on a struct field to disable generation of delegation to
/// the fields which do not implement `NetworkBehaviour`.
/// Struct members that don't implement [`NetworkBehaviour`] must be annotated with `#[behaviour(ignore)]`.
///
/// By default, events generated by the remaining members are delegated to [`NetworkBehaviourEventProcess`]
/// implementations. Those must be provided by the user on the type that [`NetworkBehaviour`] is
/// derived on.
///
/// Alternatively, users can specify `#[behaviour(event_process = false)]`. In this case, users
/// should provide a custom `out_event` and implement [`From`] for each of the event types generated
/// by the struct members.
/// Not processing events within the derived [`NetworkBehaviour`] will cause them to be emitted as
/// part of polling the swarm in [`SwarmEvent::Behaviour`](crate::SwarmEvent::Behaviour).
///
/// 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.
pub trait NetworkBehaviour: Send + 'static {
/// Handler for all the protocols the network behaviour supports.
type ProtocolsHandler: IntoProtocolsHandler;
@ -193,8 +202,11 @@ pub trait PollParameters {
fn local_peer_id(&self) -> &PeerId;
}
/// When deriving [`NetworkBehaviour`] this trait must be implemented for all the possible event types
/// generated by the inner behaviours.
/// When deriving [`NetworkBehaviour`] this trait must by default be implemented for all the
/// possible event types generated by the inner behaviours.
///
/// You can opt out of this behaviour through `#[behaviour(event_process = false)]`. See the
/// documentation of [`NetworkBehaviour`] for details.
pub trait NetworkBehaviourEventProcess<TEvent> {
/// Called when one of the fields of the type you're deriving `NetworkBehaviour` on generates
/// an event.