[−][src]Struct nng::Socket

pub struct Socket { /* fields omitted */ }

A nanomsg-next-generation 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 documenatation for more information.

Methods

`impl Socket`[src]

`pub fn new(t: Protocol) -> Result<Socket>`[src]

Creates a new socket which uses the specified protocol.

`pub fn dial(&self, url: &str) -> Result<()>`[src]

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.

`pub fn listen(&self, url: &str) -> Result<()>`[src]

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.

`pub fn dial_async(&self, url: &str) -> Result<()>`[src]

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.

`pub fn listen_async(&self, url: &str) -> Result<()>`[src]

Asynchronously 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 asynchronously, including any necessary name resolution. Any failure to bind will be periodically reattempted in the background.

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.

`pub fn recv(&self) -> Result<Message>`[src]

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.

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

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.

`pub fn try_recv(&self) -> Result<Message>`[src]

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.

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

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.

`pub fn recv_async(&self, aio: &Aio) -> Result<()>`[src]

Receive a message using the socket asynchronously.

This function will return immediately. If there is already an I/O operation in progress that is not a receive operation, this function will return Error::TryAgain.

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

Send a message using the socket asynchronously.

This function will return immediately. If there is already an I/O operation in progress, this function will return Error::TryAgain and return the message to the caller.

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

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.

Panicking

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 into_raw(self) -> Option<RawSocket>`[src]

Creates a RawSocket object if this socket is in "raw" mode.

`pub fn close(&self)`[src]

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.