Struct AttrDef 

pub struct AttrDef<M: Model> { /* private fields */ }

A builder for defining an attribute of a device.

Implementations

impl<M: Model> AttrDef<M>

pub fn new<N>(name: N) -> Self

where N: Into<Cow<'static, str>>,

Create a new attribute definition, without any read or write function.

pub fn doc<D>(self, doc: D) -> Self

where D: Into<Cow<'static, str>>,

Set the description of the attribute, which every device of the class starts from; like the rest of its configuration, the database and clients may override it per device.

pub fn label<L>(self, label: L) -> Self

where L: Into<Cow<'static, str>>,

Set the label of the attribute, the short name a client shows in place of its own, where “Position” reads better than “position” and “Δθ” than “delta_theta”.

pub fn unit<U>(self, unit: U) -> Self

where U: Into<Cow<'static, str>>,

Set the unit the value is expressed in, as it is shown next to it.

pub fn standard_unit(self, factor: f64) -> Self

Set the factor going from the value of the attribute to the same quantity in the international system, so that a client can convert without knowing the unit: 1e-3 for a value in millimetres, the metre being the standard unit of a length.

pub fn display_unit<U>(self, unit: U) -> Self

where U: Into<Cow<'static, str>>,

Set the unit the value is displayed in, when it is not the one it is expressed in: a value in metres a client should show in millimetres.

pub fn display_format<F>(self, format: F) -> Self

where F: Into<Cow<'static, str>>,

Set how the value is formatted for display, as a printf format such as %8.3f, which is what tells a client how many decimals of it are meaningful.

pub fn display_level(self, level: DisplayLevel) -> Self

Set the display level of the attribute, DisplayLevel::Expert hiding it from the panels an operator is shown without hiding it from anyone who asks for it.

pub fn range<T, R>(self, range: R) -> Self

where T: Into<AttrNumber> + Copy, R: RangeBounds<T>,

Set the range of the values the attribute accepts being written, outside of which a write is refused by the server rather than by the device.

The range is given as a Rust range, either bound of which may be left open for an attribute that is only bounded on one side:

AttrDef::new("position").range(-100.0..=100.0)
AttrDef::new("pressure").range(0.0..)

Panics

If a bound is exclusive, which Tango has no way to express.

pub fn alarm<T, R>(self, range: R) -> Self

where T: Into<AttrNumber> + Copy, R: RangeBounds<T>,

Set the range outside of which the attribute is in AttrQuality::Alarm, and the device with it: an alarm is the reading being wrong, not the write being refused.

Panics

If a bound is exclusive, see Self::range.

pub fn warning<T, R>(self, range: R) -> Self

where T: Into<AttrNumber> + Copy, R: RangeBounds<T>,

Set the range outside of which the attribute is in AttrQuality::Warning. Like an alarm, a warning puts the device in DevState::Alarm, in the states given to Dev::set_auto_alarm_states, the way cppTango does.

Panics

If a bound is exclusive, see Self::range.

pub fn delta<V, T>(self, value: V, time: T) -> Self

where V: Into<AttrNumber>, T: Into<Option<Duration>>,

Set the alarm on the read value drifting from the written one: how far apart the two may be, and for how long before it counts, absent for immediately.

This is what says that a motor asked to go somewhere is not going there, which no bound on the value alone can express.

pub fn change_event<A, R>(self, abs: A, rel: R) -> Self

where A: Into<Option<f64>>, R: Into<Option<f64>>,

Set the criteria of the change event: how much the value has to move, absolutely and relatively, for the server to send one. Either may be left out with None, and an attribute that declares neither only has the change events its device pushes by itself.

AttrDef::new("position").change_event(0.001, None)

pub fn periodic_event(self, period: Duration) -> Self

Set the period of the periodic event, which is sent whether the value moved or not and is how a client tells a device that has nothing to say from one that is gone.

pub fn archive_event<A, R, P>(self, abs: A, rel: R, period: P) -> Self

where A: Into<Option<f64>>, R: Into<Option<f64>>, P: Into<Option<Duration>>,

Set the criteria of the archive event: the same two changes as Self::change_event, and the longest an archiver may go without an event when the value does not move.

pub fn push_change_event(self, detect: bool) -> Self

Declare that the device pushes the change events of this attribute itself, see Dev::push_change_event, which is what a client may then subscribe to them for: with no polling, a subscription to the change events of an attribute that does not declare them is refused, the way cppTango refuses it.

With detect, the criteria of the change event are to be checked against what is pushed, see Self::change_event, as cppTango does.

