[−][src]Crate nng

A safe Rust wrapper for NNG

What Is NNG

NNG, like its predecessors nanomsg (and to some extent ZeroMQ), is a lightweight, broker-less library, offering a simple API to solve common recurring messaging problems, such as publish/subscribe, RPC-style request/reply, or service discovery. The API frees the programmer from worrying about details like connection management, retries, and other common considerations, so that they can focus on the application instead of the plumbing.

This crate provides a safe wrapper around the NNG library, seeking to maintain an API that is similar to the original library. As such, the majority of examples available online should be easy to apply to this crate.

Rust Version Requirements

The current version requires Rustc v1.31 or greater. In general, this crate should always be able to compile with the Rustc version available on the oldest Ubuntu LTS release. Any change that requires a newer Rustc version will always be considered a breaking change and this crate's version number will be bumped accordingly.

Features

build-nng (default): Build NNG from source and statically link to the library.
ffi-module: Expose the raw FFI bindings via the nng::ffi module. This is useful for utilizing NNG features that are implemented in the base library but not this wrapper. Note that this exposes some internal items of this library and it directly exposes the NNG library, so anything enabled by this can change without bumping versions.

Examples

The following example uses the intra-process transport to set up a request/reply socket pair. The "client" sends a String to the "server" which responds with a nice phrase.

use std::io::Write;
use nng::*;

const ADDRESS: &'static str = "inproc://nng/example";

fn request() -> Result<()> {
    // Set up the client and connect to the specified address
    let mut client = Socket::new(Protocol::Req0)?;
    client.dial(ADDRESS)?;

    // Send the request from the client to the server. In general, it will be
    // better to directly use a `Message` to enable zero-copy, but that doesn't
    // matter here.
    client.send("Ferris".as_bytes())?;

    // Wait for the response from the server.
    let msg = client.recv()?;
    let reply = String::from_utf8_lossy(&msg);
    assert_eq!(reply, "Hello, Ferris!");
    Ok(())
}

fn reply() -> Result<()> {
    // Set up the server and listen for connections on the specified address.
    let server = Socket::new(Protocol::Rep0)?;
    server.listen(ADDRESS)?;

    // Receive the message from the client.
    let mut msg = server.recv()?;
    let name = String::from_utf8_lossy(&msg).into_owned();
    assert_eq!(name, "Ferris");

    // Reuse the message to be more efficient.
    msg.clear();
    write!(msg, "Hello, {}!", name).unwrap();

    server.send(msg)?;
    Ok(())
}

Additional examples are in the examples directory.

Modules

options

Options available to configure nng constructs.

Structs

Aio	An asynchronous I/O context.
Context	A socket context.
Dialer	A constructed and running dialer.
DialerOptions	Configuration utility for nanomsg-next-generation dialers.
Header	The header of a `Message`.
Listener	A constructed and running listener.
ListenerOptions	Configuration utility for nanomsg-next-generation listeners.
Message	An `nng` message type.
Pipe	A nanomsg-next-generation pipe.
RawSocket	A socket that is open in "raw" mode.
Socket	A nanomsg-next-generation socket.

Enums

AioResult	The result of an AIO operation.
Error	Errors potentially returned by NNG operations.
PipeEvent	An event that happens on a Pipe instance.
Protocol	Describes a relationship between a socket and all sockets to which it is connected.
SocketAddr	Represents the addresses used by the underlying transports.

Functions

forwarder	Forwards messages from socket s1 to socket s2 and vice versa.
reflector	Reflects a socket's sent messages back at itself.

Type Definitions

Result

Specialized Result type for use with nng.