nng

https://docs.rs/nng/latest/nng
Admin
A safe Rust wrapper for NNG, a lightweight, broker-less messaging library that simplifies common...
Tokens:178,646
Snippets:1,437
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### NNG Listener Management API Functions

Source: https://docs.rs/nng/latest/nng/-sys/1.4.0-rc.0/i686-unknown-linux-gnu/nng_sys/index

Functions for creating, retrieving, setting, and getting various options for NNG listeners, as well as starting a listener.

```APIDOC
nng_listener_create()
nng_listener_get()
nng_listener_get_addr()
nng_listener_get_bool()
nng_listener_get_int()
nng_listener_get_ms()
nng_listener_get_ptr()
nng_listener_get_size()
nng_listener_get_string()
nng_listener_get_uint64()
nng_listener_getopt()
nng_listener_getopt_bool()
nng_listener_getopt_int()
nng_listener_getopt_ms()
nng_listener_getopt_ptr()
nng_listener_getopt_size()
nng_listener_getopt_sockaddr()
nng_listener_getopt_string()
nng_listener_getopt_uint64()
nng_listener_id()
nng_listener_set()
nng_listener_set_addr()
nng_listener_set_bool()
nng_listener_set_int()
nng_listener_set_ms()
nng_listener_set_ptr()
nng_listener_set_size()
nng_listener_set_string()
nng_listener_set_uint64()
nng_listener_setopt()
nng_listener_setopt_bool()
nng_listener_setopt_int()
nng_listener_setopt_ms()
nng_listener_setopt_ptr()
nng_listener_setopt_size()
nng_listener_setopt_string()
nng_listener_setopt_uint64()
nng_listener_start()
```

--------------------------------

### Rust nng Server Worker Contexts Example

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Aio

An example demonstrating the creation of multiple worker contexts with `nng::Aio` for a request-reply server. It illustrates how to initialize Aio handles with a callback and manage concurrent I/O operations, similar to the main server example.

```Rust
fn server(url: &str) -> Result<(), nng::Error> {
    // Create the socket
    let s = Socket::new(Protocol::Rep0)?;

    // Create all of the worker contexts
    let workers: Vec<_> = (0..PARALLEL)
        .map(|_| {
            let ctx = Context::new(&s)?;
            let ctx_clone = ctx.clone();
            let aio = Aio::new(move |aio, res| worker_callback(aio, &ctx_clone, res))?;
            Ok((aio, ctx))
        })
        .collect::<Result<_, nng::Error>>()?;

    // Only after we have the workers do we start listening.
    s.listen(url)?;

    // Now start all of the workers listening.
    for (a, c) in &workers {
        c.recv(a)?;
    }

    thread::sleep(Duration::from_secs(60 * 60 * 24 * 365));

    Ok(())
}
```

--------------------------------

### NNG Rust Asynchronous Rep0 Protocol Server Example

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Socket

Illustrates an asynchronous server using the Rep0 protocol. It creates multiple worker contexts, starts them listening for requests, and processes them concurrently.

```Rust
fn server(url: &str) -> Result<(), nng::Error> {
    // Create the socket
    let s = Socket::new(Protocol::Rep0)?;

    // Create all of the worker contexts
    let workers: Vec<_> = (0..PARALLEL)
        .map(|_| {
            let ctx = Context::new(&s)?;
            let ctx_clone = ctx.clone();
            let aio = Aio::new(move |aio, res| worker_callback(aio, &ctx_clone, res))?;
            Ok((aio, ctx))
        })
        .collect::<Result<_, nng::Error>>()?;

    // Only after we have the workers do we start listening.
    s.listen(url)?;

    // Now start all of the workers listening.
    for (a, c) in &workers {
        c.recv(a)?;
    }

    thread::sleep(Duration::from_secs(60 * 60 * 24 * 365));

    Ok(())
}
```

--------------------------------

### Rust Slice `partition_point` Basic Example

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Message

An example demonstrating the `partition_point` method. It finds the partition point for elements less than 5 in a sorted slice and asserts the correctness of the resulting index and partitions.

```Rust
let v = [1, 2, 3, 3, 5, 6, 7];
let i = v.partition_point(|&x| x < 5);

assert_eq!(i, 4);
assert!(v[..i].iter().all(|&x| x < 5));
assert!(v[i..].iter().all(|&x| !(x < 5)));
```

--------------------------------

### Rust: Asynchronous NNG Server Setup

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Context

This Rust function demonstrates how to set up an asynchronous NNG (Nanomsg Next Generation) server. It creates a `Rep0` socket, initializes multiple worker contexts, and starts listening for incoming messages. Each worker context uses an `Aio` object to handle asynchronous operations.

