Struct libzmq::Dish

pub struct Dish { /* fields omitted */ }

A Dish socket is used by a subscriber to subscribe to groups distributed by a Radio.

Initially a ZMQ_DISH socket is not subscribed to any groups, use join to join a group.

Summary of Characteristics

Characteristic	Value
Compatible peer sockets	Radio
Direction	Unidirectional
Send/receive pattern	Receive only
Incoming routing strategy	Fair-queued
Outgoing routing strategy	N/A

Example

use libzmq::{prelude::*, *};
use std::{convert::TryInto, thread, time::Duration};

let addr: TcpAddr = "127.0.0.1:*".try_into()?;

let radio = RadioBuilder::new()
    .bind(addr)
    .build()?;

let bound = radio.last_endpoint().unwrap();
let a: &Group = "group a".try_into()?;

let dish = DishBuilder::new()
    .connect(bound)
    .join(a)
    .build()?;

// Start the feed. It has no conceptual start nor end, thus we
// don't synchronize with the subscribers.
thread::spawn(move || {
    let a: &Group = "group a".try_into().unwrap();
    let b: &Group = "group b".try_into().unwrap();
    let mut count = 0;
    loop {
        let mut msg = Msg::new();
        // Alternate between the two groups.
        let group = {
            if count % 2 == 0 {
                a
            } else {
                b
            }
        };

        msg.set_group(group);
        radio.send(msg).unwrap();

        thread::sleep(Duration::from_millis(1));
        count += 1;
    }
});

// The dish exclusively receives messages from the groups it joined.
let msg = dish.recv_msg()?;
assert_eq!(msg.group().unwrap(), a);

let msg = dish.recv_msg()?;
assert_eq!(msg.group().unwrap(), a);

Methods

impl Dish

pub fn new() -> Result<Self, Error>

Create a Dish socket from the global context

Returned Error Variants

• CtxTerminated
• SocketLimit

pub fn with_ctx<C>(ctx: C) -> Result<Self, Error> where
    C: Into<Ctx>, 

Create a Dish socket from a specific context.

Returned Error Variants

• CtxTerminated
• SocketLimit

pub fn ctx(&self) -> &Ctx

Returns a reference to the context of the socket.

pub fn join<I, G>(&self, groups: I) -> Result<(), Error<usize>> where
    I: IntoIterator<Item = G>,
    G: Into<GroupOwned>, 

Joins the specified group(s).

When any of the connection attempt fail, the Error will contain the position of the iterator before the failure. This represents the number of groups that were joined before the failure.

Usage Contract

• Each group can be joined at most once.

Returned Error Variants

• CtxTerminated
• Interrupted
• InvalidInput (if group was already joined)

Example

use libzmq::{prelude::*, Dish, Group};
use std::convert::TryInto;

let group: &Group = "some group".try_into()?;
let dish = Dish::new()?;
dish.join(group)?;

pub fn joined(&self) -> Vec<GroupOwned>

Returns a snapshot of the list of joined Group.

The list might be modified by another thread after it is returned.

Example

use libzmq::{prelude::*, Dish, Group};
use std::convert::TryInto;

let first: &Group = "first group".try_into()?;
let second: &Group = "second group".try_into()?;

let dish = Dish::new()?;
assert!(dish.joined().is_empty());

dish.join(vec![first, second])?;
assert_eq!(dish.joined().len(), 2);

pub fn leave<I, G>(&self, groups: I) -> Result<(), Error<usize>> where
    I: IntoIterator<Item = G>,
    G: Into<GroupOwned>, 

Leave the specified group(s).

When any of the connection attempt fail, the Error will contain the position of the iterator before the failure. This represents the number of groups that were leaved before the failure.

Usage Contract

• The group must be already joined.

Returned Error Variants

• CtxTerminated
• Interrupted
• InvalidInput (if group not already joined)

Example

use libzmq::{prelude::*, Dish, GroupOwned};
use std::convert::TryInto;

let group: GroupOwned = "some group".to_owned().try_into()?;

let dish = Dish::new()?;
assert!(dish.joined().is_empty());

dish.join(&group)?;
assert_eq!(dish.joined().len(), 1);

dish.leave(&group)?;
assert!(dish.joined().is_empty());

Trait Implementations

impl RecvMsg for Dish

fn recv(&self, msg: &mut Msg) -> Result<(), Error>

Retreive a message from the inbound socket queue.

fn try_recv(&self, msg: &mut Msg) -> Result<(), Error>

