Struct nng::Socket

pub struct Socket { /* fields omitted */ }

An NNG socket.

All communication between application and remote Scalability Protocol peers is done through sockets. A given socket can have multiple dialers, listeners, and pipes, and may be connected to multiple transports at the same time. However, a given socket will have exactly one protocol associated with it and is responsible for any state machines or other application-specific logic.

See the NNG documentation for more information.

Implementations

impl Socket

pub fn new(t: Protocol) -> Result<Socket>

Creates a new socket which uses the specified protocol.

Errors

• NotSupported: Protocol is not enabled.
• OutOfMemory: Insufficient memory available.

pub fn dial(&self, url: &str) -> Result<()>

Initiates a remote connection to a listener.

When the connection is closed, the underlying Dialer will attempt to re-establish the connection.

The first attempt to connect to the address indicated by the provided url is done synchronously, including any necessary name resolution. As a result, a failure, such as if the connection is refused, will be returned immediately and no further action will be taken.

If the connection was closed for a synchronously dialed connection, the dialer will still attempt to redial asynchronously.

Because the dialer is started immediately, it is generally not possible to apply extra configuration. If that is needed, or if one wishes to close the dialer before the socket, applications should consider using the Dialer type directly.

See the NNG documentation for more information.

Errors

• AddressInvalid: An invalid url was specified.
• Closed: The socket is not open.
• ConnectionRefused: The remote peer refused the connection.
• ConnectionReset: The remote peer reset the connection.
• DestUnreachable: The remote address is not reachable.
• OutOfMemory: Insufficient memory is available.
• PeerAuth: Authentication or authorization failure.
• Protocol: A protocol error occurred.

pub fn listen(&self, url: &str) -> Result<()>

Initiates and starts a listener on the specified address.

Listeners are used to accept connections initiated by remote dialers. Unlike a dialer, listeners generally can have many connections open concurrently.

The act of “binding” to the address indicated by url is done synchronously, including any necessary name resolution. As a result, a failure, such as if the address is already in use, will be returned immediately.

Because the listener is started immediately, it is generally not possible to apply extra configuration. If that is needed, or if one wishes to close the dialer before the socket, applications should consider using the Listener type directly.

See the NNG documentation for more information.

Errors

• AddressInUse: The address specified by url is already in use.
• AddressInvalid: An invalid url was specified.
• Closed: The socket is not open.
• OutOfMemory: Insufficient memory is available.

pub fn dial_async(&self, url: &str) -> Result<()>

Asynchronously initiates a remote connection to a listener.

When the connection is closed, the underlying Dialer will attempt to re-establish the connection. It will also periodically retry a connection automatically if an attempt to connect asynchronously fails.

Because the dialer is started immediately, it is generally not possible to apply extra configuration. If that is needed, or if one wishes to close the dialer before the socket, applications should consider using the Dialer type directly.

See the NNG documentation for more information.

Errors

• AddressInvalid: An invalid url was specified.
• Closed: The socket is not open.
• ConnectionRefused: The remote peer refused the connection.
• ConnectionReset: The remote peer reset the connection.
• DestUnreachable: The remote address is not reachable.
• OutOfMemory: Insufficient memory is available.
• PeerAuth: Authentication or authorization failure.
• Protocol: A protocol error occurred.

pub fn recv(&self) -> Result<Message>

Receives a message from the socket.

The semantics of what receiving a message means vary from protocol to protocol, so examination of the protocol documentation is encouraged. For example, with a req socket a message may only be received after a request has been sent. Furthermore, some protocols may not support receiving data at all, such as pub.

Errors

• Closed: The socket is not open.
• IncorrectState: The socket cannot receive data in this state.
• NotSupported: The protocol does not support receiving.
• OutOfMemory: Insufficient memory is available.
• TimedOut: The operation timed out.

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

Sends a message on the socket.

The semantics of what sending a message means vary from protocol to protocol, so examination of the protocol documentation is encouraged. For example, with a pub socket the data is broadcast so that any peers who have a suitable subscription will be able to receive it. Furthermore, some protocols may not support sending data (such as sub) or may require other conditions. For example, rep sockets cannot normally send data, which are responses to requests, until they have first received a request.

If the message cannot be sent, then it is returned to the caller as a part of the Error.

Errors

• Closed: The socket is not open.
• IncorrectState: The socket cannot send messages in this state.
• MessageTooLarge: The message is too large.
• NotSupported: The protocol does not support sending messages.
• OutOfMemory: Insufficient memory available.
• TimedOut: The operation timed out.

pub fn try_recv(&self) -> Result<Message>

Attempts to receives a message from the socket.

The semantics of what receiving a message means vary from protocol to protocol, so examination of the protocol documentation is encouraged. For example, with a req socket a message may only be received after a request has been sent. Furthermore, some protocols may not support receiving data at all, such as pub.

If no message is available, this function will immediately return.

Errors

