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::{thread, time::Duration};

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

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

let bound = radio.last_endpoint()?;
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
        };

        radio.transmit(msg, group).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);

Implementations

impl Dish

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

Create a Dish socket from the global context

Returned Error Variants

• InvalidCtx
• SocketLimit

pub fn with_ctx(handle: CtxHandle) -> Result<Self, Error>

Create a Dish socket associated with a specific context from a CtxHandle.

Returned Error Variants

• InvalidCtx
• SocketLimit

pub fn ctx(&self) -> CtxHandle

Returns a reference to the context of the socket.

pub fn join<G>(&self, group: G) -> Result<(), Error> where
    G: Into<Group>, 

Joins the specified group.

Usage Contract

• A group can be joined at most once.

Returned Error Variants

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

Example

use libzmq::{prelude::*, Dish, Group};

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

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

Returns a snapshot of the list of joined groups.

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

Example

use libzmq::{prelude::*, Dish, Group};

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

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

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

pub fn leave<G>(&self, group: G) -> Result<(), Error> where
    G: AsRef<GroupSlice>, 

Leave the specified group.

Usage Contract

• The group must be already joined.

Returned Error Variants

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

Example

use libzmq::{prelude::*, Dish, Group};

let group: Group = "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 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 Debug for Dish

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

Formats the value using the given formatter.

impl Eq for Dish

impl<'a> From<&'a Dish> for Pollable<'a>

fn from(dish: &'a Dish) -> Self

Performs the conversion.

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 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_hwm(&self) -> Result<i32, Error>

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

fn set_recv_hwm(&self, hwm: i32) -> Result<(), Error>

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

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

The timeout for [recv] on the socket.

fn set_recv_timeout<P>(&self, period: P) -> Result<(), Error> where
    P: Into<Period>, 

Sets the timeout for [recv] on the socket.

impl Send for Dish

impl Socket for Dish

fn connect<E>(&self, endpoint: E) -> Result<(), Error> where
    E: Into<Endpoint>, 

Schedules a connection to a Endpoint.

fn bind<E>(&self, endpoint: E) -> Result<(), Error> where
    E: Into<Endpoint>, 

Schedules a bind to a Endpoint and then accepts incoming connections.

fn disconnect<E>(&self, endpoint: E) -> Result<(), Error> where
    E: Into<Endpoint>, 

Disconnect the socket from a Endpoint.

fn unbind<I, E>(&self, endpoint: E) -> Result<(), Error> where
    E: Into<Endpoint>, 

Unbind the socket from a Endpoint.

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

Retrieve the last endpoint connected or bound to.

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].

impl Sync for Dish