# rsTango
Experimental project to create a new implementation of the Tango distributed control
system, from scratch, and benefiting from core Rust features, such as ownership,
lifetimes and its extensive generic type system.
This project is currently a personal project and is not affiliated with ESRF or the Tango
Controls community.
Here you can find the core specification of the exposed API below.
## Specification
Contrary to the current cppTango (and thus pyTango) implementation, the main goal is to
abstract away the actual backend being used, namely omniORB for the RPC, and ZeroMQ for
event system (which itself depends on omniORB).
```rust
/// root module, note that here we use a invalid rust syntax, just to define the interfaces
mod tango {
/// core support for device proxies
mod dev {
/// proxy connection to a device
struct DevProxy {
/// returns a new proxy given a TRL, if the TRL is valid (e.g. not targeting an attribute)
fn try_new(trl: impl IntoTrl) -> Option<Self>
/// same as `try_new` but unwraps
fn new(trl: impl IntoTrl) -> Self
/// cheap clone
impl Clone
/// test equality of the target
impl Eq
/// hash the target
impl Hash
/// returns the proxy for the database used to connect to the device
fn database(&mut self) -> Result<&mut DatabaseProxy>
/// resolves the fully-qualified TRL of this device
async fn trl(&mut self) -> Result<Trl>
/// resolves the fully-qualified device name (domain/family/member)
async fn name(&mut self) -> Result<String>
/// resolves the admin device and returns a proxy to it
async fn admin_dev(&mut self) -> Result<DevProxy>
/// ping the device
async fn ping(&mut self) -> Result<()>
/// request the device state
async fn state(&mut self) -> Result<DevState>
/// request the device status
async fn status(&mut self) -> Result<String>
/// request the black box
async fn black_box(&mut self, max: Option<usize>) -> Result<Vec<String>>
/// execute a command and returns a handle to its output, to be interpreted
async fn command_raw<'i, I: IntoData<'i>>(&mut self, name: &str, data: I) -> Result<CommandOutput>
/// execute a command with generic input and output data
async fn command<'i, I: IntoData<'i>, O: FromData<'_>>(&mut self, name: &str, data: I) -> Result<O>
/// read all attributes and return a handle to interpret them
async fn read_all_attr(&mut self) -> Result<ReadManyAttr>
/// read many attributes and return a handle to interpret them
async fn read_many_attr<Names: AsNames>(&mut self, names: Names) -> Result<ReadManyAttr>
/// read one or more attributes given a spec type and their names:
/// - with a spec type `T` and a single name `&'name str`, it returns a `AttrRead<'name, T>`
/// - with a spec type `T` and an array of names `[&'name str; N]`, it returns a `[AttrRead<'name, T>; N]`
/// - with a spec type `(A, B, ...)` and a tuple of names of the same size, it returns a `(AttrRead<'name, A>, AttrRead<'name, B>, ...)`
async fn read_attr<Spec: ReadAttrSpec<Names>, Names: AsNames>(&mut self, names: Names) -> Result<Spec::Output>
/// returns a builder for pushing many `AttrWrite<'name, ?>`
fn write_attr_builder<'data>(&mut self) -> WriteAttrBuilder<'_, 'data>
/// write one or more attributes given a spec of attributes:
/// - with a single `AttrWrite<'name, T>` value;
/// - with a single `(&'name str, T)` tuple, the `AttrWrite<'name, T>` is constructed on the fly with Valid quality and current time
/// - some type that implements `IntoIterator` of any of these types
/// - a tuple of any of these types
async fn write_attr<Spec: WriteAttrSpec<'_, '_>>(&mut self, attrs: Spec) -> Result<WriteManyAttr>
/// get information about all commands
async fn get_all_command_info(&mut self) -> Result<GetManyCommandInfo>
/// get command information about some specific commands
async fn get_many_command_info<Names: AsNames>(&mut self, names: Names) -> Result<GetManyCommandInfo>
/// read all attributes info
async fn get_all_attr_info(&mut self) -> Result<GetManyAttrInfo>
/// read many attributes info
async fn get_many_attr_info<Names: AsNames>(&mut self, names: Names) -> Result<GetManyAttrInfo>
// /// TODO:
// fn set_many_attr_config<'dev, 'name>(&mut self,) -> Result<()>
// /// TODO:
// async fn set_attr_config<Spec: SetAttrInfoSpec<'_>>(&mut self, info: Spec) -> Result<()>
/// subscribe to value events of given type on an attribute
async fn subscribe_attr_value<T: FromData<'_>>(&mut self, name: &str, event: AttrValueEvent) -> Result<AttrChannel<T>>
/// subscribe to read event on an attribute
async fn subscribe_attr_ready(&mut self, name: &str) -> Result<AttrReadyChannel>
/// list all properties of this device
async fn list_prop(&mut self) -> Result<Vec<String>>
/// get all properties for this device
async fn get_all_prop(&mut self) -> Result<GetManyProp>
/// get many properties from their names
async fn get_many_prop<Names: AsNames>(&mut self, names: Names) -> Result<GetManyProp>
/// forwarding to `DatabaseProxy::get_dev_prop`
async fn get_prop<Spec: GetPropSpec<Names>, Names: AsNames>(&mut self, names: Names) -> Result<Spec::Output>
/// create a builder for setting many properties at once on this device
fn set_prop_builder<'data>(&mut self) -> SetPropBuilder<'_, 'data>
/// forwarding to `DatabaseProxy::set_dev_prop`
async fn set_prop<Spec: SetPropSpec<'_>>(&mut self, props: Spec) -> Result<()>
/// forwarding to `DatabaseProxy::del_dev_prop`
async fn del_prop<Names: AsNames>(&mut self, names: Names) -> Result<()>
}
/// supporting the different ways of representing, attribute, command and various
/// names, by converting it to an orderer slice of strings
trait AsNames<'name>: Sealed {
type Slice: AsRef<[&'name str]>
fn into_slice(self) -> Self::Slice
}
/// supporting `DevProxy::command_raw`
struct CommandOutput {
/// try to parse the command output using the given type
fn get<'s, O: FromData<'s>>(&'s self) -> Result<O>
}
/// supporting `DevProxy::read_many_attr` and `read_all_attr`
/// default type for Names is when we request all attributes
struct ReadManyAttr {
/// returns the number of attributes read
fn len(&self) -> usize
/// try to parse the attribute values for the given type
fn get<'s, T: FromData<'s>>(&'s self, index: usize) -> Result<AttrRead<'s, T>>
}
/// supporting `DevProxy::read_attr`
trait ReadAttrSpec<Names>: Sealed {
type Output;
}
/// supporting `DevProxy::write_many_attr`
struct WriteAttrBuilder<'dev, 'data> {
/// returns the current number of attributes to be written
fn len(&self) -> usize
/// push a new attribute write value to this builder
fn push<T: IntoData<'data>>(&mut self, attr: AttrWrite<'data, T>)
/// write all values to the device, returning the result for each attribute
async fn write(self) -> Result<WriteManyAttr>
}
/// supporting `WriteManyAttrBuilder::write` and `DevProxy::write_attr`
struct WriteManyAttr {
/// returns the number of attributes that have been written
fn len(&self) -> usize
/// check the result of the attribute at given index
fn check(&self, index: usize) -> Result<()>
}
/// supporting `DevProxy::write_attr`
trait WriteAttrSpec: Sealed { }
/// supporting `DevProxy::get_many_attr_info`
/// default type for Names is when we request all attributes
struct GetManyAttrInfo {
/// the number of attributes
fn len(&self) -> usize
/// the information for a given attribute
fn get(&self, index: usize) -> Result<AttrInfo<'name>>
}
/// supporting `DevProxy::get_many_command_info`
/// default type for Names is when we request all attributes
struct GetManyCommandInfo {
/// the number of attributes
fn len(&self) -> usize
/// the information for a given attribute
fn get(&self, index: usize) -> Result<CommandInfo<'name>>
}
/// failure stack for device
struct DevFailed {
/// create a new empty failure stack
const fn new() -> Self
fn push_frame(&mut self, frame: DevFailFrame)
fn with_frame(mut self, frame: DevFailFrame) -> Self
/// last frame refers to the origin of the failure propagation
fn frames(&self) -> &[DevFailFrame]
/// constructing the failed stack in order
impl FromIterator<DevFailFrame>
}
struct DevFailFrame {
reason: String
severity: DevFailSeverity
description: String
origin: String
}
enum DevFailSeverity {
Warning
Error
Panic
}
struct CommandInfo<'name> {
/// The name of the read attribute.
name: Cow<'name, str>
/// The display level of the attribute.
display_level: DisplayLevel
/// Input data kind.
in_kind: DataKind
/// Output data kind.
out_kind: DataKind
/// Description for the output data.
in_description: Option<String>
/// Description for the input data.
out_description: Option<String>
}
struct AttrRead<'name, T> {
name: Cow<'name, str>
value: Option<T>
w_value: Option<T>
quality: AttrQuality
time: SystemTime
}
struct AttrWrite<'name, T> {
name: Cow<'name, str>
value: Option<T>
quality: AttrQuality
time: SystemTime
}
enum AttrQuality {
Valid
Invalid
Alarm
Changing
Warning
}
struct AttrInfo<'name> {
config: AttrConfig<'name>
mode: AttrMode<'name>
data_kind: DataKind
}
enum AttrMode<'name> {
Read
ReadWithWrite {
write_attr_name: Cow<'name, str>
}
Write
ReadWrite
}
struct AttrConfig<'name> {
name: Cow<'name, str>
description: Option<String>
label: Option<String>
}
/// all the device states
enum DevState {
On
Off
Close
Open
Insert
Extract
Moving
Standby
Fault
Init
Running
Alarm
Disable
Unknown
}
enum DevSource {
Dev
Cache
CacheDev
}
enum DisplayLevel {
Operator
Expert
}
enum AttrValueEvent {
Change
Periodic
Archive
User
Alarm
}
struct AttrChannel<T> {
/// indefinitely wait for an attribute to have a new value
async fn wait<T: FromData<'_>>(&mut self) -> Result<AttrRead<'_, T>>
}
struct AttrReadyChannel {
/// indefinitely wait for an attribute to be ready
async fn wait(&mut self) -> Result<&'_ str>
}
}
/// wrapper around device proxy but with standard interface for databases.
mod database {
/// a wrapper around a DevProxy that is known to be a database
struct DatabaseProxy {
/// new proxy to the environment database(s) (TANGO_HOST)
fn new_from_env() -> Self
/// new proxy to a specific data
fn new(host: &str, port: u16) -> Self
/// request a device for import on the database (DbImportDevice)
async fn import_dev(&mut self, dev_name: &str) -> Result<Option<ImportDevInfo>>
/// list all free properties given a wildcard (DbGetPropertyList)
async fn list_free_prop(&mut self, obj_name: &str, wildcard: &str) -> Result<Vec<String>>
/// list all class properties given a wildcard (DbGetClassPropertyList/DbGetClassPropertyListWildcard)
async fn list_class_prop(&mut self, class_name: &str, wildcard: &str) -> Result<Vec<String>>
/// list all device properties given a wildcard (DbGetDevicePropertyList)
async fn list_dev_prop(&mut self, dev_name: &str, wildcard: &str) -> Result<Vec<String>>
/// return a handle for reading all properties of an object
async fn get_all_free_prop(&mut self, obj_name: &str) -> Result<GetManyProp>
/// return a handle for reading all properties of a class
async fn get_all_class_prop(&mut self, class_name: &str) -> Result<GetManyProp>
/// return a handle for reading all properties of a device
async fn get_all_dev_prop(&mut self, dev_name: &str) -> Result<GetManyProp>
/// return a handle for reading many properties of an object (DbGetProperty)
async fn get_many_free_prop<Names: AsNames>(&mut self, obj_name: &str, names: Names) -> Result<GetManyProp>
/// return a handle for reading many properties of a class (DbGetClassProperty)
async fn get_many_class_prop<Names: AsNames>(&mut self, class_name: &str, names: Names) -> Result<GetManyProp>
/// return a handle for reading many properties of a device (DbGetDeviceProperty)
async fn get_many_dev_prop<Names: AsNames>(&mut self, dev_name: &str, names: Names) -> Result<GetManyProp>
/// get one or multiple object properties
async fn get_free_prop<Spec: GetPropSpec<Names>, Names: AsNames>(&mut self, obj_name: &str, names: Names) -> Result<Spec::Output>
/// get one or multiple class properties
async fn get_class_prop<Spec: GetPropSpec<Names>, Names: AsNames>(&mut self, class_name: &str, names: Names) -> Result<Spec::Output>
/// get one or multiple device properties
async fn get_dev_prop<Spec: GetPropSpec<Names>, Names: AsNames>(&mut self, dev_name: &str, names: Names) -> Result<Spec::Output>
/// returns a new builder for setting one or multiple object properties (DbPutProperty)
async fn set_free_prop_builder<'data>(&mut self, obj_name: &'data str) -> SetPropBuilder<'_, 'data>
/// returns a new builder for setting one or multiple class properties (DbPutClassProperty)
async fn set_class_prop_builder<'data>(&mut self, class_name: &'data str) -> SetPropBuilder<'_, 'data>
/// returns a new builder for setting one or multiple device properties (DbPutDeviceProperty)
async fn set_dev_prop_builder<'data>(&mut self, dev_name: &'data str) -> SetPropBuilder<'_, 'data>
/// set one or multiple object properties
async fn set_free_prop<'data, Spec: SetPropSpec<'data>>(&mut self, obj_name: &'data str, props: Spec) -> Result<()>
/// set one or multiple class properties
async fn set_class_prop<'data, Spec: SetPropSpec<'data>>(&mut self, class_name: &'data str, props: Spec) -> Result<()>
/// set one or multiple device properties
async fn set_dev_prop<'data, Spec: SetPropSpec<'data>>(&mut self, dev_name: &'data str, props: Spec) -> Result<()>
/// delete many device properties (DbDeleteProperty)
async fn del_free_prop<Names: AsNames>(&mut self, obj_name: &str, names: Names) -> Result<()>
/// delete many device properties (DbDeleteClassProperty)
async fn del_class_prop<Names: AsNames>(&mut self, class_name: &str, names: Names) -> Result<()>
/// delete many device properties (DbDeleteDeviceProperty)
async fn del_dev_prop<Names: AsNames>(&mut self, dev_name: &str, names: Names) -> Result<()>
}
struct ImportDevInfo {
exported: bool
pid: i32
name: String
itr: String
version: String
server: String
host: String
class: Option<String>
}
struct PropValue<'name, T> {
name: Cow<'name, T>
value: T
}
struct GetManyProp<'name, Names: AsNames<'name> = ()> {
fn len(&self) -> usize
fn get<'d, T: FromProp<'d>>(&'d self, index: usize) -> Result<PropValue<'name, T>>
impl Debug
}
}
/// parsing of TRL
mod trl {
/// represents a validated Tango Resource Locator
struct Trl {
/// returns the string representation
fn as_str(&self) -> &str
/// if present, returns host/port
fn host_and_port(&self) -> Option<(&str, u16)>
/// returns the pointed object
fn object(&self) -> TrlObject<'_>
/// if present, returns the property pointed on the object
fn property(&self) -> Option<&str>
/// returns false if database should not be used (#dbase=no)
fn db(&self) -> bool
/// for parsing the TRL from any string
impl FromStr<Err = ParseTrlError>
}
/// represent the different kind of object pointed by a TRL
enum TrlObject<'a> {
/// an alias for a device or an attribute
Alias(&'a str)
/// a device name
Dev(&'a str)
/// a device name + attribute name
Attr(&'a str, &'a str)
}
/// for types that can be parsed into a TRL
trait IntoTrl {
fn into_trl(self) -> Result<Trl, ParseTrlError>
/// returns itself
impl for Trl
/// forward to FromStr
impl for &'_ str
}
/// parsing error
enum ParseTrlError {
InvalidProtocol
InvalidHost
InvalidPort
InvalidHash
InvalidPath
InvalidDeviceName
InvalidAttrName
InvalidAlias
InvalidPropertyName
}
}
/// general error handling for Tango
mod error {
/// result type alias
type Result<T> = std::result::Result<T, Error>
/// the common error type
enum Error {
NotHandled
DatabaseNotConnected
DatabaseNeeded
DevNotFound
ServerNotConnected
DevNotConnected
CommandNameInvalid
CommandNotFound
AttrNameInvalid
AttrNotFound
AttrNotWritable
EventNotConnected
InvalidIndex
Data(Box<str>)
TimedOut
Failed(DevFailed)
Internal(#[source] Box<dyn Error + Send + Sync>)
}
}
}