Struct veloren_network::api::Participant

pub struct Participant {
    local_pid: Pid,
    remote_pid: Pid,
    a2b_open_stream_s: UnboundedSender<(Prio, Promises, Bandwidth, Sender<Stream>)>,
    b2a_stream_opened_r: UnboundedReceiver<Stream>,
    b2a_event_r: UnboundedReceiver<ParticipantEvent>,
    b2a_bandwidth_stats_r: Receiver<f32>,
    a2s_disconnect_s: Arc<Mutex<Option<UnboundedSender<(Pid, (Duration, Sender<Result<(), ParticipantError>>))>>>>,
}

Participants are generated by the Network and represent a connection to a remote Participant. Look at the connect and connected method of Networks on how to generate Participants

Fields

local_pid: Pid

remote_pid: Pid

a2b_open_stream_s: UnboundedSender<(Prio, Promises, Bandwidth, Sender<Stream>)>

b2a_stream_opened_r: UnboundedReceiver<Stream>

b2a_event_r: UnboundedReceiver<ParticipantEvent>

b2a_bandwidth_stats_r: Receiver<f32>

a2s_disconnect_s: Arc<Mutex<Option<UnboundedSender<(Pid, (Duration, Sender<Result<(), ParticipantError>>))>>>>

Implementations

impl Participant

pub(crate) fn new( local_pid: Pid, remote_pid: Pid, a2b_open_stream_s: UnboundedSender<(Prio, Promises, Bandwidth, Sender<Stream>)>, b2a_stream_opened_r: UnboundedReceiver<Stream>, b2a_event_r: UnboundedReceiver<ParticipantEvent>, b2a_bandwidth_stats_r: Receiver<f32>, a2s_disconnect_s: UnboundedSender<(Pid, (Duration, Sender<Result<(), ParticipantError>>))>, ) -> Self

pub async fn open( &self, prio: u8, promises: Promises, bandwidth: Bandwidth, ) -> Result<Stream, ParticipantError>

Opens a Stream on this Participant with a certain Priority and Promises

Arguments

• prio - defines which stream is processed first when limited on bandwidth. See Prio for documentation.
• promises - use a combination of you preferred Promises, see the link for further documentation. You can combine them, e.g. Promises::ORDERED | Promises::CONSISTENCY The Stream will then guarantee that those promises are met.
• bandwidth - sets a guaranteed bandwidth which is reserved for this stream. When excess bandwidth is available it will be used. See Bandwidth for details.

A ParticipantError might be thrown if the Participant is already closed. Streams can be created without a answer from the remote side, resulting in very fast creation and closing latency.

Examples

use tokio::runtime::Runtime;
use veloren_network::{ConnectAddr, ListenAddr, Network, Pid, Promises};

// Create a Network, connect on port 2100 and open a stream
let runtime = Runtime::new().unwrap();
let network = Network::new(Pid::new(), &runtime);
runtime.block_on(async {
    let p1 = network
        .connect(ConnectAddr::Tcp("127.0.0.1:2100".parse().unwrap()))
        .await?;
    let _s1 = p1
        .open(4, Promises::ORDERED | Promises::CONSISTENCY, 1000)
        .await?;
    drop(network);
})

pub async fn opened(&mut self) -> Result<Stream, ParticipantError>

Use this method to handle Streams opened from remote site, like the connected method of Network. This is the associated method to open. It’s guaranteed that the order of open and opened is equal. The nth Streams on one side will represent the nth on the other side. A ParticipantError might be thrown if the Participant is already closed.

Examples

use tokio::runtime::Runtime;
use veloren_network::{Network, Pid, ListenAddr, ConnectAddr, Promises};

// Create a Network, connect on port 2110 and wait for the other side to open a stream
// Note: It's quite unusual to actively connect, but then wait on a stream to be connected, usually the Application taking initiative want's to also create the first Stream.
let runtime = Runtime::new().unwrap();
let mut network = Network::new(Pid::new(), &runtime);
runtime.block_on(async {
    let mut p1 = network.connect(ConnectAddr::Tcp("127.0.0.1:2110".parse().unwrap())).await?;
    let _s1 = p1.opened().await?;
    drop(network);
})

pub async fn disconnect(self) -> Result<(), ParticipantError>

disconnecting a Participant in a async way. Use this rather than Participant::Drop if you want to close multiple Participants.

This function will wait for all Streams to properly close, including all messages to be send before closing. If an error occurs with one of the messages. Except if the remote side already dropped the Participant simultaneously, then messages won’t be send

There is NO disconnected function in Participant, if a Participant is no longer reachable (e.g. as the network cable was unplugged) the Participant will fail all action, but needs to be manually disconnected, using this function.

Examples

use tokio::runtime::Runtime;
use veloren_network::{Network, Pid, ListenAddr, ConnectAddr};

// Create a Network, listen on port `2030` TCP and opens returns their Pid and close connection.
let runtime = Runtime::new().unwrap();
let mut network = Network::new(Pid::new(), &runtime);
let err = runtime.block_on(async {
    network
        .listen(ListenAddr::Tcp("127.0.0.1:2030".parse().unwrap()))
        .await?;
    while let Ok(participant) = network.connected().await {
        println!("Participant connected: {}", participant.remote_pid());
        participant.disconnect().await?;
    }
});
drop(network);

pub async fn fetch_event( &mut self, ) -> Result<ParticipantEvent, ParticipantError>

Use this method to query ParticipantEvent. Those are internal events from the network crate that will get reported to the frontend. E.g. Creation and Deletion of Channels.

Make sure to call this function from time to time to not let events stack up endlessly and create a memory leak.

Examples

use tokio::runtime::Runtime;
use veloren_network::{Network, Pid, ListenAddr, ConnectAddr, Promises, ParticipantEvent};

// Create a Network, connect on port 2040 and wait for the other side to open a stream
// Note: It's quite unusual to actively connect, but then wait on a stream to be connected, usually the Application taking initiative want's to also create the first Stream.
let runtime = Runtime::new().unwrap();
let mut network = Network::new(Pid::new(), &runtime);
runtime.block_on(async {
    let mut p1 = network.connect(ConnectAddr::Tcp("127.0.0.1:2040".parse().unwrap())).await?;
    let event = p1.fetch_event().await?;
    drop(network);
})

pub fn try_fetch_event( &mut self, ) -> Result<Option<ParticipantEvent>, ParticipantError>

use try_fetch_event to check for a ParticipantEvent . This function does not block and returns immediately. It’s intended for use in non-async context only. Other then that, the same rules apply than for fetch_event.

pub fn bandwidth(&self) -> f32

Returns the current approximation on the maximum bandwidth available. This WILL fluctuate based on the amount/size of send messages.

pub fn remote_pid(&self) -> Pid

Returns the remote Pid

Trait Implementations

impl Debug for Participant

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Participant

fn drop(&mut self)

Executes the destructor for this type.

impl PartialEq for Participant

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.