### Complete Proxy Service Setup

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/utilities-and-patterns.md

Demonstrates a full setup for a proxy service, binding frontend, backend, and monitor sockets to specific network addresses. This example shows how to initialize and run a proxy in a typical application.

```rust
use zeromq::{proxy, RouterSocket, DealerSocket, PushSocket, Socket};

#[tokio::main]
async fn main() -> zeromq::ZmqResult<()> {
    let mut frontend = RouterSocket::new();
    frontend.bind("tcp://*:5555").await?; // Clients connect here
    
    let mut backend = DealerSocket::new();
    backend.bind("tcp://*:5556").await?; // Workers connect here
    
    let mut monitor = PushSocket::new();
    monitor.bind("tcp://*:5557").await?; // Monitoring clients connect here
    
    println!("Proxy running:");
    println!("  Clients:  tcp://127.0.0.1:5555");
    println!("  Workers:  tcp://127.0.0.1:5556");
    println!("  Monitor:  tcp://127.0.0.1:5557");
    
    proxy(frontend, backend, Some(Box::new(monitor))).await?;
    Ok(())
}
```

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

### Run Default Tokio Example

Source: https://github.com/zeromq/zmq.rs/blob/master/examples/README.md

Execute a ZeroMQ example using the default Tokio asynchronous runtime.

```bash
cargo run --example <example_name>
```

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

### Example Run IDs

Source: https://github.com/zeromq/zmq.rs/blob/master/docs/BENCHMARK_RESULTS.md

Examples of run IDs demonstrating the specified format.

```text
macbook-standard-16ae7d1-20260514T190000Z
c7g-4xlarge-standard-16ae7d1-20260514T190000Z
```

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

### Run Async-Std Example

Source: https://github.com/zeromq/zmq.rs/blob/master/examples/README.md

Execute a ZeroMQ example using the async-std asynchronous runtime by disabling default features and enabling the `async-std-runtime` feature.

```bash
cargo run --example <example_name> --no-default-features --features async-std-runtime
```

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

### Install ZeroMQ Development Libraries (Linux)

Source: https://github.com/zeromq/zmq.rs/blob/master/docs/BENCHMARKS.md

Install the ZeroMQ development libraries on Linux systems using apt-get.

```sh
sudo apt-get install libzmq3-dev
```

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

### Install ZeroMQ (macOS)

Source: https://github.com/zeromq/zmq.rs/blob/master/docs/BENCHMARKS.md

Install ZeroMQ on macOS using the Homebrew package manager.

```sh
brew install zeromq
```

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

### RepSocket Receive Example

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/request-reply-sockets.md

Shows how to continuously receive request messages using RepSocket. This example runs in a loop, printing each received request and handling potential errors.

```rust
use zeromq::{RepSocket, Socket, SocketRecv};

let mut socket = RepSocket::new();
socket.bind("tcp://*:5555").await?;

loop {
    match socket.recv().await {
        Ok(request) => println!("Request: {:?}", request),
        Err(e) => eprintln!("Error: {}", e),
    }
}
```

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

### Archive Location Example

Source: https://github.com/zeromq/zmq.rs/blob/master/docs/BENCHMARK_RESULTS.md

An example of an S3 prefix for storing benchmark archives, useful for distributed agent runs.

```text
s3://<bucket>/zmq.rs/perf-runs/<run-id>/zmqrs-perf-<run-id>.tar.gz
```

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

### Weather Service Example

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/pub-sub-sockets.md

Demonstrates a complete Publish-Subscribe system with a weather server (PubSocket) and clients (SubSocket) for specific cities.

```rust
use zeromq::{PubSocket, SubSocket, Socket, SocketSend, SocketRecv};
use bytes::Bytes;

async fn weather_server() -> zeromq::ZmqResult<()> {
    let mut socket = PubSocket::new();
    socket.bind("tcp://*:5555").await?;
    
    loop {
        // Publish NYC weather
        let mut msg = zeromq::ZmqMessage::from("weather.nyc");
        msg.push_back(Bytes::from("25C"));
        socket.send(msg).await?;
        
        // Publish LA weather
        let mut msg = zeromq::ZmqMessage::from("weather.la");
        msg.push_back(Bytes::from("30C"));
        socket.send(msg).await?;
        
        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
    }
}

async fn weather_client(city: &str) -> zeromq::ZmqResult<()> {
    let mut socket = SubSocket::new();
    let topic = format!("weather.{}", city);
    socket.subscribe(&topic).await?;
    socket.connect("tcp://localhost:5555").await?;
    
    for _ in 0..10 {
        let msg = socket.recv().await?;
        println!("{}: {{:?}}", city, msg);
    }
    Ok(())
}
```

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

### Integrate with async-std Async Runtime

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/utilities-and-patterns.md

Example of switching to the async-std async runtime with the ZeroMQ Rust crate.

```rust
// With async-std
#[async_std::main]
async fn main() {
    // code
}
```

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

### Integrate with Tokio Async Runtime

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/utilities-and-patterns.md

Example of using the default Tokio async runtime with the ZeroMQ Rust crate.

```rust
// With tokio (default)
#[tokio::main]
async fn main() {
    // code
}
```

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

### Full Publish-Subscribe Example

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/pub-sub-sockets.md

Demonstrates the complete Publish-Subscribe pattern with a publisher sending messages periodically and a subscriber receiving and printing them. Requires both publisher and subscriber to be run.

