Stale readings
Let devices forget old readings with a timer, which an actor opts into by its type.
A sensor which goes silent keeps its last reading forever, so the averages keep counting a temperature that may be hours old. In this step a device forgets its reading once it has received no new one for a while. The manager, the groups and the query are those from the previous step, unchanged.
A timer per device
const STALE_AFTER: Duration = Duration::from_secs(1);struct Device;
impl Actor for Device {
type Message = DeviceMessage;
type Timers = Timed;
type Stash = Unstashed;
type State = Option<f64>;
type Error = InvalidReading;
fn init(
&self,
_: &ActorContext<Self::Message, Self::Timers>,
) -> Result<Self::State, Self::Error> {
Ok(None)
}
fn receive(
&self,
context: &ActorContext<Self::Message, Self::Timers>,
incoming: Incoming<Self::Message>,
last_reading: Self::State,
) -> Result<Control<Self::State>, Self::Error> {
let Incoming::Message(message) = incoming else {
unreachable!("the device watches no actor, hence never gets a terminated signal")
};
match message {
DeviceMessage::Record(degrees) if degrees.is_nan() => Err(InvalidReading),
DeviceMessage::Record(degrees) => {
context.start_timer("stale", DeviceMessage::Expire, STALE_AFTER);
Ok(Control::Continue(Some(degrees)))
}
DeviceMessage::Expire => Ok(Control::Continue(None)),
DeviceMessage::Read(reply_to) => {
reply_to.reply(last_reading);
Ok(Control::Continue(last_reading))
}
DeviceMessage::Retire => Ok(Control::Stop),
}
}
}
enum DeviceMessage {
Record(f64),
Expire,
Read(ReplyTo<Option<f64>>),
Retire,
}
#[derive(Debug, Error)]
#[error("reading is not a number")]
struct InvalidReading;The device declares type Timers = Timed. This gives its context two more methods, start_timer and cancel_timer. init and receive always take ActorContext<Self::Message, Self::Timers, Self::Stash>. The earlier steps could write ActorContext<Self::Message>, because the context's other two type parameters default to Untimed and Unstashed, which is what their actors declare. The device has to name Self::Timers, and leaves the third parameter at its default, Unstashed. Every other actor keeps Untimed, and its context has no start_timer at all. An actor can only start a timer if its type says so, and an untimed actor runs without the bookkeeping timers need.
On Record, the device calls start_timer with a key, a message and a delay. Once STALE_AFTER has elapsed, the device receives Expire, as if it had told itself, and it forgets its reading.
One timer per key
The key names the timer. Starting a timer under a key which is in use replaces the timer, so every Record pushes the deadline back. A device which keeps reporting never receives Expire.
A replaced timer is never received, even when it was already due. A timer's message is also handled behind everything that was queued when the timer fired. So a Record which arrived before the deadline is handled first, replaces the timer, and the fresh reading stays.
Timers and restarts
A device which fails on an invalid reading restarts without a reading, as in step 6. The restart also cancels its timers, since they belong to the old state. No Expire from before the restart reaches the new state.
Talking to the manager
main is like the one of the previous step. It records readings for left, right and window in the attic and for boiler in the cellar, retires right and asks all three groups for their average. What follows is new:
print_averages(manager).await?;
sleep(2 * STALE_AFTER).await;
manager.tell(DeviceManagerMessage::Record {
group_name: "attic",
device_name: "left",
degrees: 22.3,
});
print_averages(manager).await?;print_averages is the loop over the three groups from the previous step, moved into a function. After the first round, main waits for twice STALE_AFTER, records a new reading for left and asks again.
Why ask before waiting? A device starts its timer when it handles its Record, not when main sends it. The group tells each device its Record before the query sends its Read, and both arrive in the device's mailbox in that order. So when the first answers arrive, every device has started its timer, and the wait begins after that.
Run it
From a clone of the tellus repository:
RUST_LOG=tellus=debug cargo run --quiet -p tellus --example getting_started_08_stale_readingsOn stdout it typically prints:
Average temperature in attic: 19.65
Average temperature in cellar: 11.00
No readings in garage
Average temperature in attic: 22.30
No readings in cellar
No readings in garageIn the first round the attic averages left and window, since right retired. In the second round window has gone stale, so only the new reading of left counts. The cellar's boiler has gone stale, too.
The timing leaves a margin of a full STALE_AFTER on both sides, but it is not guaranteed. On a heavily loaded machine a device can get to its Expire only after the second query's Read.
What you learned
A timer lets an actor send itself a message after a delay. Timers are opt-in: only an actor whose Timers type is Timed can start one. Starting a timer under a key in use replaces it, and a restart cancels all of them.
Where to go from here
You have used the core features of tellus: actors with state, tell and ask, child actors, watch with its ordering guarantee, supervision and timers.
The next tutorials build on this one. Event-sourced actors makes the devices survive restarts, and Clustered actors spreads them across nodes.