Struct DevProxy 

pub struct DevProxy { /* private fields */ }

A device proxy is an object that allows querying a remote device.

Equality and hash between two device proxies is defined by if their target is similar or not, not the actual backend being identical!

The Eq and Hash implementation is entirely based on the internal target of of the device, not its trl, nor its actual implementation details.

Implementations

impl DevProxy

pub fn new<'a>(trl: impl IntoTrl<'a>) -> Self

Same as Self::try_new but panics if the TRL is invalid for a device proxy.

pub fn try_new<'a>(trl: impl IntoTrl<'a>) -> Option<Self>

Create a new device proxy located by the given Tango Resource Locator, the given TRL should not target an attribute or property, or else this function will return None.

pub fn new_from_database(database: &DatabaseProxy, name: &str) -> Self

Create a new device from a database and the device’s name.

pub fn new_with_backend<'a>( backend: Arc<dyn Backend>, trl: impl IntoTrl<'a>, ) -> Self

Same as Self::try_new but panics if the TRL is invalid for a device proxy.

pub fn try_new_with_backend<'a>( backend: Arc<dyn Backend>, trl: impl IntoTrl<'a>, ) -> Option<Self>

Create a new device proxy located by the given Tango Resource Locator, the given TRL should not target an attribute or property, or else this function will return None.

pub fn new_from_database_with_backend( backend: Arc<dyn Backend>, database: &DatabaseProxy, name: &str, ) -> Self

Create a new device from a database and the device’s name, with backend.

pub fn backend(&self) -> &Arc<dyn Backend>

pub fn timeout(&self) -> Duration

Retrieve the timeout duration currently used for all requests.

pub fn set_timeout(&mut self, timeout: Duration) -> Duration

Set the timeout duration and return the previous one. See Self::timeout.

pub fn source(&self) -> DevSource

Retrieve the source of data currently used for attribute readings and commands.

pub fn set_source(&mut self, source: DevSource) -> DevSource

Set the source of data and return the previous one. See Self::source.

pub fn database(&self) -> Result<&DatabaseProxy>

Return the DatabaseProxy this device has been requested from! If the device is no db and is not a database, then it returns None.

pub fn trl(&self) -> Result<ArcTrl>

Resolve this device’s fully qualified device name.

pub fn connect(&self) -> Result<()>

Connect this proxy to its device if that has not happened yet, so that its clones share that connection instead of each making its own.

pub async fn connect_async(&self) -> Result<()>

Connect this proxy to its device if that has not happened yet, see Self::connect.

pub fn name(&self) -> Result<Arc<str>>

Resolve this device’s name.

pub async fn name_async(&self) -> Result<Arc<str>>

Resolve this device’s name, see Self::name.

pub fn admin_dev_name(&self) -> Result<Arc<str>>

Resolve this device’s admin device name.

pub async fn admin_dev_name_async(&self) -> Result<Arc<str>>

Resolve this device’s admin device name, see Self::admin_dev_name.

pub fn admin_dev(&self) -> Result<DevProxy>

Resolve this device’s admin device and return it!

pub async fn admin_dev_async(&self) -> Result<DevProxy>

Resolve this device’s admin device and return it, see Self::admin_dev.

pub fn info(&self) -> Result<DevInfo>

Get what the device says it is: the class it is an instance of, the server running it and where, and the versions of whatever that server is built out of.

All of it is the server’s own description of itself and none of it is asked of the database, so it answers for a device served without one.

pub async fn info_async(&self) -> Result<DevInfo>

Get what the device says it is, see Self::info.

pub fn ping(&self) -> Result<()>

Ping this device.

pub async fn ping_async(&self) -> Result<()>

Ping this device, see Self::ping.

pub fn state(&self) -> Result<DevState>

Get the device state.

pub async fn state_async(&self) -> Result<DevState>

Get the device state, see Self::state.

pub fn status(&self) -> Result<String>

Get the device status.

pub async fn status_async(&self) -> Result<String>

Get the device status, see Self::status.

pub fn init(&self) -> Result<()>

Initialize the device again, executing its Init command.

pub fn init_async(&self) -> impl Future<Output = Result<()>> + Send

Initialize the device again, see Self::init.

pub fn black_box(&self, max: Option<usize>) -> Result<Vec<String>>

Request the device black box.

pub async fn black_box_async(&self, max: Option<usize>) -> Result<Vec<String>>

Request the device black box, see Self::black_box.