Try to retrieve a message from the inbound socket queue without blocking.

fn recv_msg(&self) -> Result<Msg, Error>

A convenience function that allocates a [Msg] with the same properties as [recv].

fn try_recv_msg(&self) -> Result<Msg, Error>

A convenience function that allocates a [Msg] with the same properties as [try_recv].

fn recv_high_water_mark(&self) -> Result<Option<i32>, Error>

The high water mark for incoming messages on the specified socket.

fn set_recv_high_water_mark(&self, maybe: Option<i32>) -> Result<(), Error>

Set the high water mark for inbound messages on the specified socket.

fn recv_timeout(&self) -> Result<Option<Duration>, Error>

The timeout for [recv] on the socket.

fn set_recv_timeout(&self, maybe: Option<Duration>) -> Result<(), Error>

Sets the timeout for [recv] on the socket.

impl Socket for Dish

fn connect<I, E>(&self, endpoints: I) -> Result<(), Error<usize>> where
    I: IntoIterator<Item = E>,
    E: Into<Endpoint>, 

Schedules a connection to one or more [Endpoints] and then accepts incoming connections.

fn connected(&self) -> Vec<Endpoint>

Returns a snapshot of the list of connected Endpoint.

fn disconnect<I, E>(&self, endpoints: I) -> Result<(), Error<usize>> where
    I: IntoIterator<Item = E>,
    E: Into<Endpoint>, 

Disconnect the socket from one or more [Endpoints].

fn bind<I, E>(&self, endpoints: I) -> Result<(), Error<usize>> where
    I: IntoIterator<Item = E>,
    E: Into<Endpoint>, 

Schedules a bind to one or more [Endpoints] and then accepts incoming connections.

fn bound(&self) -> Vec<Endpoint>

Returns a snapshot of the list of bound Endpoint.

fn unbind<I, E>(&self, endpoints: I) -> Result<(), Error<usize>> where
    I: IntoIterator<Item = E>,
    E: Into<Endpoint>, 

Unbinds the socket from one or more [Endpoints].

fn last_endpoint(&self) -> Result<Option<Endpoint>, Error>

Retrieve the last endpoint connected or bound to.

fn backlog(&self) -> Result<i32, Error>

Retrieve the maximum length of the queue of outstanding peer connections.

fn set_backlog(&self, value: i32) -> Result<(), Error>

Set the maximum length of the queue of outstanding peer connections for the specified socket; this only applies to connection-oriented transports.

fn heartbeat_interval(&self) -> Result<Duration, Error>

The interval between sending ZMTP heartbeats.

fn set_heartbeat_interval(&self, duration: Duration) -> Result<(), Error>

Sets the interval between sending ZMTP PINGs (aka. heartbeats).

fn heartbeat_timeout(&self) -> Result<Duration, Error>

How long to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic.

fn set_heartbeat_timeout(&self, duration: Duration) -> Result<(), Error>

How long to wait before timing-out a connection after sending a PING ZMTP command and not receiving any traffic.

fn heartbeat_ttl(&self) -> Result<Duration, Error>

The timeout on the remote peer for ZMTP heartbeats. If this option and heartbeat_interval is not None the remote side shall time out the connection if it does not receive any more traffic within the TTL period.

fn set_heartbeat_ttl(&self, duration: Duration) -> Result<(), Error>

Set timeout on the remote peer for ZMTP heartbeats. If this option and heartbeat_interval is not None the remote side shall time out the connection if it does not receive any more traffic within the TTL period.

fn linger(&self) -> Result<Option<Duration>, Error>

Returns the linger period for the socket shutdown.

fn set_linger(&self, maybe: Option<Duration>) -> Result<(), Error>

Sets the linger period for the socket shutdown.

fn mechanism(&self) -> Mechanism

Returns the socket's [Mechanism].

fn set_mechanism<M>(&self, mechanism: M) -> Result<(), Error> where
    M: Into<Mechanism>, 

Set the socket's [Mechanism]. # Example ``` # use failure::Error; # # fn main() -> Result<(), Error> { use libzmq::{prelude::*, Client, auth::{PlainClientCreds, Mechanism}};

impl Sync for Dish

impl Send for Dish

impl PartialEq<Dish> for Dish

fn eq(&self, other: &Dish) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

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

This method tests for !=.

impl Clone for Dish

fn clone(&self) -> Dish

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Eq for Dish

impl Debug for Dish

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

Formats the value using the given formatter.