```rust
use zeromq::{PubSocket, SubSocket, Socket, SocketSend, SocketRecv};
use bytes::Bytes;

// Publisher
async fn run_publisher() -> zeromq::ZmqResult<()> {
    let mut socket = PubSocket::new();
    socket.bind("tcp://*:5555").await?;
    
    loop {
        let mut msg = zeromq::ZmqMessage::from("weather");
        msg.push_back(Bytes::from("sunny"));
        socket.send(msg).await?;
        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
    }
}

// Subscriber
async fn run_subscriber() -> zeromq::ZmqResult<()> {
    let mut socket = SubSocket::new();
    socket.subscribe("weather").await?;
    socket.connect("tcp://localhost:5555").await?;
    
    while let Ok(msg) = socket.recv().await {
        println!("Received: {:?}", msg);
    }
    Ok(())
}
```

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

### Basic RouterSocket usage example

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/request-reply-sockets.md

This example demonstrates receiving a message with RouterSocket and sending a reply. The first frame of the received message is the client's identity, which must be prepended to the reply.

```rust
use zeromq::{RouterSocket, Socket, SocketRecv, SocketSend};

let mut socket = RouterSocket::new();
socket.bind("tcp://*:5555").await?;

let mut msg = socket.recv().await?;
// msg.get(0) is the client identity
// Reply must also have identity as first frame
socket.send(msg).await?;
```

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

### Example: Create PeerIdentity from Bytes

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/types.md

Demonstrates creating a PeerIdentity from a Bytes object. This is useful when receiving identity data over the network.

```rust
use zeromq::util::PeerIdentity;
use bytes::Bytes;
use std::convert::TryFrom;

let id = PeerIdentity::try_from(Bytes::from("my-peer"))?;
```

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

### Example: Get Peer Identity as Byte Slice

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/types.md

Shows how to obtain the byte slice representation of a PeerIdentity. This is commonly used when interacting with lower-level network functions.

```rust
let id = PeerIdentity::new();
let bytes: &[u8] = id.as_ref();
```

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

### Example: Convert PeerIdentity to Bytes

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/types.md

Shows how to convert a PeerIdentity into a Bytes object. This is often a necessary step before transmitting the identity.

```rust
let id = PeerIdentity::new();
let bytes: Bytes = id.into();
```

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

### Example: Create and Print Peer Identity

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/types.md

Demonstrates how to create a new random PeerIdentity and print its byte representation. This is useful for debugging and verifying identity generation.

```rust
use zeromq::util::PeerIdentity;

let id = PeerIdentity::new();
println!("ID: {:?}", id.as_ref());
```

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

### Endpoint Error Handling Examples

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/endpoints.md

Provides examples of common endpoint parsing errors, including invalid ports, unknown transports, and syntax errors.

```rust
use zeromq::Endpoint;

// Invalid port
"tcp://127.0.0.1:99999".parse::<Endpoint>() // Syntax error
    .expect_err("Port out of range");

// Unknown transport
"http://example.com:8000".parse::<Endpoint>()
    .expect_err("Unknown transport");

// Missing port
"tcp://127.0.0.1".parse::<Endpoint>()
    .expect_err("Syntax error");
```

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

### Monitor Socket Events Example

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/types.md

Demonstrates how to monitor socket events, such as listening, accepted connections, and disconnections. This is crucial for managing socket lifecycle and peer interactions.

```rust
use zeromq::{Socket, PushSocket};

let mut socket = PushSocket::new();
let mut events = socket.monitor();

socket.bind("tcp://*:5555").await?;

while let Some(event) = events.recv().await {
    match event {
        zeromq::SocketEvent::Listening(ep) => {
            println!("Now listening on {}", ep);
        }
        zeromq::SocketEvent::Accepted(ep, peer) => {
            println!("Accepted connection from {} at {}", 
                     String::from_utf8_lossy(peer.as_ref()), ep);
        }
        zeromq::SocketEvent::Disconnected(_) => {
            println!("Peer disconnected");
        }
        _ => {}
    }
}
```

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

### Example: Create PeerIdentity from Byte Slice

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/types.md

Shows how to create a PeerIdentity directly from a byte slice literal. This is useful for static identity definitions.

```rust
let id = PeerIdentity::try_from(b"my-peer" as &[u8])?;
```

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

### IPC Endpoint Binding Example

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/endpoints.md

Shows how to bind a ZeroMQ socket to an IPC (Inter-Process Communication) endpoint on Unix-like systems.

```rust
use zeromq::{Socket, PushSocket};

let mut socket = PushSocket::new();
socket.bind("ipc:///tmp/zmq-socket").await?;
```

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

### Wildcard TCP Binding Example

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/endpoints.md

Demonstrates binding a ZeroMQ socket to a wildcard host ('*') and port 0, which results in an ephemeral port being assigned.

```rust
use zeromq::{Socket, PushSocket};

let mut socket = PushSocket::new();
let endpoint = socket.bind("tcp://*:0").await?; // Port 0 = ephemeral
println!("Bound to: {}", endpoint); // Actual resolved address
```

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

### Example: Create PeerIdentity from Vec<u8>

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/types.md

Demonstrates creating a PeerIdentity from a Vec<u8>. This is common when processing data that has been collected into a vector.

```rust
let id = PeerIdentity::try_from("my-peer".as_bytes().to_vec())?;
```

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

### Example: Convert PeerIdentity to Vec<u8>

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/types.md

Demonstrates converting a PeerIdentity into a Vec<u8>. This can be useful for various data manipulation tasks.

```rust
let id = PeerIdentity::new();
let vec: Vec<u8> = id.into();
```

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

### ReqSocket Receive Example

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/request-reply-sockets.md

Shows how to receive a reply message after sending a request with ReqSocket. This call blocks until a reply is available.

```rust
use zeromq::{ReqSocket, Socket, SocketSend, SocketRecv};

let mut socket = ReqSocket::new();
socket.connect("tcp://localhost:5555").await?;

socket.send("Request".into()).await?;
let reply = socket.recv().await?;
```

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

### Request-Reply Pattern Example

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/request-reply-sockets.md