```Rust
fn server(url: &str) -> Result<(), nng::Error> {
    // Create the socket
    let s = Socket::new(Protocol::Rep0)?;

    // Create all of the worker contexts
    let workers: Vec<_> = (0..PARALLEL)
        .map(|_| {
            let ctx = Context::new(&s)?;
            let ctx_clone = ctx.clone();
            let aio = Aio::new(move |aio, res| worker_callback(aio, &ctx_clone, res))?;
            Ok((aio, ctx))
        })
        .collect::<Result<_, nng::Error>>()?;

    // Only after we have the workers do we start listening.
    s.listen(url)?;

    // Now start all of the workers listening.
    for (a, c) in &workers {
        c.recv(a)?;
    }

    thread::sleep(Duration::from_secs(60 * 60 * 24 * 365));

    Ok(())
}
```

--------------------------------

### Rust NNG Intra-Process Request/Reply Example

Source: https://docs.rs/nng/latest/nng/1.0.1/src/nng/lib.rs

This example demonstrates setting up a request/reply socket pair using NNG's intra-process transport in Rust. A 'client' sends a string to a 'server', which then processes the request and sends back a response. It illustrates basic message sending and receiving with NNG sockets.

```Rust
use nng::*;

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

fn request() -> Result<()> {
    // Set up the client and connect to the specified address
    let client = Socket::new(Protocol::Req0)?;
    # // Don't error if we hit here before the server does.
    # client.dial_async(ADDRESS)?;
    # if false {
    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()?;
    assert_eq!(&msg[..], b"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()?;
    assert_eq!(&msg[..], b"Ferris");

    // Reuse the message to be more efficient.
    msg.push_front(b"Hello, ");

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

# // Start the server first, so the client can connect to it.
# let jh = std::thread::spawn(|| reply().unwrap());
# request().unwrap();
# jh.join().unwrap();
```

--------------------------------

### Rust Slice: Example for `as_rchunks` Method

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Illustrates the usage of the `as_rchunks` method, showing how it splits a slice into chunks starting from the end, resulting in a remainder at the beginning of the original slice.

```Rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let (remainder, chunks) = slice.as_rchunks();
assert_eq!(remainder, &['l']);
assert_eq!(chunks, &[['o', 'r'], ['e', 'm']]);
```

--------------------------------

### Rust Slice: Examples for `as_chunks` Method

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Provides two examples for using the `as_chunks` method. The first demonstrates splitting a slice and retrieving both chunks and remainder. The second shows how to combine `as_chunks` with `let-else` to assert an exact multiple length, panicking otherwise.

```Rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let (chunks, remainder) = slice.as_chunks();
assert_eq!(chunks, &[['l', 'o'], ['r', 'e']]);
assert_eq!(remainder, &['m']);

let slice = ['R', 'u', 's', 't'];
let (chunks, []) = slice.as_chunks::<2>() else {
    panic!("slice didn't have even length")
};
assert_eq!(chunks, &[['R', 'u'], ['s', 't']]);
```

--------------------------------

### NNG Listener API Functions (nng_sys)

Source: https://docs.rs/nng/latest/nng/-sys/1.4.0-rc.0/x86_64-unknown-linux-gnu/nng_sys/index

Functions for managing NNG listeners, including creation, starting, retrieving and setting options (boolean, integer, string, pointer, size, time, uint64, sockaddr), and getting the listener ID.

```APIDOC
nng_listener_create()
nng_listener_get()
nng_listener_get_addr()
nng_listener_get_bool()
nng_listener_get_int()
nng_listener_get_ms()
nng_listener_get_ptr()
nng_listener_get_size()
nng_listener_get_string()
nng_listener_get_uint64()
nng_listener_getopt()
nng_listener_getopt_bool()
nng_listener_getopt_int()
nng_listener_getopt_ms()
nng_listener_getopt_ptr()
nng_listener_getopt_size()
nng_listener_getopt_sockaddr()
nng_listener_getopt_string()
nng_listener_getopt_uint64()
nng_listener_id()
nng_listener_set()
nng_listener_set_addr()
nng_listener_set_bool()
nng_listener_set_int()
nng_listener_set_ms()
nng_listener_set_ptr()
nng_listener_set_size()
nng_listener_set_string()
nng_listener_set_uint64()
nng_listener_setopt()
nng_listener_setopt_bool()
nng_listener_setopt_int()
nng_listener_setopt_ms()
nng_listener_setopt_ptr()
nng_listener_setopt_size()
nng_listener_setopt_string()
nng_listener_setopt_uint64()
nng_listener_start()
```

--------------------------------

### NNG Rust DialerBuilder API Reference

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.DialerBuilder

Comprehensive API documentation for the `DialerBuilder` struct in the NNG Rust crate, detailing its constructor (`new`), method for starting dialers (`start`), and trait implementations like `Debug` (`fmt`) and `Drop` (`drop`).

