Reacting to writes
✅ Verified ·
on_put.rs·on_put_reject.rs·demo_on_put.py· checkdocs_verify·The badge reports the whole
docs-verifysuite, not this chapter alone.
What you'll build
A writable PV that runs your code when a client writes to it and, in the form that supports it, refuses writes it does not like.
Rust
#![allow(unused)] fn main() { let server = PvaServer::builder() .ao("SIM:SETPOINT", 25.0) .on_put("SIM:SETPOINT", |pv, val| { println!("{pv} was set to {val:?}"); }) .build(); }
That is the builder form, and it is worth reading its signature carefully:
#![allow(unused)] fn main() { Fn(&str, &DecodedValue) }
It returns (). It runs after the value has been applied, and it has no
way to say no. It is only a notification hook.
To reject a write, use the typed handle form instead:
#![allow(unused)] fn main() { Fn(&Pv<T>, T) -> Result<(), String> }
#![allow(unused)] fn main() { let setpoint = Pv::ao("SIM:SETPOINT", 25.0) .units("degC") .drive_limits(0.0, 100.0) .on_put(|pv, value: f64| { if !(0.0..=100.0).contains(&value) { // Err rejects the PUT; the client's put() fails. return Err(format!("{} outside 0..100: {value}", pv.name())); } println!("{} accepted {value}", pv.name()); Ok(()) }); let server = PvaServer::serve([setpoint.clone()]).build().await; }
Err(msg) rejects the PUT on the wire and the client's put fails:
$ spput SIM:SETPOINT 500
SIM:SETPOINT ERROR protocol error: PUT failed: SIM:SETPOINT outside 0..100: 500
$ spget SIM:SETPOINT
SIM:SETPOINT 2026-08-04 10:08:05.123 30
The rejected value never reached the record.
Ok(()) accepts it. You also get the value already converted to T
instead of a raw DecodedValue.
The two forms are not interchangeable. The builder form cannot reject a write. If you are validating, use handles.
Python
setpoint = spvirit.ao("SIM:SETPOINT", 25.0, drive_limits=(0.0, 100.0))
@setpoint.on_put
def _on_setpoint(pv, value):
print(f"{pv.name} was set to {value}")
if value > 100.0:
return False # reject the PUT on the wire
server = spvirit.Server(pvs=[setpoint])
Python has one form and it can reject: returning False (or raising)
rejects the PUT, and anything else accepts it. The callback runs before
the value is applied.
$ spput SIM:SETPOINT 30
SIM:SETPOINT OK
$ spput SIM:SETPOINT 500
SIM:SETPOINT ERROR protocol error: PUT failed: rejected by on_put
What to notice
Attach callbacks before serving. on_put, scan, and calc must be
attached to a PV before it is handed to Server(...) / PvaServer::serve.
Attaching afterwards is a silent no-op: the core logs a warning, raises
no error, and never runs your callback.
This is true in both languages.
Validation is the only enforcement you get. Drive limits are advisory
(see Serving scalars), so on_put is where range checking
actually happens. If a PV must not accept 500, write that rule here.
The callback is not a place to block. It runs on the server's runtime. Long work belongs in a task you spawn from it.
A single client write can invoke your callback more than once. spput
tries the full PUT flow first and silently falls back to the simple flow if
that fails, so a rejected write arrives at the server twice and your
callback logs twice:
$ spput SIM:SETPOINT 700
SIM:SETPOINT ERROR protocol error: PUT failed: rejected by on_put
# server log
SIM:SETPOINT was set to 700.0
SIM:SETPOINT was set to 700.0
Accepted writes run once; only the retry path doubles up. Pass
--no-flow-fallback to suppress it. The general rule holds regardless of
client: on_put callbacks should be idempotent, and side effects that
must happen exactly once do not belong in one.
Array PVs do not support on_put or scan in Python. Calling either
on an array PV raises TypeError. Drive arrays with pv.set(...) from
your own loop instead; see Arrays and waveforms.
Run it
# Terminal 1
cargo run -p spvirit-server --example on_put
# or: python spvirit-py/examples/demo_on_put.py
# Terminal 2
spput SIM:SETPOINT 30
spput SIM:SETPOINT 500
on_put only observes: both writes succeed, and the interesting output
is in terminal 1:
$ spput SIM:SETPOINT 30
SIM:SETPOINT OK
$ spput SIM:SETPOINT 500
SIM:SETPOINT OK
# terminal 1
SIM:SETPOINT was set to Structure([("value", Float64(30.0))])
SIM:SETPOINT was set to Structure([("value", Float64(500.0))])
The callback receives the whole submitted structure, not a bare number —
a client may write value alone or several fields at once.
Now run on_put_reject instead, which returns an error for out-of-range
values:
cargo run -p spvirit-server --example on_put_reject
$ spput SIM:SETPOINT 30
SIM:SETPOINT OK
$ spput SIM:SETPOINT 500
SIM:SETPOINT ERROR protocol error: PUT failed: SIM:SETPOINT outside 0..100: 500
Error: Protocol("PUT failed: SIM:SETPOINT outside 0..100: 500")
Your message crosses the wire verbatim, so write it for whoever is holding
the terminal. spput also exits non-zero, which is why it prints that
second Error: line — useful in a script.
Terminal 1 logs only the write it let through:
SIM:SETPOINT accepted 30