pub fn command_async<I, O>( &self, name: &str, input: I, ) -> impl Future<Output = Result<O>> + Send

where I: IntoValue, O: FromValue,

Execute a remote command, giving back what it answered with, converted into the type it is expected to be, see FromValue.

The value shares the octets the device answered with, so asking for a Value or for one of the buffers it holds — a crate::value::Spectrum of a million points above all — copies nothing, where the usual owned types are copied out of it.

pub fn command<I, O>(&self, name: &str, input: I) -> Result<O>

where I: IntoValue, O: FromValue,

Execute a remote command, giving back what it answered with, see Self::command_async.

pub fn read_attr_async<Spec, Names: ToNames>( &self, names: Names, ) -> impl Future<Output = Result<Spec::Output>> + Send

where Spec: ReadAttrSpec<Names>,

Read attributes given a specification of attributes. This specification is really flexible and allows various signatures for the function:

1. read_attr<T>(&str) -> Result<AttrRead<T>>
2. read_attr<T>(&[&str]) -> Result<Vec<Result<AttrRead<T>>>>
3. read_attr<T>([&str; N]) -> Result<[Result<AttrRead<T>>; N]>
4. read_attr<(A, B, ...)>((&str, &str, ...)) -> Result<(Result<AttrRead<A>>, Result<AttrRead<B>>, ...)>
5. read_attr<T>(All) -> Result<Vec<NamedResult<AttrRead<T>>>>

Forms 1 to 3 and 5 convert every attribute into the same type, whereas form 4 gives each attribute its own type. Nothing in the names constrains the specification, so it has to come either from a turbofish, leaving the names inferred as in read_attr::<i16, _>("enum_scalar"), or from the type of the binding it is assigned to. Reading into a Value keeps whatever the device answered with, and reading into a buffer copies nothing, see Self::command_async.

Each reading comes with the Result of that one reading, so that a per-attribute failure is seen without the whole request failing. Note that, unlike the many-attributes forms, the single-attribute form has no per-attribute slot in its output and therefore returns that attribute’s error directly. The fixed-size forms 3 and 4 additionally fail with ErrorKind::Internal if the device does not answer with exactly as many readings as were requested.

All requested attributes are read within a single request, which matters beyond saving round trips: if the device enforces serialization, it is held for the whole batch and only released at the end, so the readings are consistent with each other instead of being sampled at instants another client could have written between.

pub fn read_attr<Spec, Names: ToNames>( &self, names: Names, ) -> Result<Spec::Output>

where Spec: ReadAttrSpec<Names>,

Read attributes, see Self::read_attr_async.

pub fn write_attr_async<'a, Spec>( &self, spec: Spec, ) -> impl Future<Output = Result<Spec::Output>> + Send

where Spec: WriteAttrSpec<'a>,

Write attributes given a specification of attributes and their values, giving back the outcome of each individual write, in the order they were given. In Tango a write only carries a value: quality and timestamp cannot be written. Like for Self::read_attr, this specification is really flexible and allows various signatures for the function:

1. write_attr((&str, T)) -> Result<()>
2. write_attr(Vec<(&str, T)>) -> Result<Vec<Result<()>>>
3. write_attr([(&str, T); N]) -> Result<[Result<()>; N]>
4. write_attr(((&str, A), (&str, B), ...)) -> Result<(Result<()>, Result<()>, ...)>

Each written value only needs to implement IntoValue, so unlike for Self::read_attr the value types are inferred from the specification and never have to be named. Note that, unlike the many-attributes forms, the single-attribute form has no per-attribute slot in its output and therefore returns that attribute’s error directly. The fixed-size forms 3 and 4 fail with ErrorKind::Internal if the device does not answer for exactly as many attributes as were written.

pub fn write_attr<'a, Spec>(&self, spec: Spec) -> Result<Spec::Output>

where Spec: WriteAttrSpec<'a>,

Write attributes, see Self::write_attr_async.

pub fn write_read_attr_async<'a, Spec>( &self, spec: Spec, ) -> impl Future<Output = Result<<Spec::ReadSpec as ReadAttrSpec<Spec::ReadNames>>::Output>> + Send

where Spec: WriteAttrSpec<'a>, Spec::ReadSpec: ReadAttrSpec<Spec::ReadNames>,

Write attributes and read them back, given the same flexible specification as Self::write_attr, but returning the read-back values instead of unit results. Each value is converted back into the very type that was written:

1. write_read_attr((&str, T)) -> Result<AttrRead<T>>
2. write_read_attr(Vec<(&str, T)>) -> Result<Vec<Result<AttrRead<T>>>>
3. write_read_attr([(&str, T); N]) -> Result<[Result<AttrRead<T>>; N]>
4. write_read_attr(((&str, A), (&str, B), ...)) -> Result<(Result<AttrRead<A>>, Result<AttrRead<B>>, ...)>

The read is done by the server right after the write, so this saves a round trip compared to a Self::write_attr followed by a Self::read_attr, and no other request can interleave between the two when the device enforces serialization.

Because the read-back is converted back into the written type, each value type must also implement FromValue here, whereas Self::write_attr only requires IntoValue.

pub fn write_read_attr<'a, Spec>( &self, spec: Spec, ) -> Result<<Spec::ReadSpec as ReadAttrSpec<Spec::ReadNames>>::Output>

where Spec: WriteAttrSpec<'a>, Spec::ReadSpec: ReadAttrSpec<Spec::ReadNames>,

Write attributes and read them back, see Self::write_read_attr_async.

pub fn command_info_async<Spec: ToNamesSpec<CommandInfo>>( &self, spec: Spec, ) -> impl Future<Output = Result<Spec::Output>> + Send

Get the static information of commands, given the same flexible specification of names as Self::read_attr takes:

1. command_info(&str) -> Result<CommandInfo>
2. command_info(&[&str]) -> Result<Vec<Result<CommandInfo>>>
3. command_info([&str; N]) -> Result<[Result<CommandInfo>; N]>
4. command_info(All) -> Result<Vec<NamedResult<CommandInfo>>>

Every command comes with the Result of that one command, an unknown command name and a data type that no CommandDataKind has a variant for being the two the device answers with.

Note that, unlike the attributes, the Tango interface has no operation taking a list of command names, so asking for several of them costs one request each, where All only costs one for the whole listing.

pub fn command_info<Spec: ToNamesSpec<CommandInfo>>( &self, spec: Spec, ) -> Result<Spec::Output>

Get the static information of commands, see Self::command_info_async.

pub fn attr_info_async<Spec: ToNamesSpec<AttrInfo>>( &self, spec: Spec, ) -> impl Future<Output = Result<Spec::Output>> + Send

Get the static information of attributes, their runtime-modifiable configuration included, given the same flexible specification of names as Self::read_attr takes:

1. attr_info(&str) -> Result<AttrInfo>
2. attr_info(&[&str]) -> Result<Vec<Result<AttrInfo>>>
3. attr_info([&str; N]) -> Result<[Result<AttrInfo>; N]>
4. attr_info(All) -> Result<Vec<NamedResult<AttrInfo>>>

Every attribute comes with the Result of that one attribute, a data type that no AttrDataKind has a variant for being what the device answers with. Unlike the commands, an unknown attribute name fails the whole request, all of them travelling in a single one.

pub fn attr_info<Spec: ToNamesSpec<AttrInfo>>( &self, spec: Spec, ) -> Result<Spec::Output>

Get the static information of attributes, see Self::attr_info_async.

pub async fn set_attr_config_async( &self, values: &[(&str, AttrConfig)], ) -> Result<Vec<Result<()>>>

Change the configuration of the given attributes, giving back the outcome of each individual change, in the order they were given.

Only the configuration is writable, which is the part of an AttrInfo that a client is allowed to set: what an attribute is — its mode, its data kind and its format — is what its definition says and is never written from the outside.

The whole configuration of an attribute goes out every time, so changing one property of it is reading the configuration with Self::attr_info and writing back what was read with that one property changed, which is what the protocol carries.

A field with no value brings it back to what the attribute inherits from its class, if anything.

pub fn set_attr_config( &self, values: &[(&str, AttrConfig)], ) -> Result<Vec<Result<()>>>

Change the configuration of the given attributes, see Self::set_attr_config_async.

pub async fn command_history_async<T: FromValue>( &self, name: &str, max: usize, ) -> Result<Vec<(SystemTime, Result<T>)>>

The recorded history of a command, which is what the polling of the device left behind, oldest entry first and at most max of them, every entry being the time the run was recorded at and what the command answered then, converted into the type it is expected to be, a run that failed carrying the failure it failed with.

A device that is not polled has no history to give, which is a failure and not an empty history: nothing was recorded because nothing is recording.

pub fn command_history<T: FromValue>( &self, name: &str, max: usize, ) -> Result<Vec<(SystemTime, Result<T>)>>

The recorded history of a command, see Self::command_history_async.