Illustrates the complete request-reply pattern with both a server (RepSocket) and a client (ReqSocket). The server binds to an address and handles incoming requests, while the client connects and sends requests, then receives replies.

```rust
use zeromq::{ReqSocket, RepSocket, Socket, SocketSend, SocketRecv};

// Server
async fn run_server() -> zeromq::ZmqResult<()> {
    let mut socket = RepSocket::new();
    socket.bind("tcp://*:5555").await?;
    
    while let Ok(request) = socket.recv().await {
        println!("Received: {:?}", request);
        socket.send("Response".into()).await?;
    }
    Ok(())
}

// Client
async fn run_client() -> zeromq::ZmqResult<()> {
    let mut socket = ReqSocket::new();
    socket.connect("tcp://localhost:5555").await?;
    
    socket.send("Request".into()).await?;
    let reply = socket.recv().await?;
    println!("Got reply: {:?}", reply);
    Ok(())
}
```

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

### RepSocket Send Example

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/request-reply-sockets.md

Demonstrates sending a reply message using RepSocket. This should be called after receiving a request. Ensure the socket is bound to an endpoint.

```rust
use zeromq::{RepSocket, Socket, SocketRecv, SocketSend};

let mut socket = RepSocket::new();
socket.bind("tcp://*:5555").await?;

let request = socket.recv().await?;
socket.send("Reply".into()).await?;
```

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

### Example: Parse PeerIdentity from String

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/types.md

Shows how to parse a PeerIdentity from a string using the FromStr trait. This is a convenient way to initialize identities.

```rust
use zeromq::util::PeerIdentity;
use std::str::FromStr;

let id = PeerIdentity::from_str("my-service")?;
```

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

### Abstract Namespace IPC Binding Example

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/endpoints.md

Illustrates binding an IPC socket to the abstract namespace on Linux using the '@' prefix.

```rust
socket.bind("ipc://@myservice").await?;
```

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

### Run All Cargo Benchmarks

Source: https://github.com/zeromq/zmq.rs/blob/master/docs/BENCHMARKS.md

Execute all benchmarks defined in the Cargo project without running them. This is typically a setup step before running specific benchmarks.

```sh
cargo bench --no-run
```

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

### Create Socket with Custom Options

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/configuration.md

Creates a PushSocket with a modified SocketOptions object. This example sets a custom connection timeout of 60 seconds.

```rust
use zeromq::{PushSocket, Socket, SocketOptions};
use std::time::Duration;

let mut opts = SocketOptions::default();
opts.connect_timeout(Duration::from_secs(60));

let socket = PushSocket::with_options(opts);
```

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

### Handling ConnectTimeout Error

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/errors.md

This example illustrates how to handle a `ConnectTimeout` error, which occurs when a connection attempt exceeds the configured timeout. It provides feedback on the duration of the timeout.

```rust
match socket.connect("tcp://unreachable-host:5555").await {
    Ok(()) => println!("Connected"),
    Err(ZmqError::ConnectTimeout(duration)) => {
        eprintln!("Connection timed out after {:?}", duration);
    }
    Err(e) => return Err(e),
}
```

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

### Set Custom Connection Timeout

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/configuration.md

Demonstrates setting a custom connection timeout for a socket using `connect_timeout`. Examples show setting a 1-minute and a 5-second timeout.

```rust
use zeromq::{Socket, SocketOptions};
use std::time::Duration;

let mut opts = SocketOptions::default();

// 1 minute timeout
opts.connect_timeout(Duration::from_secs(60));

// 5 second timeout
opts.connect_timeout(Duration::from_secs(5));

let socket = PushSocket::with_options(opts);
```

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

### Configure Build Features for zeromq.rs

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/INDEX.md

Specify zeromq.rs version and enable/disable features like async runtimes and transports in your Cargo.toml. This example shows custom configuration for async-std and TCP.

```toml
# Default: tokio + all transports
zeromq = "0.6"

# Custom: async-std + TCP only
zeromq = { version = "0.6", default-features = false, features = ["async-std-runtime", "tcp-transport"] }

# With macros for async-dispatcher
zeromq = { version = "0.6", features = ["async-dispatcher-macros"] }
```

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

### ReqSocket Send Example

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/request-reply-sockets.md

Demonstrates sending a request message using ReqSocket. Ensure a REP or ROUTER socket is connected to the specified endpoint.

```rust
use zeromq::{ReqSocket, Socket, SocketSend};

let mut socket = ReqSocket::new();
socket.connect("tcp://localhost:5555").await?;
socket.send("Hello".into()).await?;
```

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

### Specify zmq.rs with async-std and all transports

Source: https://github.com/zeromq/zmq.rs/blob/master/README.md

Configure your Cargo.toml to use zmq.rs with the async-std runtime and enable all transport mechanisms. This is an example of how to customize dependency features.

```toml
zeromq = { version = "*", default-features = false, features = ["async-std-runtime", "all-transport"] }
```

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

### Monitor Socket Events

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/configuration.md

Create a socket monitor to receive lifecycle events. This example demonstrates binding a PushSocket and processing Listening, Accepted, ConnectDelayed, and Disconnected events.

```rust
use zeromq::{Socket, PushSocket};

let mut socket = PushSocket::new();
let mut events = socket.monitor();

socket.bind("tcp://*:5555").await?;

while let Some(event) = events.recv().await {
    match event {
        zeromq::SocketEvent::Listening(ep) => {
            println!("Listening on {}", ep);
        }
        zeromq::SocketEvent::Accepted(ep, peer) => {
            println!("Accepted connection from {} at {}", 
                     String::from_utf8_lossy(peer.as_ref()), ep);
        }
        zeromq::SocketEvent::ConnectDelayed => {
            println!("Connection delayed, will retry");
        }
        zeromq::SocketEvent::Disconnected(_) => {
            println!("Peer disconnected");
        }
        _ => {}
    }
}
```

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