TODO: Check the criteria, every push being sent for now.

pub fn push_archive_event(self, detect: bool) -> Self

Declare that the device pushes the archive events of this attribute itself, see Self::push_change_event.

pub fn push_data_ready_event(self) -> Self

Declare that the device announces this attribute ready to be read, see Dev::push_data_ready_event: without it, both the announcement and a subscription to it are refused, the way cppTango refuses them.

pub fn memorized(self, mode: AttrMemorized) -> Self

Make the attribute memorized: the server stores the value of every write in the database and restores it when the device is initialized, the mode saying whether it is only given back as the write value or written again for real.

Only a writable scalar can be memorized, there being nothing to remember about a value the device computes, and a state or an encoded value cannot, which a class is told when the attribute is given to it, see ClassDef::attr.

pub fn polled(self, period: Duration) -> Self

Ask for the attribute to be polled at that period, each reading being recorded in its history, which a read from the cache is answered with, and sent as a periodic event, see Self::periodic_event.

This period comes second: an attribute the polled_attr property of the device lists is polled at the period the property gives, and one it does not list at this one. The admin device changes it while the device runs, writing the property along, but an attribute removed from the polling this way is polled at this period again from the next initialization of the device, the property having no way to say it is not.

pub fn kind(self, kind: AttrDataKind) -> Self

Set the advertised data kind of the attribute. This is only needed for the read and write functions that use a raw Value, the typed ones derive it from their value type.

Panics

If the data kind has already been defined, explicitly or by a read or a write function, as a different kind.

pub fn format(self, format: AttrDataFormat) -> Self

Set the advertised data format of the attribute, which also gives the maximum dimensions of a spectrum or an image. This is only needed for the read and write functions that use a raw Value, the typed ones derive a format without any maximum dimension from their value type.

A maximum dimension of zero being undefined, it is compatible with any other one, so the maximum dimensions of a typed read or write function can be completed by this method, in any order.

Panics

If the data format has already been defined, explicitly or by a read or a write function, with a different layout or a different maximum dimension.

pub fn scalar(self) -> Self

Declare the attribute to hold a single value, which is Self::format with the format written for you.

Panics

If the format has already been defined as another layout, see Self::format.

pub fn spectrum(self, max_size: usize) -> Self

Declare the attribute to hold a one dimensional array of at most that many values.

A typed read or write function already gives the layout, so this is usually only there for the maximum size, which no value type carries; a maximum of zero leaves it undeclared, an array of any size then being accepted.

Panics

If the format has already been defined as another layout, or as a spectrum of a different maximum size, see Self::format.

pub fn image(self, max_width: usize, max_height: usize) -> Self

Declare the attribute to hold a two dimensional array of at most that width and that height, see Self::spectrum.

Panics

If the format has already been defined as another layout, or as an image of different maximum dimensions, see Self::format.

pub fn read_with<F>(self, func: F) -> Self

where F: Fn(&M, &Dev<M>) -> Result<AttrRead<Value>> + Send + Sync + 'static,

Define the read function of this attribute, with a shared access to the model.

This is the raw form of Self::read: the closure returns a Value, converting what it borrows from the model itself, which is what makes a closure usable for such a result. The advertised kind and format then have to be given with Self::kind and Self::format.

pub fn read<F>(self, func: F) -> Self

where F: for<'m> ReadShared<'m, M> + Send + Sync + 'static,

Define the read function of this attribute, with a shared access to the model, which allows parallel reading of such attributes.

The value type is taken from the ReadShared implementation of the function, and may borrow from the model, with the same constraints as CommandDef::exec: it is then written as a function item generic over the model lifetime, typically an associated method of the model.

Panics

If the advertised kind or format has already been defined incompatibly, see Self::kind and Self::format.

pub fn read_exclusive_with<F>(self, func: F) -> Self

where F: Fn(&mut M, &Dev<M>) -> Result<AttrRead<Value>> + Send + Sync + 'static,

Define the read function of this attribute, with an exclusive access to the model. This is the raw form of Self::read_exclusive, see Self::read_with.

pub fn read_exclusive<F>(self, func: F) -> Self

where F: for<'m> ReadExclusive<'m, M> + Send + Sync + 'static,

Define the read function of this attribute, with an exclusive access to the model, therefore no other command or attribute can access it in parallel.

Panics

If the advertised kind or format has already been defined incompatibly, see Self::kind and Self::format.

pub fn read_async_with<F>(self, func: F) -> Self

