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).

/// 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>)
    }

  }

}