### Create and Send ZmqMessage with Multiple Frames

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/INDEX.md

Demonstrates how to construct a ZmqMessage by adding multiple frames, starting with an initial frame. This is useful for sending complex data structures.

```rust
let mut msg = ZmqMessage::from("frame1");
msg.push_back(Bytes::from("frame2"));
msg.push_back(Bytes::from("frame3"));
```

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

### Handling NoMessage Error

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/errors.md

This example shows how to gracefully handle the `NoMessage` error, which occurs when no message is available from the socket. It suggests retrying or handling the situation without crashing.

```rust
match socket.recv().await {
    Ok(msg) => process(msg),
    Err(ZmqError::NoMessage) => {
        // No message available; can retry or handle gracefully
        eprintln!("No message available");
    }
    Err(e) => return Err(e),
}
```

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

### Displaying Host as String

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/endpoints.md

Shows how to format a Host into its string representation.

```rust
use zeromq::Host;

let host = Host::Domain("example.com".to_string());
println!("{}", host); // example.com

let host: Host = "::1".parse()?;
println!("{}", host); // ::1
```

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

### Run Compare Libzmq Benchmark

Source: https://github.com/zeromq/zmq.rs/blob/master/docs/BENCHMARKS.md

Execute the 'compare_libzmq' benchmark to compare latency cases (PUB/SUB, REQ/REP, PUSH/PULL, DEALER/ROUTER) side-by-side with libzmq. It uses a specific sample size.

```sh
cargo bench --bench compare_libzmq -- --sample-size 10
```

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

### Minimal Binary Configuration

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/configuration.md

Create a minimal binary by using only the TCP transport and essential Tokio features. Eliminates IPC and unused async runtimes.

```toml
[dependencies]
zeromq = { version = "0.6", default-features = false, features = ["tokio-runtime", "tcp-transport"] }
tokio = { version = "1", features = ["rt-multi-thread"] }
```

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

### Get ZmqMessage Frame Count

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/message.md

Returns the number of frames currently in the ZmqMessage.

```rust
use zeromq::ZmqMessage;

let msg = ZmqMessage::from("hello");
assert_eq!(msg.len(), 1);
```

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

### Getting Transport Type from Endpoint

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/endpoints.md

Retrieves the transport type (TCP or IPC) from an Endpoint instance.

```rust
use zeromq::{Endpoint, Transport};

let ep = "tcp://localhost:5555".parse::<Endpoint>()?;
assert_eq!(ep.transport(), Transport::Tcp);
```

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

### get()

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/message.md

Retrieves a reference to a frame at a specific index within the ZmqMessage. Returns None if the index is out of bounds.

```APIDOC
## get()

### Description
Returns a reference to a frame at the given index.

### Method
`get(&self, index: usize) -> Option<&Bytes>`

### Parameters
#### Path Parameters
- **index** (`usize`) - Required - Frame index

### Return
- **Option<&Bytes>** - Frame reference or `None` if index out of bounds

### Request Example
```rust
use zeromq::ZmqMessage;

let msg = ZmqMessage::from("hello");
if let Some(frame) = msg.get(0) {
    println!("{:?}", frame);
}
```
```

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

### Basic Publish-Subscribe Publisher

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/INDEX.md

Sets up a PubSocket to bind to a TCP address and send a message. Requires tokio runtime.

```rust
use zeromq::{PubSocket, SubSocket, Socket, SocketSend, SocketRecv};

// Publisher
#[tokio::main]
async fn main() {
    let mut socket = PubSocket::new();
    socket.bind("tcp://*:5555").await.unwrap();
    
    socket.send("weather.nyc: 25°C".into()).await.unwrap();
}
```

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

### Get a frame by index

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/message.md

Retrieves a reference to a frame at a specific index. Returns None if the index is out of bounds.

```rust
use zeromq::ZmqMessage;

let msg = ZmqMessage::from("hello");
if let Some(frame) = msg.get(0) {
    println!("{:?}", frame);
}
```

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

### Basic Request-Reply Server

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/INDEX.md

Sets up a RepSocket to bind to a TCP address, receive a request, and send a response. Requires tokio runtime.

```rust
use zeromq::{ReqSocket, RepSocket, Socket, SocketSend, SocketRecv};

// Server
#[tokio::main]
async fn main() {
    let mut socket = RepSocket::new();
    socket.bind("tcp://*:5555").await.unwrap();
    
    let request = socket.recv().await.unwrap();
    println!("Request: {:?}", request);
    
    socket.send("Response".into()).await.unwrap();
}
```

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

### Basic Request-Reply Client

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/INDEX.md

Sets up a ReqSocket to connect to a TCP address, send a request, and receive a reply. Requires tokio runtime.

```rust
use zeromq::{ReqSocket, RepSocket, Socket, SocketSend, SocketRecv};

// Client
#[tokio::main]
async fn main() {
    let mut socket = ReqSocket::new();
    socket.connect("tcp://localhost:5555").await.unwrap();
    
    socket.send("Request".into()).await.unwrap();
    let reply = socket.recv().await.unwrap();
    println!("Reply: {:?}", reply);
}
```

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

### Run Performance Suite with OMQ Implementation

Source: https://github.com/zeromq/zmq.rs/blob/master/docs/BENCHMARKS.md

Run the performance suite using the OMQ implementation. OMQ is cloned into target/perf-deps/omq.rs at the revision specified in perf-suite.json or via --omq-rev.

```sh
python3 scripts/run_perf_suite.py --profile smoke --impl omq --transport tcp
```

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

### Async-std with Minimal Transport Configuration

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/configuration.md

Use async-std as the runtime with only TCP transport enabled. This results in a smaller dependency tree compared to using Tokio with all features.

