Struct Networking 

pub struct Networking<D: NetDriver> { /* private fields */ }

Networking stack for managing OSI host layers 5 (session) and 6 (presentation).

This structure maintains user-side networking sessions and connections. It also manages the presentation layer, by accepting layer 7 (application) Messages to present downwards to layer 4 (transport) and below.

See module-level documentation for more details.

Implementations

impl<D: NetDriver> Networking<D>

pub fn new(driver_factory: impl NetDriverFactory<D>) -> Self

Create a new Networking stack using a particular NetDriver implementation.

pub fn event_bus(&self) -> &EventBusRegistry

Get the EventBusRegistry to register event handlers.

Available events:

• NetworkingConnectEvent
• NetworkingDisconnectEvent

pub fn insert_msg_handler<M, E>(&self, handler: impl MessageHandler<M, E>)

where M: MessageRecv, E: Error + Send + Sync + 'static,

Insert a message handler into this Networking stack.

The handler is associated with the message type’s key, and inserting multiple handlers with the same key will override the old one.

pub fn connection_info(&self, connection: &Connection) -> Option<ConnectionInfo>

Retrieve detailed ConnectionInfo for a particular Connection.

If there is no Connection or it has been closed, yields None.

pub async fn close(&self)

Close the Networking stack.

Closes the stack if it is open (e.g. has been connected or listened). It is likely that any future operations will yield NetworkingError::Closed until the stack is reset.

Note that the Networking stack will automatically close itself when dropped, so it is not necessary to explicitly call this before dropping the stack.

pub fn close_blocking(&self)

Convenience wrapper for a sync version of Self::close().

impl<D: NetDriverConnect> Networking<D>

pub async fn connect( &self, socket_addr: SocketAddr, ) -> Result<ClientConnectContext, NetworkingError>

Attempt to connect to the remote socket_addr.

How many endpoints can be connected to is up to the particular driver. For example, a client/server architecture may only allow a client to connect to one server at a time, whereas a peer-to-peer architecture may allow clients to connect to many other clients at once. See the driver’s documentation for more details.

Errors

NetworkingError::InvalidAddress if the socket_addr could not be connected to.

NetworkingError::Cancelled if the connection was cancelled by event handling.

pub fn connect_sync( &self, socket_addr: SocketAddr, ) -> Result<ClientConnectContext, NetworkingError>

Convenience wrapper for a sync version of Self::connect().

impl<D: NetDriverCloseConnection> Networking<D>

pub async fn close_connection(&self, connection: Connection)

Close the specified Connection.

This method is idempotent, and specifying a non-existing Connection ID will do nothing.

impl<D: NetDriverListen> Networking<D>

pub async fn listen( &self, socket_addr: SocketAddr, ) -> Result<(), NetworkingError>

Bind to and listen on a socket.

Errors

NetworkingError::InvalidAddress if the socket_addr could not be bound.

impl<D: NetDriverSend> Networking<D>

pub fn send<M>(&self, msg: impl Into<Message<M>>) -> Result<(), NetworkingError>

where M: MessageSend,

Send a Message.

Messages are dispatched immediately. This method does not block or otherwise wait.

Errors

NetworkingError::MalformedMessage if the Message couldn’t be encoded into bytes.

NetworkingError::Closed if the connection is closed.

pub fn send_recv<M>( &self, msg: impl Into<Message<M>>, ) -> Result<MessageReplyFuture<M::Reply>, NetworkingError>

where M: MessageSend + MessageRepliable, M::Reply: MessageRecv + Send + 'static,

Send a repliable Message and get a reply future.

Messages are dispatched immediately. This method does not block or otherwise wait, however the returned reply future can be waited on.

Errors

NetworkingError::MalformedMessage if the Message couldn’t be encoded into bytes.

NetworkingError::Closed if the connection is closed.

impl<D: NetDriverSendTo> Networking<D>

pub fn send_to<M>( &self, connection: Connection, msg: impl Into<Message<M>>, ) -> Result<(), NetworkingError>

where M: MessageSend,

Send a Message to a specific Connection.

Messages are dispatched immediately. This method does not block or otherwise wait.

Errors

NetworkingError::InvalidConnection if the Connection does not exist.

NetworkingError::MalformedMessage if the Message couldn’t be encoded into bytes.

NetworkingError::Closed if the driver is closed (e.g. no longer listening on a socket in the case of a server).

pub fn send_recv_to<M>( &self, connection: Connection, msg: impl Into<Message<M>>, ) -> Result<MessageReplyFuture<M::Reply>, NetworkingError>

where M: MessageSend + MessageRepliable, M::Reply: MessageRecv + Send + 'static,

Send a repliable Message to a specific Connection and get a reply future.

Messages are dispatched immediately. This method does not block or otherwise wait, however the returned reply future can be waited on.

Errors

NetworkingError::InvalidConnection if the Connection does not exist.

NetworkingError::MalformedMessage if the Message couldn’t be encoded into bytes.

NetworkingError::Closed if the driver is closed (e.g. no longer listening on a socket in the case of a server).

impl<D: NetDriverBroadcast> Networking<D>

pub fn broadcast<M>( &self, msg: impl Into<Message<M>>, ) -> Result<(), NetworkingError>

where M: MessageSend,

Broadcast a Message to all Connections.

Messages are dispatched immediately. This method does not block or otherwise wait.

Errors

NetworkingError::MalformedMessage if the Message couldn’t be encoded into bytes.

NetworkingError::Closed if the driver is closed (e.g. no longer listening on a socket in the case of a server).

Trait Implementations

impl<D: NetDriver> Drop for Networking<D>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.