semiont 0.7.2

Semiont's Rust SDK: the protocol's types, the transport contract and a client of the bus over it, and what a client needs to name its principals and hold its roles, as protocol/specs/ states it.
Documentation
//! A pointer's dwell: an annotation is hovered once the pointer has rested
//! on it, and no longer the moment it leaves. A pointer crossing the page
//! hovers nothing on its way.

use crate::locked;
use crate::state_unit::StateUnit;
use crate::types::AnnotationId;
use std::sync::{Arc, Mutex};
use std::time::Duration;
use tokio::task::AbortHandle;

#[derive(Default)]
struct Dwell {
    /// What was last said to be hovered.
    hovering: Option<AnnotationId>,
    /// The rest that has not run its time yet.
    resting: Option<AbortHandle>,
    /// Which rest is the current one: one that was overtaken says nothing.
    rest: u64,
    /// Once disposed, the pointer is followed no more.
    disposed: bool,
}

impl Dwell {
    fn interrupt(&mut self) {
        self.rest += 1;
        if let Some(resting) = self.resting.take() {
            resting.abort();
        }
    }
}

type Say = dyn Fn(Option<&AnnotationId>) + Send + Sync;

/// See the module's documentation. `say` is told each change: the
/// annotation hovered, or none. `client.beckon.hover` is what it is usually
/// given. Disposing it forgets a rest that has not run its time, and it says
/// nothing more; dropping it disposes it.
pub struct HoverDwell {
    dwell: Arc<Mutex<Dwell>>,
    say: Arc<Say>,
    delay: Duration,
}

impl HoverDwell {
    /// A dwell of `delay`: `crate::timing::HOVER_DELAY` unless the viewer
    /// was told another.
    pub fn new(
        say: impl Fn(Option<&AnnotationId>) + Send + Sync + 'static,
        delay: Duration,
    ) -> HoverDwell {
        HoverDwell {
            dwell: Arc::new(Mutex::new(Dwell::default())),
            say: Arc::new(say),
            delay,
        }
    }

    /// The pointer is on an annotation. It is hovered once the pointer has
    /// stayed for the delay; one already hovered is not said again.
    pub fn enter(&self, annotation_id: &AnnotationId) {
        let mut dwell = locked(&self.dwell);
        if dwell.disposed || dwell.hovering.as_ref() == Some(annotation_id) {
            return;
        }
        dwell.interrupt();
        let (rest, delay) = (dwell.rest, self.delay);
        let (shared, say) = (self.dwell.clone(), self.say.clone());
        let annotation_id = annotation_id.clone();
        let resting = tokio::spawn(async move {
            tokio::time::sleep(delay).await;
            {
                let mut dwell = locked(&shared);
                if dwell.rest != rest {
                    return;
                }
                dwell.resting = None;
                dwell.hovering = Some(annotation_id.clone());
            }
            say(Some(&annotation_id));
        });
        dwell.resting = Some(resting.abort_handle());
    }

    /// The pointer left. Said at once, and only when something was hovered.
    pub fn leave(&self) {
        let was_hovering = {
            let mut dwell = locked(&self.dwell);
            if dwell.disposed {
                return;
            }
            dwell.interrupt();
            dwell.hovering.take().is_some()
        };
        if was_hovering {
            (self.say)(None);
        }
    }
}

impl StateUnit for HoverDwell {
    fn dispose(&self) {
        let mut dwell = locked(&self.dwell);
        dwell.interrupt();
        dwell.disposed = true;
    }
}

impl Drop for HoverDwell {
    fn drop(&mut self) {
        self.dispose();
    }
}