```toml
[dependencies]
zeromq = { version = "0.6", default-features = false, features = ["async-std-runtime", "tcp-transport"] }
async-std = { version = "1", features = ["attributes"] }

#[async_std::main] async fn main() {
    // code
}
```

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

### Prelude Module

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/utilities-and-patterns.md

The prelude module provides a convenient glob import for common types and traits, making them available without needing to specify their full paths.

```APIDOC
## Prelude Module

Convenient glob import for common types and traits.

**Source:** `src/lib.rs` (lines 418–422)

```rust
pub mod prelude {
    pub use crate::{Socket, SocketRecv, SocketSend, TryIntoEndpoint};
}
```

### Usage

```rust
use zeromq::prelude::*;

// Now available without full paths:
// - Socket trait
// - SocketRecv trait
// - SocketSend trait
// - TryIntoEndpoint trait
```
```

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

### Get Socket Type as String

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/socket-types.md

Converts a SocketType enum variant into its static string representation. Useful for logging or display purposes.

```rust
let socket_type = SocketType::PUB;
println!("{}", socket_type.as_str()); // Output: "PUB"
```

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

### Configure Async-dispatcher Runtime

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/configuration.md

Enable async-dispatcher-runtime and async-dispatcher-macros for the async-dispatcher runtime. Requires async-dispatcher dependency.

```toml
[dependencies]
zeromq = { version = "0.6", default-features = false, features = ["async-dispatcher-runtime", "async-dispatcher-macros"] }
async-dispatcher = { version = "0.1", features = ["macros"] }
```

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

### Configure ZeroMQ Rust Crate with Cargo.toml

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/utilities-and-patterns.md

Illustrates how to specify ZeroMQ crate features in `Cargo.toml` to enable specific async runtimes and transports.

```toml
# Default (tokio + all transports)
zeromq = "0.6"

# Async-std without IPC
zeromq = { version = "0.6", default-features = false, features = ["async-std-runtime", "tcp-transport"] }
```

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

### Basic Pipeline Consumer

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/INDEX.md

Sets up a PullSocket to connect to a TCP address and continuously receive and process messages. Requires tokio runtime.

```rust
use zeromq::{PushSocket, PullSocket, Socket, SocketSend, SocketRecv};

// Consumer
#[tokio::main]
async fn main() {
    let mut socket = PullSocket::new();
    socket.connect("tcp://localhost:5555").await.unwrap();
    
    while let Ok(msg) = socket.recv().await {
        println!("Processing: {:?}", msg);
    }
}
```

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

### Basic Pipeline Producer

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/INDEX.md

Sets up a PushSocket to bind to a TCP address and send a series of messages. Requires tokio runtime.

```rust
use zeromq::{PushSocket, PullSocket, Socket, SocketSend, SocketRecv};

// Producer
#[tokio::main]
async fn main() {
    let mut socket = PushSocket::new();
    socket.bind("tcp://*:5555").await.unwrap();
    
    for i in 0..100 {
        socket.send(format!("task-{}", i).into()).await.unwrap();
    }
}
```

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

### Run Performance Suite

Source: https://github.com/zeromq/zmq.rs/blob/master/docs/BENCHMARKS.md

Execute the performance suite with specified profiles, implementations, and transports. Results are normalized and can be compared against a pinned OMQ clone.

```sh
python3 scripts/run_perf_suite.py --profile smoke --impl zmqrs,libzmq --transport tcp
python3 scripts/report_perf_suite.py target/perf-runs/<run-id>
```

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

### Bind PushSocket to Endpoint

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/socket-core.md

Binds a PushSocket to a specified network endpoint and starts listening for incoming connections. The returned Endpoint provides the resolved address.

```rust
use zeromq::{PushSocket, Socket};

let mut socket = PushSocket::new();
let endpoint = socket.bind("tcp://*:5555").await?;
println!("Bound to: {}", endpoint); // tcp://127.0.0.1:5555
```

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

### Create Socket with Default Options

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/configuration.md

Instantiates a PushSocket using default configuration options. This includes auto-generated peer identity and a 30-second connection timeout.

```rust
use zeromq::{PushSocket, Socket};

let socket = PushSocket::new();
// Uses: no custom identity, 30 second timeout
```

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

### Basic Publish-Subscribe Subscriber

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/INDEX.md

Sets up a SubSocket to subscribe to a topic, connect to a publisher, and receive messages. Requires tokio runtime.

```rust
use zeromq::{PubSocket, SubSocket, Socket, SocketSend, SocketRecv};

// Subscriber
#[tokio::main]
async fn main() {
    let mut socket = SubSocket::new();
    socket.subscribe("weather").await.unwrap();
    socket.connect("tcp://localhost:5555").await.unwrap();
    
    let msg = socket.recv().await.unwrap();
    println!("Update: {:?}", msg);
}
```

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

### Full Cargo Build Configuration

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/configuration.md

Compile the project with all default features enabled. This is the standard build command for including all available functionalities.

```bash
cargo build --release
```

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

### Handling Network Binding Errors

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/errors.md

Recover from network-level failures like 'port already in use' when binding a socket. This example demonstrates retrying on a different port.

```rust
match socket.bind("tcp://*:5555").await {
    Ok(ep) => println!("Bound to {}", ep),
    Err(ZmqError::Network(io_err)) if io_err.kind() == std::io::ErrorKind::AddrInUse => {
        eprintln!("Port already in use, trying next port");
    }
    Err(e) => return Err(e),
}
```

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

### Production Server Configuration

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/configuration.md

Configure for a production server with all transports enabled and full Tokio functionality. Includes logging support.

```toml
[dependencies]
zeromq = "0.6"  # Default: tokio + TCP + IPC
tokio = { version = "1", features = ["full"] }
log = "0.4"
```

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

### Socket::with_options

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/socket-core.md

