busybeaver 0.1.6

This Beaver executes your Futures independently of your worker threads, supporting scheduling strategies such as time intervals, execution count intervals, specific-time polling policies, and more.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

use crate::error::RuntimeError;
use std::sync::Arc;

/// Listener for task lifecycle events.
///
/// **Important**: listener callbacks run on the executor lane and **must not**
/// panic or block. Panics inside a listener callback are *not* isolated by
/// the framework and will tear down the executor lane.
pub trait WorkListener: Send + Sync {
    /// Called when the task **exhausts all of its retry attempts** without the
    /// work ever returning [`WorkResult::Done`](crate::WorkResult::Done).
    ///
    /// Despite the name, this callback represents *retries-exhausted*, not
    /// *successful completion*. It fires only after the last permitted
    /// execution still returned [`WorkResult::NeedRetry`](crate::WorkResult::NeedRetry).
    /// For [`PeriodicTask`](crate::periodic_task::PeriodicTask) it also fires
    /// when the work eventually returns `Done` (since periodic tasks have no
    /// retry budget to exhaust).
    fn on_complete(&self);

    /// Called when the task is cancelled or interrupted by
    /// [`Beaver::cancel_all`](crate::Beaver::cancel_all),
    /// [`Beaver::cancel_non_long_resident`](crate::Beaver::cancel_non_long_resident),
    /// [`Beaver::release_thread_resource_by_name`](crate::Beaver::release_thread_resource_by_name),
    /// or [`Beaver::destroy`](crate::Beaver::destroy).
    fn on_interrupt(&self);

    /// Called when a runtime error occurs during task execution.
    ///
    /// This includes panics inside [`work`](crate::work): if the closure or its async block
    /// panics, the panic is caught and reported as [`RuntimeError::TaskExecutionFailed`];
    /// the worker continues so other tasks can still run.
    ///
    /// Default implementation does nothing; callers may optionally override.
    fn on_error(&self, _error: RuntimeError) {}
}

/// Progress callback for fixed-count retry tasks, called before each execution.
pub trait FixedCountProgress: Send + Sync {
    /// Called before the `current`-th execution (out of `total`), with the task's `tag`.
    fn on_progress(&self, current: u32, total: u32, tag: &str);
}

/// Constructs a [`WorkListener`] from closures.
pub struct WorkListenerClosure<C, I, E> {
    on_complete: C,
    on_interrupt: I,
    on_error: E,
}

impl<C, I, E> WorkListener for WorkListenerClosure<C, I, E>
where
    C: Fn() + Send + Sync,
    I: Fn() + Send + Sync,
    E: Fn(RuntimeError) + Send + Sync,
{
    fn on_complete(&self) {
        (self.on_complete)();
    }
    fn on_interrupt(&self) {
        (self.on_interrupt)();
    }
    fn on_error(&self, error: RuntimeError) {
        (self.on_error)(error);
    }
}

/// Creates a [`WorkListener`] from two closures (without error handling).
pub fn listener<C, I>(
    on_complete: C,
    on_interrupt: I,
) -> Arc<WorkListenerClosure<C, I, fn(RuntimeError)>>
where
    C: Fn() + Send + Sync,
    I: Fn() + Send + Sync,
{
    Arc::new(WorkListenerClosure {
        on_complete,
        on_interrupt,
        on_error: |_| {},
    })
}

/// Creates a [`WorkListener`] from three closures (with error handling).
pub fn listener_with_error<C, I, E>(
    on_complete: C,
    on_interrupt: I,
    on_error: E,
) -> Arc<WorkListenerClosure<C, I, E>>
where
    C: Fn() + Send + Sync,
    I: Fn() + Send + Sync,
    E: Fn(RuntimeError) + Send + Sync,
{
    Arc::new(WorkListenerClosure {
        on_complete,
        on_interrupt,
        on_error,
    })
}

impl<F> FixedCountProgress for F
where
    F: Fn(u32, u32, &str) + Send + Sync,
{
    fn on_progress(&self, current: u32, total: u32, tag: &str) {
        self(current, total, tag);
    }
}