```APIDOC
Struct DialerBuilder:
  Description: Configuration utility for NNG dialers. This object allows for the configuration of dialers before they are started. If it is not necessary to change dialer settings or to close the dialer without closing the socket, then Socket::dial provides a simpler interface.
  Methods:
    new(socket: &Socket, url: &str) -> Result<Self>:
      Description: Creates a new dialer object associated with the given socket. Note that this does not start the dialer. In order to start the dialer, this object must be consumed by DialerBuilder::start.
      Parameters:
        socket: &Socket - The socket to associate the dialer with.
        url: &str - The URL for the dialer.
      Returns: Result<Self>
      Errors:
        AddressInvalid: An invalid url was specified.
        Closed: The socket is not open.
        OutOfMemory: Insufficient memory available.

    start(self, nonblocking: bool) -> Result<Dialer, (Self, Error)>:
      Description: Causes the dialer to start connecting to the address with which it was created. Normally, the first attempt to connect to the dialer’s address 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. However, if `nonblocking` is specified, then the connection attempt is made asynchronously. Furthermore, if the connection was closed for a synchronously dialed connection, the dialer will still attempt to redial asynchronously. The returned handle controls the life of the dialer. If it is dropped, the dialer is shut down and no more messages will be received on it.
      Parameters:
        self: DialerBuilder - The DialerBuilder instance to consume.
        nonblocking: bool - If true, the connection attempt is made asynchronously.
      Returns: Result<Dialer, (Self, Error)> - A Dialer handle on success, or the DialerBuilder and an Error on failure.
      Errors:
        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 available.
        PeerAuth: Authentication or authorization failure.
        Protocol: A protocol error occurred.

    fmt(&self, f: &mut Formatter<'_>) -> Result:
      Description: Formats the value using the given formatter. This is part of the Debug trait implementation for DialerBuilder.
      Parameters:
        self: &DialerBuilder - The DialerBuilder instance.
        f: &mut Formatter<'_> - The formatter to use.
      Returns: Result

    drop(self):
      Description: Implements the Drop trait for DialerBuilder, defining actions to take when the DialerBuilder goes out of scope. This ensures proper resource cleanup when the dialer handle is dropped.
      Parameters:
        self: DialerBuilder - The DialerBuilder instance being dropped.
      Returns: None (implicitly for Drop trait)
```

--------------------------------

### Rust Slice connect Example (Deprecated)

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Message

Shows how to use the deprecated `connect` method, which is functionally identical to `join`.

```Rust
assert_eq!(["hello", "world"].connect(" "), "hello world");
assert_eq!([[1, 2], [3, 4]].connect(&0), [1, 2, 0, 3, 4]);
```

--------------------------------

### Rust Slice `as_simd` Example for SIMD Operations

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

This example demonstrates how to use `as_simd` to split a slice into a prefix, a middle section of SIMD types, and a suffix. It includes a `basic_simd_sum` function that leverages SIMD for efficient summation of `f32` arrays.

```Rust
#![feature(portable_simd)]
use core::simd::prelude::*;

let short = &[1, 2, 3];
let (prefix, middle, suffix) = short.as_simd::<4>();
assert_eq!(middle, []); // Not enough elements for anything in the middle

// They might be split in any possible way between prefix and suffix
let it = prefix.iter().chain(suffix).copied();
assert_eq!(it.collect::<Vec<_>>(), vec![1, 2, 3]);

fn basic_simd_sum(x: &[f32]) -> f32 {
    use std::ops::Add;
    let (prefix, middle, suffix) = x.as_simd();
    let sums = f32x4::from_array([
        prefix.iter().copied().sum(),
        0.0,
        0.0,
        suffix.iter().copied().sum(),
    ]);
    let sums = middle.iter().copied().fold(sums, f32x4::add);
    sums.reduce_sum()
}

let numbers: Vec<f32> = (1..101).map(|x| x as _).collect();
assert_eq!(basic_simd_sum(&numbers[1..99]), 4949.0);
```

--------------------------------

### Rust Slice sort_by Usage Examples

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Provides examples demonstrating how to use the `sort_by` method to sort a slice in ascending order and in reverse order using custom comparison closures.

```Rust
let mut v = [4, -5, 1, -3, 2];
v.sort_by(|a, b| a.cmp(b));
assert_eq!(v, [-5, -3, 1, 2, 4]);

// reverse sorting
v.sort_by(|a, b| b.cmp(a));
assert_eq!(v, [4, 2, 1, -3, -5]);
```

--------------------------------

### Example of Rust Slice `sort` Method Usage

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Message

A practical example demonstrating how to use the `sort` method on a mutable Rust slice to sort its elements in ascending order.

```Rust
let mut v = [4, -5, 1, -3, 2];

v.sort();
assert_eq!(v, [-5, -3, 1, 2, 4]);
```

--------------------------------

### NNG Dialer API Functions

Source: https://docs.rs/nng/latest/nng/-sys/^1.4.0-rc

Provides a comprehensive list of functions for managing NNG dialers, including creation, closing, starting, and various methods for getting and setting options like addresses, boolean flags, integers, milliseconds, pointers, sizes, strings, and uint64 values. These functions allow fine-grained control over outgoing connections.