Creates a new socket with custom configuration options. Allows for fine-grained control over socket behavior during initialization.

```APIDOC
## Socket::with_options

### Description
Creates a new socket with custom options.

### Method
`with_options(options: SocketOptions) -> Self`

### Parameters
#### Request Body
- **options** (`SocketOptions`) - Required - Configuration options for the socket

### Return
- `Self`: A new socket instance with specified options

### Example
```rust
use zeromq::{PushSocket, Socket, SocketOptions};
use std::time::Duration;

let mut opts = SocketOptions::default();
opts.connect_timeout(Duration::from_secs(60));
let socket = PushSocket::with_options(opts);
```
```

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

### Configure Async-std Runtime

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/configuration.md

Use the async-std-runtime feature for async-std. Requires explicit dependency on async-std and an async main function.

```toml
[dependencies]
zeromq = { version = "0.6", default-features = false, features = ["async-std-runtime"] }
async-std = { version = "1", features = ["attributes"] }

#[async_std::main] async fn main() {
    // code
}
```

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

### Run Throughput Benchmark

Source: https://github.com/zeromq/zmq.rs/blob/master/docs/BENCHMARKS.md

Execute the 'throughput' benchmark, which measures batched PUB fanout and DEALER/ROUTER throughput. It uses a specific sample size.

```sh
cargo bench --bench throughput -- --sample-size 10
```

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

### Prelude Usage

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/socket-core.md

Re-exports frequently used items for convenience.

```APIDOC
## Prelude

Re-exports frequently used items:

```rust
pub mod prelude {
    pub use crate::{Socket, SocketRecv, SocketSend, TryIntoEndpoint};
}
```

**Usage:**
```rust
use zeromq::prelude::*;
```
```

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

### Check Socket Type Compatibility

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/socket-types.md

Determines if two socket types can communicate with each other based on ZeroMQ's pairing rules. Ensures proper setup for peer-to-peer communication.

```rust
use zeromq::SocketType;

assert!(SocketType::PUB.compatible(SocketType::SUB));
assert!(SocketType::REQ.compatible(SocketType::REP));
assert!(SocketType::DEALER.compatible(SocketType::ROUTER));
assert!(!SocketType::PUB.compatible(SocketType::REP));
```

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

### IPv6 Endpoint Binding and Connecting

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/endpoints.md

Demonstrates binding and connecting to ZeroMQ endpoints using IPv6 addresses, which require brackets around the address.

```rust
socket.bind("tcp://[::1]:5555").await?;
socket.connect("tcp://[2001:db8::1]:5555").await?;
```

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

### Handling BufferFull Errors

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/errors.md

Recover when the internal message queue is full, indicating a channel send failure. This example shows logging the error and considering backpressure or message dropping.

```rust
match socket.send(message).await {
    Ok(()) => println!("Message sent"),
    Err(ZmqError::BufferFull(msg)) => {
        eprintln!("Queue full: {}", msg);
        // Could implement backpressure or drop the message
    }
    Err(e) => return Err(e),
}
```

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

### Prelude Import for Common ZMQ Types and Traits

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/utilities-and-patterns.md

Provides a convenient glob import for essential types and traits, allowing them to be used without full paths.

```rust
pub mod prelude {
    pub use crate::{Socket, SocketRecv, SocketSend, TryIntoEndpoint};
}
```

```rust
use zeromq::prelude::*;

// Now available without full paths:
// - Socket trait
// - SocketRecv trait
// - SocketSend trait
// - TryIntoEndpoint trait
```

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

### Message Proxy with ROUTER and DEALER Sockets

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/INDEX.md

A message proxy relays messages between a frontend (ROUTER) and a backend (DEALER) socket. This setup is useful for managing complex message flows.

```rust
let frontend = RouterSocket::new();
let backend = DealerSocket::new();

frontend.bind("tcp://*:5555").await?;
backend.bind("tcp://*:5556").await?;

proxy(frontend, backend, None).await?;
```

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

### Configure Long Connection Timeout for Unreliable Networks

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/configuration.md

Set a prolonged connection timeout using `SocketOptions::connect_timeout` to handle unstable network conditions. This example sets a 5-minute timeout.

```rust
use zeromq::{Socket, SocketOptions};
use std::time::Duration;

let mut opts = SocketOptions::default();
opts.connect_timeout(Duration::from_secs(300)); // 5 minutes

let socket = PushSocket::with_options(opts);
socket.connect("tcp://remote-service:5555").await?;
```

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

### Handling ZmqError::ReturnToSender

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/INDEX.md

Example of handling a `ReturnToSender` error during message sending. This specific error indicates the message could not be delivered and provides a reason. The code demonstrates requeueing the message for a retry.

```rust
match socket.send(message).await {
    Ok(()) => println!("Sent"),
    Err(ZmqError::ReturnToSender { reason, message }) => {
        eprintln!("Failed to send: {}", reason);
        queue.push(message); // Queue for retry
    }
    Err(e) => eprintln!("Error: {}", e),
}
```

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

### SubSocket subscribe()

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/pub-sub-sockets.md

Adds a subscription filter to the SUB socket. The socket will then receive messages whose first frame starts with the specified subscription string. An empty string subscription matches all messages.

```APIDOC
## SubSocket subscribe()

### Description
Adds a subscription filter. The socket will receive messages whose first frame starts with the subscription string.

### Method
`subscribe()`

### Parameters
#### Request Body
- **subscription** (`&str`) - Required - Subscription prefix to match (as UTF-8 string)

### Response
#### Success Response
- **`ZmqResult<()>`** - Success or error

### Example
```rust
use zeromq::{SubSocket, Socket};

let mut socket = SubSocket::new();
socket.subscribe("weather.nyc").await?;
socket.subscribe("weather.la").await?;
socket.subscribe("sports").await?;
socket.connect("tcp://localhost:5555").await?;
```
```

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