• Closed: The socket is not open.
• IncorrectState: The socket cannot receive data in this state.
• NotSupported: The protocol does not support receiving.
• OutOfMemory: Insufficient memory is available.
• TryAgain: The operation would block.

pub fn try_send<M: Into<Message>>(&self, msg: M) -> Result<(), (Message, Error)>

Attempts to sends a message on the socket.

The semantics of what sending a message means vary from protocol to protocol, so examination of the protocol documentation is encouraged. For example, with a pub socket the data is broadcast so that any peers who have a suitable subscription will be able to receive it. Furthermore, some protocols may not support sending data (such as sub) or may require other conditions. For example, rep sockets cannot normally send data, which are responses to requests, until they have first received a request.

If the message cannot be sent (e.g., there are no peers or there is backpressure from the peers) then this function will return immediately. If the message cannot be sent, then it is returned to the caller as a part of the Error.

Errors

• Closed: The socket is not open.
• IncorrectState: The socket cannot send messages in this state.
• MessageTooLarge: The message is too large.
• NotSupported: The protocol does not support sending messages.
• OutOfMemory: Insufficient memory available.
• TryAgain: The operation would block.

pub fn recv_async(&self, aio: &Aio) -> Result<()>

Start a receive operation using the given Aio and return immediately.

Errors

• IncorrectState: The Aio already has a running operation.

pub fn send_async<M: Into<Message>>(
    &self,
    aio: &Aio,
    msg: M
) -> Result<(), (Message, Error)>

Start a send operation on the given Aio and return immediately.

Errors

• IncorrectState: The Aio already has a running operation.

pub fn pipe_notify<F>(&self, callback: F) -> Result<()> where
    F: Fn(Pipe, PipeEvent) + Send + Sync + 'static, 

Register a callback function to be called whenever a pipe event occurs on the socket.

Only a single callback function can be supplied at a time. Registering a new callback implicitly unregisters any previously registered.

Errors

None specified.

Panics

If the callback function panics, the program will log the panic if possible and then abort. Future Rustc versions will likely do the same for uncaught panics at FFI boundaries, so this library will produce the abort in order to keep things consistent. As such, the user is responsible for either having a callback that never panics or catching and handling the panic within the callback.

pub fn close(&self)

Close the underlying socket.

Messages that have been submitted for sending may be flushed or delivered depending on the transport and the linger option. Further attempts to use the socket (via this handle or any other) after this call returns will result in an error. Threads waiting for operations on the socket when this call is executed may also return with an error.

Closing the socket while data is in transmission will likely lead to loss of that data. There is no automatic linger or flush to ensure that the socket send buffers have completely transmitted. It is recommended to wait a brief period after sending data before calling this function.

This function will be called automatically when all handles have been dropped.

Trait Implementations

impl Clone for Socket

fn clone(&self) -> Socket

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Socket

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

Formats the value using the given formatter.

impl Hash for Socket

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl Ord for Socket

fn cmp(&self, other: &Socket) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<Socket> for Socket

fn eq(&self, other: &Socket) -> 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 !=.

impl PartialOrd<Socket> for Socket

fn partial_cmp(&self, other: &Socket) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl TryFrom<Socket> for RawSocket

type Error = CookedSocketError

The type returned in the event of a conversion error.

fn try_from(socket: Socket) -> Result<Self, Self::Error>

Performs the conversion.

impl Eq for Socket

impl GetOpt<MaxTtl> for Socket

impl GetOpt<Raw> for Socket

impl GetOpt<RecvBufferSize> for Socket

impl GetOpt<RecvFd> for Socket

impl GetOpt<RecvTimeout> for Socket

impl GetOpt<ResendTime> for Socket

impl GetOpt<SendBufferSize> for Socket

impl GetOpt<SendFd> for Socket

impl GetOpt<SendTimeout> for Socket

impl GetOpt<SocketName> for Socket

impl GetOpt<SurveyTime> for Socket

impl SetOpt<CaFile> for Socket

impl SetOpt<CertKeyFile> for Socket

impl SetOpt<KeepAlive> for Socket

impl SetOpt<MaxTtl> for Socket

impl SetOpt<NoDelay> for Socket

impl SetOpt<ReconnectMaxTime> for Socket

impl SetOpt<ReconnectMinTime> for Socket

impl SetOpt<RecvBufferSize> for Socket

impl SetOpt<RecvMaxSize> for Socket

impl SetOpt<RecvTimeout> for Socket

impl SetOpt<RequestHeaders> for Socket

impl SetOpt<ResendTime> for Socket

impl SetOpt<ResponseHeaders> for Socket

impl SetOpt<SendBufferSize> for Socket

impl SetOpt<SendTimeout> for Socket

impl SetOpt<SocketName> for Socket

impl SetOpt<Subscribe> for Socket

impl SetOpt<SurveyTime> for Socket

impl SetOpt<Unsubscribe> for Socket