V4 CA Client User Interface

Channel Access Client User Interface

Under V4, a ProcessVariable would no longer be limited to the current properties 'value', 'units', ... but allow the users to create CA servers and clients that understand new properties.

The low-level V4 CA client API is likely to be rather complex because it now needs to handle arbitrary property catalogs.

• There still needs to be an easy to use high-level API, not much more complex than the existing one.
• There needs to be access to CA from languages like Matlab in a way that's as easy as

pv = caopen('fred');
value = caget(pv);

Food for thought

Is there anything we can learn from other communication libraries?

• A brief look at ZeroC ICE

Skeleton API

What follows is in the form of pseudo classes and associated methods that a CA client API should provide.

Directory

The directory is used to discover available channels and map them to the CA Server address and port.

• Directory(string URL-type-server-address = "")
  Constructor; uses site-specific default server or specific one. The 'URL' might contain a user & password, which decides if this name server connection is read-only (for OPI clients) or if writes are allowed (for IOCs that add PVs to the name server).
• getChannelInfo(string PV_or_pattern)
  Returns list of
  • CA server - IP & port of server that has the PV
  • quality - is this the IOC, a gateway, backup/primary
• addChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...)
  Used by CA servers to register their PV in directory
• deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...)
  Used by CA servers to remove their PV from directory

There is a default directory, available via something like "EPICSDefaults::getDirectory()" and "...setDirectory()". The implementation could use

• LDAP
• Broadcast (as before)
• your custom implementation
  as long as it uses the above interface and registers itself as the default.

Note that Ben argues to hide the directory lookup from the CA client us er. See separate V4 Name Server wiki for the issue of "record" and "PV" information.

Data Access

All the data is accessed via DataAccess, which handles the introspection of arbitrary data types. It should provide the following convenience routines in addition to whatever more efficient methods it might have (using hash IDs instead property name string etc.):

• list<string> getProperties()
  Get a list of all the properties
• type_info getType(string property)
• bool hasWriteAccess(string property)
• string getAsString(string property)

Channel

• Channel(string name, Directory dir = default)
  Constructor. Channel has to have a name. Uses the 'best' channel from the default directory or from a given directory.
• Channel(string name, CASInfo)
  ... in case you want a specific server after querying the directory yourself or not using a directory at all.
• getName()
  Returns the name of the channel.
• addListener(Listener l), removeListener(Listener l)
  Register for notifications, see below.
• getProperties()
  A read or subscription will return a dataAccess interface to the retrieved data. That might exclude properties that this client cannot access. It will include the data, which might be huge. This separate call will only get property information, no data, for all properties, including read/write access information. The result could be in the form of dataAccess, except all access to actual data yields empty results, only the property-info related part of dataAccess is functional.

Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.

Note also that in order to read or write, one needs to know what properties to access. Does the channel magically provide a list of all properties? Is there a "get all properties" request that reads them on-demand from the CA server? Or does the directory hold the list of available properties and their types?

Channel: Listener

The Channel::Listener interface is invoked in response to the many asynchronous methods of the Channel.

• writeComplete(Channel ch)
  • Channel that send this notification
• newData(Channel ch, DataAccess data, Event why)
  • DataAccess interface to the data
  • Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
• disconnected(Channel ch)
• accessRightChange(Channel ch)

Alternatively, these could be separate interfaces for a writeListener, dataListener, stateListener.

Channel: State

In contrast to the V3 API, the user doesn't 'connect'. The first data notification implies that we're connected.

• bool isConnected()
  .. for those who want to poll
• xxx getServerInfo(), xxx getType()
  .. only valid when isConnected().
• setUser(), ...
  Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime.

Channel: Writing

• write(new value)
  Sends the value to the server.
• createWriteRequest(new value, receipt {delivery, completion})
  Sends the value to the server, invokes Listener when CA server has received the value respectively all the processing triggered by the new value has completed.
• scheduleWriteRequest(new value, event)
  Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.

Channel: Reading

• createSubscription(list<property> what, Event e, Filter f)
  Will invoke Listener once data arrives.
  • event is a set of any of the following:
    • exceeded absolute value deadband, exceeded percentage change, exceeded logarithmic change
    • minimum update period expired
    • alarm condition change
    • some hardware event (like blue beam)
  • filters
    • override server-side idea of the value deadband, percentage change, log. change, minumum update rate, maximum update rate
    • specify value count
      setting this to '1' turns the subscription into a single-value 'get'
• cancelSubscription(Event, Filter)

SyncChannel

A wrapper class around the async. Channel. Uses a configurable timeout and provides synchronous 'read', 'write'.

Container

The Channel does not store any data. When attaching a container to a channel, the container will subscribe to the channel and keep a copy of all data, so one can always ask the container for the current values.

• attach(channel)
• detach()
• implements the DataAccess interface to allow access to the data.

caget 101

This is how a simple 'caget' could be written:

SyncChannel channel("fred"); 
DataAccess da = channel.read("value");
cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";
channel.disconnect();