```APIDOC
nng_dialer_close
```

```APIDOC
nng_dialer_create
```

```APIDOC
nng_dialer_get
```

```APIDOC
nng_dialer_get_addr
```

```APIDOC
nng_dialer_get_bool
```

```APIDOC
nng_dialer_get_int
```

```APIDOC
nng_dialer_get_ms
```

```APIDOC
nng_dialer_get_ptr
```

```APIDOC
nng_dialer_get_size
```

```APIDOC
nng_dialer_get_string
```

```APIDOC
nng_dialer_get_uint64
```

```APIDOC
nng_dialer_getopt
```

```APIDOC
nng_dialer_getopt_bool
```

```APIDOC
nng_dialer_getopt_int
```

```APIDOC
nng_dialer_getopt_ms
```

```APIDOC
nng_dialer_getopt_ptr
```

```APIDOC
nng_dialer_getopt_size
```

```APIDOC
nng_dialer_getopt_sockaddr
```

```APIDOC
nng_dialer_getopt_string
```

```APIDOC
nng_dialer_getopt_uint64
```

```APIDOC
nng_dialer_id
```

```APIDOC
nng_dialer_set
```

```APIDOC
nng_dialer_set_addr
```

```APIDOC
nng_dialer_set_bool
```

```APIDOC
nng_dialer_set_int
```

```APIDOC
nng_dialer_set_ms
```

```APIDOC
nng_dialer_set_ptr
```

```APIDOC
nng_dialer_set_size
```

```APIDOC
nng_dialer_set_string
```

```APIDOC
nng_dialer_set_uint64
```

```APIDOC
nng_dialer_setopt
```

```APIDOC
nng_dialer_setopt_bool
```

```APIDOC
nng_dialer_setopt_int
```

```APIDOC
nng_dialer_setopt_ms
```

```APIDOC
nng_dialer_setopt_ptr
```

```APIDOC
nng_dialer_setopt_size
```

```APIDOC
nng_dialer_setopt_string
```

```APIDOC
nng_dialer_setopt_uint64
```

```APIDOC
nng_dialer_start
```

--------------------------------

### Rust Example: Basic Slice Sorting

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

An example demonstrating the use of the `sort` method to sort a mutable array slice in Rust, showing the transformation from an unsorted to a sorted state.

```Rust
let mut v = [4, -5, 1, -3, 2];

v.sort();
assert_eq!(v, [-5, -3, 1, 2, 4]);
```

--------------------------------

### nng_stream_listener_listen Function

Source: https://docs.rs/nng/latest/nng/-sys/1.4.0-rc.0/i686-unknown-linux-gnu/nng_sys/index

API reference for the `nng_stream_listener_listen` function, used to start listening for incoming connections on a stream listener.

```APIDOC
nng_stream_listener_listen
```

--------------------------------

### Rust Slice join Example

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Message

Illustrates joining elements of a slice with a specified separator, demonstrating usage with strings and integer slices.

```Rust
assert_eq!(["hello", "world"].join(" "), "hello world");
assert_eq!([[1, 2], [3, 4]].join(&0), [1, 2, 0, 3, 4]);
assert_eq!([[1, 2], [3, 4]].join(&[0, 0][..]), [1, 2, 0, 0, 3, 4]);
```

--------------------------------

### Rust NNG Request/Reply Socket Example

Source: https://docs.rs/nng/latest/nng/latest/nng

Demonstrates setting up a request/reply socket pair using the intra-process transport in Rust. A client sends a string, and a server responds with a modified phrase, showcasing basic message sending and receiving with NNG.

```Rust
use nng::*;

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

fn request() -> Result<()> {
    // Set up the client and connect to the specified address
    let 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()?;
    assert_eq!(&msg[..], b"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()?;
    assert_eq!(&msg[..], b"Ferris");

    // Reuse the message to be more efficient.
    msg.push_front(b"Hello, ");

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

--------------------------------

### Access Rust Slice Elements with get

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Message

Examples of using the `get` method to safely access elements or subslices of a Rust array by index or range, returning `Option`.

```Rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```

--------------------------------

### Rust Slice rchunks Example

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Message

Example demonstrating the usage of the `rchunks` method to iterate over a slice in reverse chunks. Shows how to get non-overlapping chunks and handle the potentially smaller last chunk.

```Rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.rchunks(2);
assert_eq!(iter.next().unwrap(), &['e', 'm']);
assert_eq!(iter.next().unwrap(), &['o', 'r']);
assert_eq!(iter.next().unwrap(), &['l']);
assert!(iter.next().is_none());
```

--------------------------------

### Get Element or Subslice from Rust Slice

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Examples demonstrating the `get` method on a Rust slice to retrieve elements by index or subslices by range. Shows successful retrieval and cases where `None` is returned for out-of-bounds access.

```Rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```

--------------------------------

### Implement Request/Reply Sockets with NNG in Rust

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/index

This example demonstrates setting up a basic request/reply socket pair using the NNG Rust library's intra-process transport. A 'client' sends a string message, and a 'server' receives it, prepends 'Hello, ' to the message, and sends it back as a reply. It showcases Socket::new, client.dial, server.listen, send, and recv operations.

```Rust
use nng::*;

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