### Create New PushSocket

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/socket-core.md

Creates a new PushSocket instance with default options. Use this for basic socket creation when no special configuration is needed.

```rust
use zeromq::{PushSocket, Socket};

let socket = PushSocket::new();
```

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

### Parse Host from String

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/endpoints.md

Shows how to parse a Host from a string using FromStr or TryFrom. It handles IPv4, IPv6 (with or without brackets), and domain names. Empty strings are rejected.

```rust
impl FromStr for Host {
    type Err = EndpointError;
}

impl TryFrom<String> for Host {
    type Error = EndpointError;
}
```

```rust
use zeromq::Host;
use std::str::FromStr;

let host: Host = "127.0.0.1".parse()?; // IPv4
let host: Host = "::1".parse()?; // IPv6 without brackets
let host: Host = "[::1]".parse()?; // IPv6 with brackets
let host: Host = "example.com".parse()?; // Domain name
```

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

### Socket::new

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/socket-core.md

Creates a new socket with default options. This is a constructor for creating new socket instances.

```APIDOC
## Socket::new

### Description
Creates a new socket with default options.

### Method
`new()`

### Return
- `Self`: A new socket instance

### Example
```rust
use zeromq::{PushSocket, Socket};

let socket = PushSocket::new();
```
```

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

### Displaying Endpoint as String

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/endpoints.md

Shows how to format an Endpoint into its string representation for display.

```rust
let ep = Endpoint::Tcp(Host::Ipv4("127.0.0.1".parse()?),
 5555);
println!("{}", ep); // tcp://127.0.0.1:5555

let ep = Endpoint::Tcp(Host::Ipv6("::1".parse()?),
 5555);
println!("{}", ep); // tcp://[::1]:5555
```

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

### Configure Tokio Runtime

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/configuration.md

Specify the tokio-runtime feature for using the Tokio async runtime. This is the default.

```toml
zeromq = "0.6"

# Explicit
zeromq = { version = "0.6", features = ["tokio-runtime"] }
```

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

### Package and Share Performance Runs

Source: https://github.com/zeromq/zmq.rs/blob/master/docs/BENCHMARK_RESULTS.md

Use these commands to run the performance suite and package the results for sharing. The package script creates a compressed archive of the benchmark run.

```sh
python3 scripts/run_perf_suite.py --profile standard --impl zmqrs,libzmq,omq --transport tcp,ipc --run-id <run-id>
python3 scripts/package_perf_run.py target/perf-runs/<run-id>
```

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

### Run Codec Benchmark

Source: https://github.com/zeromq/zmq.rs/blob/master/docs/BENCHMARKS.md

Execute the 'codec' benchmark, which focuses on encode/decode microbenchmarks. It uses a specific sample size for measurement.

```sh
cargo bench --bench codec -- --sample-size 10
```

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

### Run Comprehensive Performance Suite

Source: https://github.com/zeromq/zmq.rs/blob/master/docs/BENCHMARKS.md

Execute a decision-making local run with multiple implementations and transports to compare performance across different configurations.

```sh
python3 scripts/run_perf_suite.py --profile standard --impl zmqrs,libzmq,omq --transport tcp,ipc
```

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

### Minimal Cargo Build Configuration

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/configuration.md

Compile the project with minimal features, disabling defaults and explicitly enabling only the tokio runtime and TCP transport. This reduces binary size and dependencies.

```bash
cargo build --release --no-default-features --features "tokio-runtime,tcp-transport"
```

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

### Create and Access ZeroMQ Messages

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/utilities-and-patterns.md

Demonstrates creating single and multi-frame ZeroMQ messages using `ZmqMessage` and accessing individual frames.

```rust
use zeromq::ZmqMessage;
use bytes::Bytes;

// Single frame (convenience)
let msg = ZmqMessage::from("hello");
assert_eq!(msg.len(), 1);

// Multi-frame
let mut msg = ZmqMessage::from("header");
msg.push_back(Bytes::from("body"));
assert_eq!(msg.len(), 2);

// Access frames
if let Some(frame) = msg.get(0) {
    println!("First frame: {:?}", frame);
}

// Iterate
for (i, frame) in msg.iter().enumerate() {
    println!("Frame {}: {} bytes", i, frame.len());
}
```

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

### Create PushSocket with Custom Options

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/socket-core.md

Creates a new PushSocket with custom configuration options, such as connection timeouts. Useful for fine-tuning socket behavior.

```rust
use zeromq::{PushSocket, Socket, SocketOptions};
use std::time::Duration;

let mut opts = SocketOptions::default();
opts.connect_timeout(Duration::from_secs(60));
let socket = PushSocket::with_options(opts);
```

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

### SocketOptions Defaults

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/socket-core.md

Default configuration for SocketOptions.

```APIDOC
## Defaults

```rust
implement Default for SocketOptions {
    fn default() -> Self {
        Self {
            peer_id: None,
            connect_timeout: Some(DEFAULT_CONNECT_TIMEOUT), // 30 seconds
        }
    }
}
```
```

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

### ZmqMessage Construction

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/message.md

Demonstrates how to construct a ZmqMessage from different data types like Vec<Bytes>, Vec<u8>, Bytes, String, and &str.

```APIDOC
## ZmqMessage Construction

### From `Vec<Bytes>`

Creates a message from a vector of frames. Returns error if vector is empty.

**Example:**
```rust
use zeromq::ZmqMessage;
use bytes::Bytes;
use std::convert::TryFrom;

let frames = vec![Bytes::from("hello"), Bytes::from("world")];
let msg = ZmqMessage::try_from(frames)?;
```

### From `Vec<u8>`

Creates a single-frame message from a byte vector.

**Example:**
```rust
use zeromq::ZmqMessage;