where F: for<'a> Fn(&'a M, &'a Dev<M>) -> BoxFuture<'a, Result<AttrRead<Value>>> + Send + Sync + 'static,

Define the read function of this attribute, asynchronously and with a shared access to the model. This is the raw form of Self::read_async, for a closure that boxes its future itself, see Self::read_with.

pub fn read_async<F>(self, func: F) -> Self

where F: for<'a> ReadAsync<'a, &'a M, M> + Send + Sync + 'static,

Define the read function of this attribute, asynchronously and with a shared access to the model, typically an async fn method of the model, see CommandDef::exec_async for what it is for and what it must not do.

Panics

If the advertised kind or format has already been defined incompatibly, see Self::kind and Self::format.

pub fn read_exclusive_async_with<F>(self, func: F) -> Self

where F: for<'a> Fn(&'a mut M, &'a Dev<M>) -> BoxFuture<'a, Result<AttrRead<Value>>> + Send + Sync + 'static,

Define the read function of this attribute, asynchronously and with an exclusive access to the model. This is the raw form of Self::read_exclusive_async, see Self::read_async_with.

pub fn read_exclusive_async<F>(self, func: F) -> Self

where F: for<'a> ReadAsync<'a, &'a mut M, M> + Send + Sync + 'static,

Define the read function of this attribute, asynchronously and with an exclusive access to the model, which no other command or attribute can then access until the future completes. See Self::read_async.

Panics

If the advertised kind or format has already been defined incompatibly, see Self::kind and Self::format.

pub fn write_with<F>(self, func: F) -> Self

where F: Fn(&M, &Dev<M>, Value) -> Result<()> + Send + Sync + 'static,

Define the write function of this attribute, with a shared access to the model. This is the raw form of Self::write, the written Value being given as-is and the advertised kind and format having to be given with Self::kind and Self::format.

pub fn write<F, I>(self, func: F) -> Self

where F: WriteShared<M, I> + Send + Sync + 'static,

Define the write function of this attribute, with a shared access to the model.

The value type is taken from the WriteShared implementation of the function, any FromValue type, a Buf sharing the written value rather than copying it.

Panics

If the advertised kind or format has already been defined incompatibly, which notably happens when the read function of the attribute does not use the same value type, see Self::kind and Self::format.

pub fn write_exclusive_with<F>(self, func: F) -> Self

where F: Fn(&mut M, &Dev<M>, Value) -> Result<()> + Send + Sync + 'static,

Define the write function of this attribute, with an exclusive access to the model. This is the raw form of Self::write_exclusive, see Self::write_with.

pub fn write_exclusive<F, I>(self, func: F) -> Self

where F: WriteExclusive<M, I> + Send + Sync + 'static,

Define the write function of this attribute, with an exclusive access to the model, which is what a write usually needs in order to store the written value.

Panics

If the advertised kind or format has already been defined incompatibly, which notably happens when the read function of the attribute does not use the same value type, see Self::kind and Self::format.

pub fn write_async_with<F>(self, func: F) -> Self

where F: for<'a> Fn(&'a M, &'a Dev<M>, Value) -> BoxFuture<'a, Result<()>> + Send + Sync + 'static,

Define the write function of this attribute, asynchronously and with a shared access to the model. This is the raw form of Self::write_async, see Self::read_async_with.

pub fn write_async<F, I>(self, func: F) -> Self

where F: for<'a> WriteAsync<'a, &'a M, M, I> + Send + Sync + 'static,

Define the write function of this attribute, asynchronously and with a shared access to the model, see Self::read_async.

Panics

If the advertised kind or format has already been defined incompatibly, see Self::write.

pub fn write_exclusive_async_with<F>(self, func: F) -> Self

where F: for<'a> Fn(&'a mut M, &'a Dev<M>, Value) -> BoxFuture<'a, Result<()>> + Send + Sync + 'static,

Define the write function of this attribute, asynchronously and with an exclusive access to the model. This is the raw form of Self::write_exclusive_async, see Self::read_async_with.

pub fn write_exclusive_async<F, I>(self, func: F) -> Self

where F: for<'a> WriteAsync<'a, &'a mut M, M, I> + Send + Sync + 'static,

Define the write function of this attribute, asynchronously and with an exclusive access to the model, which no other command or attribute can then access until the future completes. See Self::read_async.

Panics

If the advertised kind or format has already been defined incompatibly, see Self::write.

Trait Implementations

impl<M: Model> Debug for AttrDef<M>

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

Formats the value using the given formatter.