fn request() -> Result<()> {
    // Set up the client and connect to the specified address
    let 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()?;
    assert_eq!(&msg[..], b"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()?;
    assert_eq!(&msg[..], b"Ferris");

    // Reuse the message to be more efficient.
    msg.push_front(b"Hello, ");

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

--------------------------------

### NNG Rust Pair0 Protocol Node Example

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Socket

Demonstrates a basic node implementation using the Pair0 protocol. It creates a socket, listens on a URL, and then sends/receives messages.

```Rust
fn node0(url: &str) -> Result<(), Error> {
    let s = Socket::new(Protocol::Pair0)?;
    s.listen(url)?;

    send_recv(&s, "NODE0")
}
```

--------------------------------

### Get Iterator for Rust Slice

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Returns an iterator over the slice. The iterator yields all items from the start to the end of the slice, providing immutable references to each element.

```APIDOC
pub fn iter(&self) -> Iter<'_, T>
  Returns an iterator over the slice.
  The iterator yields all items from start to end.
```

```Rust
let x = &[1, 2, 4];
let mut iterator = x.iter();

assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);
```

--------------------------------

### Rust slice::split_at Example

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Demonstrates how to use the `split_at` method to divide a Rust slice into two parts at different indices.

```Rust
let v = ['a', 'b', 'c'];

{
   let (left, right) = v.split_at(0);
   assert_eq!(left, []);
   assert_eq!(right, ['a', 'b', 'c']);
}

{
    let (left, right) = v.split_at(2);
    assert_eq!(left, ['a', 'b']);
    assert_eq!(right, ['c']);
}

{
    let (left, right) = v.split_at(3);
    assert_eq!(left, ['a', 'b', 'c']);
    assert_eq!(right, []);
}
```

--------------------------------

### Rust `first_chunk_mut` Example

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Demonstrates how to use `first_chunk_mut` to get a mutable reference to the first `N` elements of a slice and modify them. It also shows the behavior when the slice is shorter than `N`.

```Rust
let x = &mut [0, 1, 2];

if let Some(first) = x.first_chunk_mut::<2>() {
    first[0] = 5;
    first[1] = 4;
}
assert_eq!(x, &[5, 4, 2]);

assert_eq!(None, x.first_chunk_mut::<4>());
```

--------------------------------

### Example: Use first_chunk on Rust Slice

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Demonstrates how to use the `first_chunk` method to extract a fixed-size array reference from the beginning of a slice. Includes examples for successful extraction, insufficient length, and zero-length chunks.

```Rust
let u = [10, 40, 30];
assert_eq!(Some(&[10, 40]), u.first_chunk::<2>());

let v: &[i32] = &[10];
assert_eq!(None, v.first_chunk::<2>());

let w: &[i32] = &[];
assert_eq!(Some(&[]), w.first_chunk::<0>());
```

--------------------------------

### Rust Slice: Example of starts_with Usage

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Demonstrates how to use the `starts_with` method to check if a slice begins with a specified sub-slice, including cases with empty prefixes.

```Rust
let v = [10, 40, 30];
assert!(v.starts_with(&[10]));
assert!(v.starts_with(&[10, 40]));
assert!(v.starts_with(&v));
assert!(!v.starts_with(&[50]));
assert!(!v.starts_with(&[10, 50]));

let v = &[10, 40, 30];
assert!(v.starts_with(&[]);
let v: &[u8] = &[];
assert!(v.starts_with(&[]));
```

--------------------------------

### Example: Use split_last_mut on Rust Slice

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Illustrates how to use `split_last_mut` to get mutable references to the last element and the rest of the slice. Shows how to modify the elements directly through these references.

```Rust
let x = &mut [0, 1, 2];

if let Some((last, elements)) = x.split_last_mut() {
    *last = 3;
    elements[0] = 4;
    elements[1] = 5;
}
assert_eq!(x, &[4, 5, 3]);
```

--------------------------------

### Example: Use split_first_mut on Rust Slice

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Illustrates how to use `split_first_mut` to get mutable references to the first element and the rest of the slice. Shows how to modify the elements directly through these references.

```Rust
let x = &mut [0, 1, 2];

if let Some((first, elements)) = x.split_first_mut() {
    *first = 3;
    elements[0] = 4;
    elements[1] = 5;
}
assert_eq!(x, &[3, 4, 5]);
```

--------------------------------

### NNG Options Module API Reference

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/options/index

Detailed API documentation for the `nng::options` module, outlining its sub-modules, enums, and traits for configuring NNG sockets, dialers, and listeners.

```APIDOC
Module: nng::options

Description: Options available to configure NNG constructs. Many of the options are transport or protocol specific. Additionally, even though the Socket does not have a specific transport, it is able to accept transport options to be used as defaults for any new Dialers or Listeners. Additionally, a Dialer or Listener is able to read options from the underlying Socket but they are unable to write options unless they are directly supported.

Sub-Modules:
  - protocol: Options relating to the socket protocol.
  - transport: Options dealing with the underlying transport.

Enums:
  - LocalAddr: The local address used for communication.
  - MaxTtl: The maximum number of “hops” a message may traverse.
  - Raw: Whether or not the socket is in “raw” mode.
  - ReconnectMaxTime: The maximum amount of time to wait before attempting to establish a connection after a previous attempt has failed.
  - ReconnectMinTime: The minimum amount of time to wait before attempting to establish a connection after a previous attempt has failed.
  - RecvBufferSize: The depth of the socket’s receive buffer as a number of messages.
  - RecvFd: A raw file descriptor that can be used to poll for receiving on a socket.
  - RecvMaxSize: The maximum message size that the will be accepted from a remote peer.
  - RecvTimeout: The socket receive timeout.
  - RemAddr: The remote address of the peer.
  - SendBufferSize: The depth of the socket send buffer as a number of messages.
  - SendFd: A raw file descriptor that can be used to poll for sending on a socket.
  - SendTimeout: The socket send timeout.
  - SocketName: The socket name.
  - Url: The URL with which a listener or dialer was configured.

Traits:
  - GetOpt: Marks that a type can get the specific NNG option.
  - Opt: Marks the type as an NNG option.
  - Options: Trait for getting and setting options.
  - SetOpt: Marks that a type can set the specific NNG option.
```

--------------------------------

### Rust binary_search_by Example Usage

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Message

Example demonstrating the usage of `binary_search_by` on a sorted Rust slice. It shows how to search for existing elements, non-existing elements, and elements with multiple matches, asserting the expected `Ok` or `Err` results. The comparator function `probe.cmp(&seek)` is used to compare elements.

```Rust
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];

let seek = 13;
assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Ok(9));
let seek = 4;
assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(7));
let seek = 100;
assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(13));
let seek = 1;
let r = s.binary_search_by(|probe| probe.cmp(&seek));
assert!(match r { Ok(1..=4) => true, _ => false, });
```

--------------------------------

### Rust Slice: Get Last Element (`last`)

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Message

Provides the API signature and examples for the `last()` method, which returns an immutable reference to the last element of a slice. Returns `None` if the slice is empty.

```APIDOC
pub fn last(&self) -> Option<[&T]>

Returns the last element of the slice, or `None` if it is empty.
```

```Rust
let v = [10, 40, 30];
assert_eq!(Some(&30), v.last());

let w: &[i32] = &[];
assert_eq!(None, w.last());
```

--------------------------------

### Rust nng Pair Protocol Node Example

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Socket

Demonstrates a node using the nng Pair0 protocol. It initializes a socket, dials a URL, and then proceeds to send and receive messages using a helper function.

```Rust
fn node1(url: &str) -> Result<(), Error> {
    let s = Socket::new(Protocol::Pair0)?;
    s.dial(url)?;

    send_recv(&s, "NODE1")
}
```

--------------------------------

### Rust `split_first_chunk_mut` Example

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Demonstrates how to use `split_first_chunk_mut` to get mutable references to the first `N` elements and the rest of a slice, then modify them. It also shows the behavior when the slice is shorter than `N`.

```Rust
let x = &mut [0, 1, 2];

if let Some((first, elements)) = x.split_first_chunk_mut::<2>() {
    first[0] = 3;
    first[1] = 4;
    elements[0] = 5;
}
assert_eq!(x, &[3, 4, 5]);

assert_eq!(None, x.split_first_chunk_mut::<4>());
```

--------------------------------

### nng::Aio Struct API Documentation

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Aio

Detailed API documentation for the `nng::Aio` struct, focusing on its `new` method. It explains how to create an asynchronous I/O handle, the behavior of its callback, and potential errors or panics.

```APIDOC
impl Aio:
  pub fn new<F>(callback: F) -> Result<Self>
    where F: Fn(Aio, AioResult) + Sync + Send + 'static
    Description: Creates a new asynchronous I/O handle. The provided callback will be called on every single I/O event, successful or not. It is possible that the callback will be entered multiple times simultaneously.
    Errors:
      OutOfMemory: Insufficient memory available.
    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.
```

--------------------------------

### Example: Use last_mut on Rust Slice

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Illustrates how to use `last_mut` to get a mutable reference to the last element of a slice. Shows how to modify the element directly and handles empty slices.

```Rust
let x = &mut [0, 1, 2];

if let Some(last) = x.last_mut() {
    *last = 10;
}
assert_eq!(x, &[0, 1, 10]);

let y: &mut [i32] = &mut [];
assert_eq!(None, y.last_mut());
```

--------------------------------

### Mutate Last Chunk of Rust Slice

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Example demonstrating how to use `last_chunk_mut` to get a mutable reference to the last `N` elements of a slice and modify them. Also shows a case where `None` is returned.

```Rust
let x = &mut [0, 1, 2];

if let Some(last) = x.last_chunk_mut::<2>() {
    last[0] = 10;
    last[1] = 20;
}
assert_eq!(x, &[0, 10, 20]);

assert_eq!(None, x.last_chunk_mut::<4>());
```

--------------------------------

### NNG Rust ReqRep Protocol Reply Server Example

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Socket

Demonstrates a reply server using the Rep0 protocol. It waits for commands, processes date requests, calculates the current Unix epoch time, and sends it back as a reply.

```Rust
fn reply(url: &str) -> Result<(), Error> {
    let s = Socket::new(Protocol::Rep0)?;
    s.listen(url)?;

    loop {
        println!("REPLY: WAITING FOR COMMAND");
        let mut msg = s.recv()?;

        let cmd = u64::from_le_bytes(msg[..].try_into().unwrap());
        if cmd != DATE_REQUEST {
            println!("REPLY: UNKNOWN COMMAND");
            continue;
        }

        println!("REPLY: RECEIVED DATE REQUEST");
        let rep = SystemTime::now()
            .duration_since(SystemTime::UNIX_EPOCH)
            .expect("current system time is before Unix epoch")
            .as_secs();

        msg.clear();
        msg.push_back(&rep.to_le_bytes());

        println!("REPLY: SENDING {}", rep);
        s.send(msg)?;
    }
}
```

--------------------------------

### Rust nng Socket listen Method API Documentation

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Socket

Documentation for the `listen` method of the `nng::Socket` type, which initiates and starts a listener on a specified address. It describes its purpose, synchronous binding behavior, and limitations regarding configuration.

```APIDOC
Method: pub fn listen(&self, url: &[str]) -> Result<(), ()>
Description: 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.
Parameters:
  url: &[str] - The address to listen on.
Returns:
  Result<(), ()> - A Result indicating success or an Error.
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.
```

--------------------------------

### Rust `split_last_chunk_mut` Example

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Demonstrates how to use `split_last_chunk_mut` to get mutable references to the remaining elements and the last `N` elements of a slice, then modify them. It also shows the behavior when the slice is shorter than `N`.

```Rust
let x = &mut [0, 1, 2];

if let Some((elements, last)) = x.split_last_chunk_mut::<2>() {
    last[0] = 3;
    last[1] = 4;
    elements[0] = 5;
}
assert_eq!(x, &[5, 3, 4]);

assert_eq!(None, x.split_last_chunk_mut::<4>());
```

--------------------------------

### nng::Aio Struct API Reference

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Aio

Detailed API documentation for the `nng::Aio` struct, an asynchronous I/O context. It includes a description of its purpose, a list of its methods, and various trait implementations.

```APIDOC
Struct: Aio
  Description: An asynchronous I/O context. Asynchronous operations are performed without blocking calling application threads. Instead the application registers a "callback" function to be executed when the operation is complete (whether successfully or not). This callback will be executed exactly once. The callback must not perform any blocking operations and must complete it's execution quickly. If the callback does block, this can lead ultimately to an apparent "hang" or deadlock in the application.
  Methods:
    - cancel
    - new
    - set_timeout
    - sleep
    - wait
  Trait Implementations:
    - Clone
    - Debug
    - Eq
    - Hash
    - PartialEq
  Auto Trait Implementations:
    - Freeze
    - RefUnwindSafe
    - Send
    - Sync
    - Unpin
    - UnwindSafe
  Blanket Implementations:
    - Any
    - Borrow<T>
    - BorrowMut<T>
    - CloneToUninit
    - From<T>
    - Into<U>
    - ToOwned
    - TryFrom<U>
    - TryInto<U>
```

--------------------------------

### Implement GetOpt for ListenerBuilder with Url option

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.ListenerBuilder

Provides the ability to retrieve the `Url` option for `ListenerBuilder` instances, for getting the listener URL.

```Rust
impl GetOpt<Url> for ListenerBuilder
```

--------------------------------

### Rust Slice API: starts_with Method

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Documentation for the `starts_with` method on Rust slices, which checks if a slice begins with a given prefix slice.

```Rust
pub fn starts_with(&self, needle: &[T]) -> bool where T: PartialEq,

Description:
  Returns true if needle is a prefix of the slice or equal to the slice.
```

--------------------------------

### Rust Slice: Copying Elements Within the Same Slice

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Example demonstrating how to use `copy_within` to move a range of elements to a different starting position within the same slice. This method is useful for in-place data rearrangement.

```Rust
let mut bytes = *b"Hello, World!";

bytes.copy_within(1..5, 8);

assert_eq!(&bytes, b"Hello, Wello!");
```

--------------------------------

### Rust Slice `as_rchunks` Example

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Message

Demonstrates how to use `as_rchunks` to split a slice into chunks from the end, returning the remainder at the beginning.

```Rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let (remainder, chunks) = slice.as_rchunks();
assert_eq!(remainder, &['l']);
assert_eq!(chunks, &[['o', 'r'], ['e', 'm']]);
```

--------------------------------

### Rust NNG Publish-Subscribe Subscriber Example

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Socket

Demonstrates a subscriber socket in Rust using the nng library. It dials into a publisher URL, subscribes to all topics, and continuously receives and prints messages, illustrating the publish-subscribe pattern.

```Rust
fn subscriber(url: &str) -> Result<(), nng::Error> {
    let s = Socket::new(Protocol::Sub0)?;
    s.dial(url)?;

    println!("SUBSCRIBER: SUBSCRIBING TO ALL TOPICS");
    let all_topics = vec![];
    s.set_opt::<Subscribe>(all_topics)?;

    loop {
        let msg = s.recv()?;
        let subs = usize::from_le_bytes(msg[..].try_into().unwrap());
        println!("SUBSCRIBER: THERE ARE {} SUBSCRIBERS", subs);
    }
}
```

--------------------------------

### Rust Slice: Get Mutable Last Element (`last_mut`)

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Message

Provides the API signature and examples for the `last_mut()` method, which returns a mutable reference to the last element of a slice. This allows for in-place modification of the element. Returns `None` if the slice is empty.

```APIDOC
pub fn last_mut(&mut self) -> Option<[&mut T]>

Returns a mutable reference to the last item in the slice, or `None` if it is empty.
```

```Rust
let x = &mut [0, 1, 2];

if let Some(last) = x.last_mut() {
    *last = 10;
}
assert_eq!(x, &[0, 1, 10]);

let y: &mut [i32] = &mut [];
assert_eq!(None, y.last_mut());
```

--------------------------------

### Rust Slice: Get Mutable First Element (`first_mut`)

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Message

Provides the API signature and examples for the `first_mut()` method, which returns a mutable reference to the first element of a slice. This allows for in-place modification of the element. Returns `None` if the slice is empty.

```APIDOC
pub fn first_mut(&mut self) -> Option<[&mut T]>

Returns a mutable reference to the first element of the slice, or `None` if it is empty.
```

```Rust
let x = &mut [0, 1, 2];

if let Some(first) = x.first_mut() {
    *first = 5;
}
assert_eq!(x, &[5, 1, 2]);

let y: &mut [i32] = &mut [];
assert_eq!(None, y.first_mut());
```

--------------------------------

### Rust Slice: Using as_rchunks_mut to Split a Slice from the End

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Message

This example illustrates the usage of `as_rchunks_mut` to split a mutable slice into chunks and a remainder, starting the chunking from the end of the slice. It demonstrates modifying both parts and verifying the final slice content.

```Rust
let v = &mut [0, 0, 0, 0, 0];
let mut count = 1;

let (remainder, chunks) = v.as_rchunks_mut();
remainder[0] = 9;
for chunk in chunks {
    *chunk = [count; 2];
    count += 1;
}
assert_eq!(v, &[9, 1, 1, 2, 2]);
```

--------------------------------

### Rust Slice: Get Unchecked Element (Immutable)

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

This example demonstrates how to use `get_unchecked` to access an element of a slice without bounds checking. This method is unsafe and requires an `unsafe` block. It returns an immutable reference to the element at the specified index.

```Rust
let x = &[1, 2, 4];

unsafe {
    assert_eq!(x.get_unchecked(1), &2);
}
```

--------------------------------

### Example: Using Rust Slice binary_search_by_key

Source: https://docs.rs/nng/latest/nng/1.0.1/nng/struct.Header

Demonstrates how to use the `binary_search_by_key` method in Rust to search for elements in a slice of pairs, sorted by their second elements. It shows successful searches, failed searches, and handling multiple matches with `Result::Ok` and `Result::Err`.

```Rust
let s = [(0, 0), (2, 1), (4, 1), (5, 1), (3, 1),
         (1, 2), (2, 3), (4, 5), (5, 8), (3, 13),
         (1, 21), (2, 34), (4, 55)];

assert_eq!(s.binary_search_by_key(&13, |&(a, b)| b),  Ok(9));
assert_eq!(s.binary_search_by_key(&4, |&(a, b)| b),   Err(7));
assert_eq!(s.binary_search_by_key(&100, |&(a, b)| b), Err(13));
let r = s.binary_search_by_key(&1, |&(a, b)| b);
assert!(match r { Ok(1..=4) => true, _ => false, });
```
Tokens:
Raw