let msg = ZmqMessage::from(vec![1, 2, 3, 4, 5]);
```

### From `Bytes`

Creates a single-frame message from a `Bytes` object.

**Example:**
```rust
use zeromq::ZmqMessage;
use bytes::Bytes;

let msg = ZmqMessage::from(Bytes::from("hello"));
```

### From `String`

Creates a single-frame message from a `String`.

**Example:**
```rust
use zeromq::ZmqMessage;

let msg = ZmqMessage::from("hello world".to_string());
```

### From `&str`

Creates a single-frame message from a string slice.

**Example:**
```rust
use zeromq::ZmqMessage;

let msg = ZmqMessage::from("hello world");
```
```

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

### monitor()

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/socket-core.md

Creates a monitor channel for receiving socket lifecycle events. Subsequent calls replace the previous monitor.

```APIDOC
## monitor()

### Description
Creates a monitor channel for receiving socket lifecycle events. Subsequent calls replace the previous monitor.

### Method
`monitor`

### Return
- `mpsc::Receiver<SocketEvent>` - Channel receiving `SocketEvent` items

### Example
```rust
use zeromq::{PushSocket, Socket};

let mut socket = PushSocket::new();
let mut events = socket.monitor();

socket.bind("tcp://*:5555").await?;

while let Some(event) = events.recv().await {
    println!("Socket event: {:?}", event);
}
```
```

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

### Prelude Module Re-exports

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/socket-core.md

Re-exports frequently used items from the zmq.rs library, such as `Socket`, `SocketRecv`, `SocketSend`, and `TryIntoEndpoint`, for convenient usage.

```rust
pub mod prelude {
    pub use crate::{Socket, SocketRecv, SocketSend, TryIntoEndpoint};
}
```

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

### Create Peer Identity from String

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/configuration.md

Demonstrates creating a custom PeerIdentity from a string. The string is converted to bytes and then to a PeerIdentity using `try_from`.

```rust
use zeromq::{Socket, SocketOptions, util::PeerIdentity};
use std::convert::TryFrom;

let mut opts = SocketOptions::default();

// From string
let id = PeerIdentity::try_from("load-balancer-1".as_bytes().to_vec())?;
opts.peer_id(id);
```

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

### Add Multiple Subscriptions

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/pub-sub-sockets.md

Configures a SubSocket to receive messages matching specific topic prefixes. An empty subscription string matches all messages. Subscriptions are immediately broadcast to publishers.

```rust
use zeromq::{SubSocket, Socket};

let mut socket = SubSocket::new();
socket.subscribe("weather.nyc").await?;
socket.subscribe("weather.la").await?;
socket.subscribe("sports").await?;
socket.connect("tcp://localhost:5555").await?;
```

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

### Run Performance Suite with Specific Toolchain

Source: https://github.com/zeromq/zmq.rs/blob/master/docs/BENCHMARKS.md

If pinned OMQ dependencies require a newer toolchain than the local default, specify it explicitly using the --toolchain flag.

```sh
python3 scripts/run_perf_suite.py --profile smoke --impl omq --transport tcp --toolchain 1.94.1
```

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

### Creating TCP Endpoint from Domain and Port

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/endpoints.md

Creates a TCP Endpoint using a domain name and a port number.

```rust
use zeromq::Endpoint;

let ep = Endpoint::from_tcp_domain("example.com".to_string(), 5555);
```

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

### Subscribe to a Topic with XSubSocket

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/pub-sub-sockets.md

Adds a subscription filter and sends the subscription message to the publisher using an XSubSocket. Connects to an XPUB socket.

```rust
use zeromq::{XSubSocket, Socket};

let mut socket = XSubSocket::new();
socket.subscribe("weather").await?;
socket.connect("tcp://localhost:5555").await?;
```

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

### Configure Multiple Services with Distinct Identities

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/configuration.md

Create multiple sockets, each with a unique peer identity, for different services like load balancers or cache servers. This is useful for managing distinct roles within an application.

```rust
use zeromq::{Socket, SocketOptions, util::PeerIdentity};
use std::convert::TryFrom;

async fn setup_services() -> zeromq::ZmqResult<()> {
    // Service 1: Load Balancer
    let mut opts1 = SocketOptions::default();
    opts1.peer_identity(PeerIdentity::try_from("lb-1".as_bytes().to_vec())?);
    let lb = RouterSocket::with_options(opts1);
    lb.bind("tcp://*:5555").await?;
    
    // Service 2: Cache Server
    let mut opts2 = SocketOptions::default();
    opts2.peer_identity(PeerIdentity::try_from("cache-1".as_bytes().to_vec())?);
    let cache = RouterSocket::with_options(opts2);
    cache.bind("tcp://*:5556").await?;
    
    Ok(())
}
```

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

### Configure Socket Options

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/INDEX.md

Set custom socket options like connection timeout and peer identity before creating a socket. Defaults are used if options are not explicitly set.

```rust
use zeromq::{Socket, SocketOptions};
use std::time::Duration;

let mut opts = SocketOptions::default();
opts.connect_timeout(Duration::from_secs(60));
opts.peer_identity(custom_id);

let socket = PushSocket::with_options(opts);
```

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

### prepend()

Source: https://github.com/zeromq/zmq.rs/blob/master/_autodocs/message.md

Adds all frames from another ZmqMessage to the beginning of the current message.

```APIDOC
## prepend()

### Description
Prepends all frames from another message to this message.

### Method
`prepend(&mut self, message: &ZmqMessage)`

### Parameters
#### Path Parameters
- **message** (`&ZmqMessage`) - Required - Message whose frames to prepend

### Request Example
```rust
use zeromq::ZmqMessage;

let mut msg1 = ZmqMessage::from("world");
let msg2 = ZmqMessage::from("hello");
msg1.prepend(&msg2);
```
```