Struct amiquip::ConfirmSmoother

pub struct ConfirmSmoother { /* fields omitted */ }

Helper to smooth out of order and/or multiple: true publisher confirmation messages.

If publisher confirms are enabled, the server may confirm messages out of order and/or may confirm multiple messages with a single Confirm. ConfirmSmoother exists to "smooth" server messages out into an always-increasing-by-one sequence of confirmation messages.

Example

use amiquip::{Confirm, ConfirmSmoother};
use crossbeam_channel::Receiver;

// assume we've published n messages and want to wait for them to be confirmed
fn wait_for_publisher_confirms(n: usize, receiver: &Receiver<Confirm>) {
    // NOTE: a new smoother assumes we will be receiving messages starting with
    // delivery_tag = 1, so this method is only valid if called after the first n
    // publishes on a channel. We could take a &mut ConfirmSmoother to be called
    // multiple times in succession on the same channel.
    let mut smoother = ConfirmSmoother::new();
    let mut acked = 0;
    let mut nacked = 0;
    while acked + nacked < n {
        // get a confirmation from the server; this may be out of order or a confirm
        // for multiple messages in one payload
        let raw_confirm = match receiver.recv() {
            Ok(raw_confirm) => raw_confirm,
            Err(_) => {
                // the I/O thread dropped the sending side; either an error has occurred
                // or another thread of ours closed the connection; either way we'll
                // stop waiting
                return;
            }
        };

        // feed the raw confirm into the smoother. Two notes:
        //   1. We must run the returned iterator to the end or risk missing confirms.
        //   2. The iterator may produce 0, 1, or multiple independent confirmations.
        //      They will all have multiple: false.
        for confirm in smoother.process(raw_confirm) {
            match confirm {
                Confirm::Ack(_) => {
                    acked += 1;
                }
                Confirm::Nack(_) => {
                    // server rejected message; need to do something else to
                    // track which messages were rejected
                    nacked += 1;
                }
            }
        }
    }
}

Methods

impl ConfirmSmoother

pub fn new() -> ConfirmSmoother

Create a new ConfirmSmoother. It expects the next (in absolute order) delivery tag received from the server to be 1.

pub fn with_expected_delivery_tag(expected: u64) -> ConfirmSmoother

Create a new ConfirmSmoother. It expects the next (in absolute order) delivery tag received from the server to be expected.

pub fn process<'a>(
    &'a mut self,
    confirm: Confirm
) -> impl Iterator<Item = Confirm> + 'a

Process a confirmation message from the server. Returns an iterator; each item returned by the iterator will be a single (i.e., multiple: false) Confirm. You must run the iterator to its completion or risk missing confirmations; future calls to process will not return an iterator that will repeat confirms that would have been returned by a previously returned iterator (even if that earlier iterator was dropped before it ran to completion).

The returned iterator may have 0 items (if confirm is a non-multiple confirmation that is later than the next expected delivery tag), 1 item (if confirm exactly matches our next expected delivery tag and we had not previously seen the next tag), or multiple items (if confirm is a multiple: true confirmation or we've previously seen out-of-order tags that are next sequentially after confirm's tag).

Trait Implementations

impl Clone for ConfirmSmoother

fn clone(&self) -> ConfirmSmoother

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for ConfirmSmoother

fn default() -> ConfirmSmoother

Returns the "default value" for a type.

impl Debug for ConfirmSmoother

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

Formats the value using the given formatter.