Struct DevProxy 

pub struct DevProxy { /* private fields */ }

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

Two device proxies are equal, and hash the same, when they use the same backend (compared by pointer) and have the same internal target, regardless of their trl, their connection or their configuration.

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 proxy 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_with_backend 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 proxy 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, or this device as a database if it is one. A device reached without a database fails with ErrorKind::DatabaseNeeded.

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<Scalar<str>>

Get the device status.

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

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<Spectrum<str>>

Request the device black box.

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

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 may fail the whole request, all of them travelling in a single one, depending on the backend.

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<RecordedResult<T>>>

The recorded history of a command, oldest entry first and at most max of them: what the polling of the device recorded, or the device itself, which may manage the history of a command it does not poll. Every entry is what the command answered then, converted into the type it is expected to be, a run that failed carrying the failure it failed with, see Recorded.

A command nothing was recorded of has no history to give, which is a failure and not an empty history, see ErrorKind::CommandNotPolled and ErrorKind::AttrNotPolled.

pub fn command_history<T: FromValue>( &self, name: &str, max: usize, ) -> Result<Vec<RecordedResult<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<RecordedResult<AttrRead<T>>>>

The recorded history of an attribute, see Self::command_history_async, a reading carrying the time it was recorded at as its own.

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

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

pub async fn poll_attr_async(&self, name: &str, period: Duration) -> Result<()>

Poll that attribute of this device at that period, or at another one if it is polled already, see the AddObjPolling and UpdObjPollingPeriod commands of the admin device.

pub fn poll_attr(&self, name: &str, period: Duration) -> Result<()>

Poll that attribute of this device, see Self::poll_attr_async.

pub async fn poll_command_async( &self, name: &str, period: Duration, ) -> Result<()>

Poll that command of this device, see Self::poll_attr_async: only a command taking no argument can be polled.

pub fn poll_command(&self, name: &str, period: Duration) -> Result<()>

Poll that command of this device, see Self::poll_command_async.

pub async fn stop_poll_attr_async(&self, name: &str) -> Result<()>

Stop polling that attribute of this device, failing if it is not polled, see the RemObjPolling command of the admin device.

pub fn stop_poll_attr(&self, name: &str) -> Result<()>

Stop polling that attribute of this device, see Self::stop_poll_attr_async.

pub async fn stop_poll_command_async(&self, name: &str) -> Result<()>

Stop polling that command of this device, see Self::stop_poll_attr_async.

pub fn stop_poll_command(&self, name: &str) -> Result<()>

Stop polling that command of this device, see Self::stop_poll_command_async.

pub async fn attr_poll_period_async( &self, name: &str, ) -> Result<Option<Duration>>

The period that attribute of this device is polled at, absent if it is not polled, out of its polling status, see Self::polling_status_async.

pub fn attr_poll_period(&self, name: &str) -> Result<Option<Duration>>

The period that attribute of this device is polled at, see Self::attr_poll_period_async.

pub async fn command_poll_period_async( &self, name: &str, ) -> Result<Option<Duration>>

The period that command of this device is polled at, see Self::attr_poll_period_async.

pub fn command_poll_period(&self, name: &str) -> Result<Option<Duration>>

The period that command of this device is polled at, see Self::command_poll_period_async.

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

The polling status of this device, one text per object polled, as its admin device gives it with its DevPollStatus command, none for a device that is not polled.

pub fn polling_status(&self) -> Result<Vec<String>>

The polling status of this device, see Self::polling_status_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 delete_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. delete_prop(&str) -> Result<()>
2. delete_prop(&[&str]) -> Result<()>
3. delete_prop([&str; N]) -> Result<()>
4. delete_prop((&str, &str, ...)) -> Result<()>

See DatabaseProxy::delete_dev_prop_async.

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

Delete the given properties of this device, see Self::delete_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<AttrReady>

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

pub fn subscribe_attr_config(&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

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 !=.