pub async fn attr_history_async<T: FromValue>( &self, name: &str, max: usize, ) -> Result<Vec<Result<AttrRead<T>>>>

The recorded history of an attribute, see Self::command_history_async, the timestamp of every entry being the one the reading itself carries.

pub fn attr_history<T: FromValue>( &self, name: &str, max: usize, ) -> Result<Vec<Result<AttrRead<T>>>>

The recorded history of an attribute, see Self::attr_history_async.

pub async fn list_prop_async(&self, filter: &str) -> Result<Spectrum<str>>

The names of the properties of this device that match the given filter.

pub fn list_prop(&self, filter: &str) -> Result<Spectrum<str>>

The names of the properties of this device, see Self::list_prop_async.

pub fn get_prop_async<Spec, Names: ToNames>( &self, names: Names, ) -> impl Future<Output = Result<Spec::Output>> + Send

where Spec: GetPropSpec<Names>,

The properties of this device, parsed into the shape the given names ask for. Like for Self::read_attr, this specification is really flexible and allows various signatures for the function:

1. get_prop<T>(&str) -> Result<T>
2. get_prop<T>(&[&str]) -> Result<Vec<Result<T>>>
3. get_prop<T>([&str; N]) -> Result<[Result<T>; N]>
4. get_prop<(A, B, ...)>((&str, &str, ...)) -> Result<(Result<A>, Result<B>, ...)>
5. get_prop<Spectrum<str>>(All) -> Result<Vec<Named<Spectrum<str>>>>

See DatabaseProxy::get_dev_prop_async for what the values may be parsed into and what a property the database holds nothing for gives.

pub fn get_prop<Spec, Names: ToNames>( &self, names: Names, ) -> Result<Spec::Output>

where Spec: GetPropSpec<Names>,

The properties of this device, see Self::get_prop_async.

pub fn set_prop_async<'a, Spec>( &self, spec: Spec, ) -> impl Future<Output = Result<()>> + Send

where Spec: SetPropSpec<'a>,

Write the given properties of this device, given as pairs of a name and a value, which allows various signatures for the function:

1. set_prop((&str, T)) -> Result<()>
2. set_prop([(&str, T); N]) -> Result<()>
3. set_prop(Vec<(&str, T)>) -> Result<()>
4. set_prop(((&str, A), (&str, B), ...)) -> Result<()>

See DatabaseProxy::set_dev_prop_async for what the values may be.

pub fn set_prop<'a, Spec>(&self, spec: Spec) -> Result<()>

where Spec: SetPropSpec<'a>,

Write the given properties of this device, see Self::set_prop_async.

pub fn del_prop_async<Names: ToNamesNotAll>( &self, names: Names, ) -> impl Future<Output = Result<()>> + Send

Delete the given properties of this device, which allows various signatures for the function:

1. del_prop(&str) -> Result<()>
2. del_prop(&[&str]) -> Result<()>
3. del_prop([&str; N]) -> Result<()>
4. del_prop((&str, &str, ...)) -> Result<()>

See DatabaseProxy::del_dev_prop_async.

pub fn del_prop<Names: ToNamesNotAll>(&self, names: Names) -> Result<()>

Delete the given properties of this device, see Self::del_prop_async.

pub fn subscribe_attr_value<T: FromValue>( &self, name: &str, event: AttrValueEvent, ) -> DevChannel<AttrRead<T>>

Subscribe to the readings of an attribute, of one of the kinds a device pushes them under, the channel giving the latest of them, see DevChannel.

Nothing is subscribed until the channel is polled, or its subscription ensured, see DevChannel::ensure_subscribed_async. There is no initial value: the first event is the next one the device pushes, so read the attribute once subscribed to know where it stands.

pub fn subscribe_attr_ready(&self, name: &str) -> DevChannel<()>

Subscribe to an attribute being announced as ready to be read, which carries nothing of the attribute: reading it is the subscriber’s to do. See Self::subscribe_attr_value.

pub fn subscribe_attr_conf(&self, name: &str) -> DevChannel<AttrInfo>

Subscribe to the configuration of an attribute changing, every event carrying the configuration as it stands after the change. See Self::subscribe_attr_value.

Trait Implementations

impl Clone for DevProxy

This clone implementation might block if the device proxy is being initialized with a backend at the same time, but it should not be an issue and with eventually timeout if necessary.

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DevProxy

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

Formats the value using the given formatter.

impl Eq for DevProxy

impl Hash for DevProxy

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for DevProxy

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.