Using the catools Library#

Overview#

The cothread.catools library provides the following functions for access to EPICS “process variables” over channel access:

caget(pvs, ...): Returns a single snapshot of the current value of each PV.
caput(pvs, values, ...): Writes values to one or more PVs.
camonitor(pvs, callback, ...): Receive notification each time any of the listed PVs changes.
connect(pvs, ...): Can be used to establish a connection to a list of PVs before calling the other routines. This routine is optional.

To use these functions a certain amount of setup work is required. The following code illustrates a simple application which reads a value from one PV, writes to another PV, and monitors a third until terminated with control-C:

# Library version specification required for dls libraries
from pkg_resources import require
require('cothread')

import cothread
from cothread.catools import *

# Using caput: write 1234 into PV1.  Raises exception on failure
caput('PV1', 1234)

# Print out the value reported by PV2.
print(caget('PV2'))

# Monitor PV3, printing out each update as it is received.
def callback(value):
    print('callback', value)
camonitor('PV3', callback)

# Now run the camonitor process until interrupted by Ctrl-C.
cothread.WaitForQuit()

The following details are general to all cothread applications.

At Diamond the routine pkg_resources.require must be used to specify a particular version of the library to use, thus the following lines are required at the start of any catools application (Python2 only):
```
from pkg_resources import require
require('cothread==2.6')
```
or if the most recent version is ok then the version number can be omitted as in the example.
Any EPICS_CA_ environment variables should be set at this point, before importing cothread.catools (see Environment Variables below).
Of course, the libraries must be imported. The cothread.catools library is a sub-module of the cothread library, and can be imported separately.
If camonitor() is being used then the program should suspend in an event loop of some sort. The routine cothread.WaitForQuit() can be used, as otherwise the camonitor() activity has no opportunity to run before the program exits!

Environment Variables#

A number of environment variables affect the operation of channel access. These can be set using the os.environ dictionary – but note that these need to be set before loading the cothread.catools module. The following are documented in the EPICS channel access developers manual.

EPICS_CA_MAX_ARRAY_BYTES: Configures the maximum number of bytes that can be transferred in a single channel access message.
EPICS_CA_ADDR_LIST: A space separated list of channel access server addresses.
EPICS_CA_AUTO_ADDR_LIST: If set to NO the automatic scanning of networks is disabled.
EPICS_CA_CONN_TMO: Connection timeout, 30 seconds by default.
EPICS_CA_BEACON_PERIOD: Beacon polling period, 15 seconds by default.
EPICS_CA_SERVER_PORT, EPICS_CA_REPEATER_PORT: Set these to configure the ports used to connect to channel access. By default ports 5064 and 5065 are used respectively.

Example code:

import os
os.environ['EPICS_CA_MAX_ARRAY_BYTES'] = '1000000'

# Note: the first import of catools must come after the environ is set up.
from cothread.catools import *

Function Reference#

The catools API consists of the three functions caput(), caget() and camonitor() together with an auxilliary connect() function. The functions caget() and camonitor() return or deliver “augmented” values which are documented in more detail in the section Working with Values.

Common Notes#

All four functions take an argument pvs which can specify the name of a single PV or can be a list of PVs. In all cases the returned result has the same “shape” as the pvs argument, in other words, if pvs is a single string then a single value (error code, value, or subscription) is returned, and if pvs is a list then a list of exactly the same length is returned.

In general there are advantages to calling caput(), caget() or connect() on a list of PVs, as in this case the channel connection and access delays will occur in parallel.

Several arguments are common through this API: throw determines how errors are handled, timeout determines timeouts, and finally datatype, format and count determine data formats and are documented in Augmented Values.

timeout

The timeout argument specified how long caput() or caget() will wait for the entire operation to complete. This timeout is in seconds, and can be one of several formats: a timeout interval in seconds, an absolute deadline (in time.time() format) as a single element tuple, or None to specify that no timeout will occur. Note that a timeout of 0 will timeout immediately if any waiting is required.

If a timeout occurs then a Timedout exception will be raised unless throw=False has been set.

throw: This parameter determines the behaviour of caget(), caput(), and connect() when an error occurs. If throw=True (the default) is set then an exception is raised, otherwise if False is specified an error code value is returned for each failing PV.

Functions#

cothread.catools.caput(pvs, values, repeat_value=False, datatype=None, wait=False, timeout=5, callback=None, throw=True)#

Writes values to one or more PVs. If pvs is a single string then values is treated as a single value to be written to the named process variable, otherwise pvs must be iterable, and unless repeat_value=True is set, values must also be an iterable of the same length in which case values[i] is written to pvs[i]. Otherwise, if a single value is given or if repeat_value=True is specified, values is written to all PVs.

Parameters:

repeat_value – When writing a value to a list of PVs ensures that values is treated as a single value to be written to each PV.
datatype – See documentation for Augmented Values below. Used to force transmitted data to the requested format, or select special alarm acknowledgement handling. Note that only standard Python type conversion will be done, in particular conversion to and from strings is not automatic.
wait – If wait=True is specified then channel access put with callback is invoked, and the caput() operation will wait until the server acknowledges successful completion before returning.
callback – If a callback is specified then channel access put with callback is invoked and the given callback function will be called with the put response as a ca_nothing object passed as the only argument. All caput() callbacks will will be called on a dedicated caput callback thread. Unless wait is specified the call to caput will complete as soon as the caput has been initiated. If wait is specified, whether caput returns before or after callback is called is unpredictable.
timeout – Documented in Common Notes above.
throw – Documented in Common Notes above.

The return value from caput() is either a list or a single value, depending on the shape of pvs. For each PV a ca_nothing success code is returned on success, otherwise either an exception is raised or an appropriate error code is returned for each failing PV if throw=True is set. The return code can be tested for boolean success, so for example it is possible to write:

if not caput(pv, value, throw=False):
    # process caput error

If all the PVs listed in pvs have already been connected, through a successful call to any catools method, then the library guarantees that the puts for each PV will occur strictly in sequence. For any PVs which need a connection to be established the order of execution of puts is completely undefined.

cothread.catools.caget(pvs, timeout=5, datatype=None, format=FORMAT_RAW, count=0, throw=True)#

Retrieves a value from one or more PVs. If pvs is a single string then a single value is returned, otherwise a list of values is returned. Each value returned is an Augmented Values, see below for details.

If .ok is False then the errorcode field is set to the appropriate ECA_ error code and str(value) will return an error message.

The various arguments control the behaviour of caget() as follows:

datatype, format, count: See documentation for Augmented Values below.
timeout, throw: Documented in Common Notes above. If a value cannot be retrieved and throw=False is set then for each failing PV an empty value with .ok==False is returned.

The format of values returned depends on the number of values requested for each PV. If only one value is requested then the value is returned as a scalar, otherwise as a numpy array.

cothread.catools.camonitor(pvs, callback, events=None, datatype=None, format=FORMAT_RAW, count=0, all_updates=False, notify_disconnect=False, connect_timeout=None)#

Creates a subscription to one or more PVs, returning a subscription object for each PV. If a single PV is given then a single subscription object is returned, otherwise a list of subscriptions is returned.

Subscriptions will remain active until the close() method is called on the returned subscription object.

The precise way in which the callback routine is called on updates depends on whether pvs is a single name or a list of names. If it is single name then it is called as:

callback(value)

for each update. If pvs is a list of names then each update is reported as:

callback(value, index)

where index is the position in the original array of PVs of the PV generating this update. The values passed to callback are Augmented Values.

The parameters modify the behaviour as follows:

Parameters:

events –

This identifies the type of update which will be notified. A bit-wise or of any the following are possible:

Flag	Description
DBE_VALUE	Notify normal value changes
DBE_LOG	Notify archive value changes
DBE_ALARM	Notify alarm state changes
DBE_PROPERTY	Notify property changes (on 3.14.11 and later servers)

If events is not specified then the default value depends on the value selected for format as follows:

`format`	Default value for `events`
FORMAT_RAW	DBE_VALUE
FORMAT_TIME	DBE_VALUE \| DBE_ALARM
FORMAT_CTRL	DBE_VALUE \| DBE_ALARM \| DBE_PROPERTY

datatype – See documentation for Augmented Values below.
format – See documentation for Augmented Values below.
count – See documentation for Augmented Values below.
all_updates –
If this is True then every update received from channel access will be delivered to the callback, otherwise multiple updates received between callback queue dispatches will be merged into the most recent value.

If updates are being merged then the value returned will be augmented with a field .update_count recording how many updates occurred on this value.
notify_disconnect – If this is True then IOC disconnect events and channel access error reports will be reported by calling the callback with a ca_nothing error with .ok False. By default these notifications are suppressed so that only valid values will be passed to the callback routine.
connect_timeout – If a connection timeout is specified then the camonitor() will report a disconnection event after the specified interval if connection has not completed by this time. Note that this notification will be made even if notify_disconnect is False, and that if the PV subsequently connects it will update as normal.

cothread.catools.connect(pvs, cainfo=False, wait=True, timeout=5, throw=True)#

Establishes a connection to one or more PVs, optionally returning detailed information about the connection. A single PV or a list of PVs can be given. This does not normally need to be called, as the ca... routines will establish their own connections as required, but after a successful connection we can guarantee that caput(..., wait=False) will complete immediately without suspension and that caput(pvs, values) will execute in order if all PVs in pvs have been successfully connected.

It is possible to test whether a channel has successfully connected without provoking suspension by calling connect(pv, wait=False, cainfo=True) and testing the state attribute of the result.

The various arguments control the behaviour of connect() as follows:

Parameters:

wait – Normally the connect() routine will not return until the requested connection is established. If wait=False is set then a connection request will be queued and connect() will unconditionally succeed.
cainfo –
By default a simple ca_nothing value is returned, but if cainfo=True is set then a ca_info structure is returned.

class cothread.catools.ca_info#

The following dynamic attributes record information about the channel access connection:

.ok#

True iff the channel was successfully connected.

.name#

Name of PV.

.state#

State of channel as an integer. Look up .state_strings[.state] for textual description. A value of 2 indicates a currently connected PV.

.host#

Host name and port of server providing this PV.

.read#

True iff read access to this PV is allowed.

.write#

True iff write access to this PV is allowed.

.count#

Data count of this channel, length of the associated data array.

.datatype#

Underlying channel datatype as DBR_ value. Look up .datatype_strings[.datatype] for description.

The following static attributes are provided to help with interpretation of the dynamic attributes:

.state_strings#

Converts state into a printable description of the connection state.

.datatype_strings#

Textual descriptions of the possible channel data types, can be used to convert .datatype into a printable string.

The str representation of this structure can be printed to produce output similar to that produced by the cainfo command line tool.
timeout – Documented in Common Notes above. If a value cannot be retrieved and throw=False is set then for each failing PV an empty value with .ok==False is returned.
throw – Documented in Common Notes above. If a value cannot be retrieved and throw=False is set then for each failing PV an empty value with .ok==False is returned.

cothread.catools.cainfo(pvs, timeout=5, throw=True)#: This is an alias for connect() with cainfo and wait set to True. Returns a ca_info structure containing information about the connected PV or a list of structures, as appropriate.

Working with Values#

There are two types of values returned by cothread.catools functions: “augmented values” and “error codes”. The caput() function only returns an error code value (which may indicate success), while caget() and camonitor() will normally return (or deliver) augmented values, but will return (or deliver) an error code on failure.

The following fields are common to both types of value. This means that is is always safe to test value.ok for a value returned by caget() or caput() or delivered by camonitor().

.ok#: Set to True if the data is good, False if there was an error. For augmented values .ok is always set to True.

.name#: Name of the pv.

If .ok is True then two further attributes are set (see Augmented Values for further details):

.datatype#: Underlying EPICS data type.

.element_count#

Underlying EPICS length. This is typically determined by record support at database loading type, for instance for waveform records this is the value in the .NELM field.

Note that this determines the maximum length of the associated data array, but the returned data may be shorter, for instance the .NORD field of a waveform record can determine a shorter length.

Values and their Types#

The type of values returned by caget() or delivered by camonitor() callbacks is determined by the requested datatype in the original caget() or camonitor() call together with the underlying length of the requested EPICS field.

If the underlying length (.element_count) of the EPICS value is 1 then the value will be returned as a Python scalar, and will be one of the three basic scalar types (string, integer or floating point number), but wrapped as an augmented type.

If on the other hand .element_count is not 1 then the value is treated as an array and is always returned as a numpy array, again wrapped as an augmented type. Note that this means that even if caget(pv, count=1) is used to fetch a value with one element, if the underlying PV is an array then the result returned will be an array.

Note

This is an incompatible change in behaviour from previous versions of cothread. Previously whether to return a value as an array or a scalar was determined purely by the length of the retrieved data, now it is determined by the underlying length of the EPICS source, ie by its .element_count value.

The table below enumerates the possibilities:

Cothread type

Derived from

For these values

ca_str

str

String value

ca_int

int

Integral value

ca_float

float

Floating point value

ca_array

numpy.ndarray

Any array value

Cothread type	Derived from	For these values
`ca_str`	`str`	String value
`ca_int`	`int`	Integral value
`ca_float`	`float`	Floating point value
`ca_array`	`numpy.ndarray`	Any array value

class cothread.dbr.ca_str#: Scalar type derived from basic Python type.

class cothread.dbr.ca_int#: Scalar type derived from basic Python type.

class cothread.dbr.ca_float#: Scalar type derived from basic Python type.

class cothread.dbr.ca_array#: Array type derived from numpy.ndarray. The associated dtype will be as close a fit to the underlying data as possible.

Augmented Values#

Augmented values are normally Python or numpy values with extra fields: the .ok and .name fields are already mentioned above, and further extra fields will be present depending on format requested for the data. As pointed out above, .ok is always True for valid data.

Four different types of augmented value are returned: strings, integers, floating point numbers or arrays, depending on the length of the data requested – an array is only used when the data length is >1.

In almost all circumstances an augmented value will behave exactly like a normal value, but there are a few rare cases where differences in behaviour are observed (these are mostly bugs). If this occurs the augumentation can be stripped from an augmented value value by writing +value – this returns the underlying value.

The type of augmented values is determined both by parameters passed to caget() and camonitor() and by the underlying datatype. Both of these functions share parameters datatype, format and count which can be used to control the type of the data returned:

datatype

For caget() and camonitor() this controls the format of the data that will be requested, while for caput() the data will be coerced into the requested format. datatype can be any of the following:

None (the default). In this case the “native” datatype provided by the channel will be returned.
A DBR_ value, one of the following:

cothread.catools.DBR_STRING#

Strings are up to 39 characters long – this is a constraint set by EPICS. For longer strings see DBR_CHAR_STR.

cothread.catools.DBR_CHAR_STR#

Read an array and interpret it as a Python string.

cothread.catools.DBR_CHAR#

cothread.catools.DBR_SHORT#

cothread.catools.DBR_LONG#

These are all signed integer types, with 8, 16 and 32 bit values respectively.

cothread.catools.DBR_FLOAT#

cothread.catools.DBR_DOUBLE#

Floating point values with 32 and 64 bit values, respectively.

cothread.catools.DBR_ENUM#

A 16 bit unsigned integer value representing an index into an array of strings. The associated strings can be retrieved by using format=FORMAT_CTRL and inspecting the enums field.
A python type compatible with any of the above values, such as int, float or str. These correspond to DBR_LONG, DBR_DOUBLE and DBR_STRING respectively.
Any numpy.dtype compatible with any of the above values.
One of the special values DBR_CHAR_STR, or DBR_CHAR_BYTES. This is used to request a char array which is then converted to a Python str or bytes string on receipt. It is not sensible to specify count with this option. The option DBR_CHAR_BYTES is meaningless and not supported for caput().

Note that if the PV name ends in $ and datatype is not specified then DBR_CHAR_STR will be used.
The special value DBR_ENUM_STR, only for caget() and camonitor(). In this case the “native” channel datatype is used unless the channel is an enumeration, in which case the corresponding string is returned.
For caget() and camonitor() two further special values are supported. In both of these cases format is ignored:

cothread.catools.DBR_STSACK_STRING#

Returns the current value as a string together with extra fields status, severity, ackt, acks.

cothread.catools.DBR_CLASS_NAME#

Returns the name of the “enclosing interface”, typically the record type, and typically the same as the EPICS .RTYP field.

For caput() also two further values are supported:

cothread.catools.DBR_PUT_ACKT#

cothread.catools.DBR_PUT_ACKS#

These are used for global alarm acknowledgement, where _ACKT configures whether alarms need to be acknowleged and _ACKS acknowledges alarms of a particular severity.

format

This controls how much auxilliary information will be returned with the retrieved data, and can be one of the following:

cothread.catools.FORMAT_RAW#: The data is returned unaugmented except for the .name and .ok fields. This is the default value.

cothread.catools.FORMAT_TIME#: The data is augmented by timestamp fields timestamp and raw_stamp together with alarm status and severity fields. The value in timestamp is in time.time() format (seconds in Unix UTC epoch) rounded to the nearest microsecond.

cothread.catools.FORMAT_CTRL#

The data is augmented by channel access “control” fields. The set of fields returned depends on the underlying datatype as follows:

DBR_SHORT, DBR_CHAR, DBR_LONG: The alarm status and severity fields together with units and limit fields: upper_disp_limit, lower_disp_limit, upper_alarm_limit, lower_alarm_limit, upper_warning_limit, lower_warning_limit, upper_ctrl_limit, lower_ctrl_limit. The meaning of these fields is determined by EPICS channel access.
DBR_FLOAT, DBR_DOUBLE: As above together with a precision field.
DBR_ENUM: Alarm status and severity fields together with enums, a list of possible enumeration strings. The underlying value for an enumeration will be an index into enums.
DBR_STRING: _CTRL format is not supported for this field type, and FORMAT_TIME data is returned instead.

count

The precise behaviour of this parameter is EPICS server and client version specific, but for recent versions of EPICS there are three options:

0 (default): For recent versions of EPICS this is interpreted as a request for the true data dependent length of the data, for example, the number of points in a waveform record determined by the .NORD field). For older versions of EPICS the full waveform is returned.

Note

This feature means that a very visible change in behaviour is seen when upgrading from EPICS 3.14.11 to 3.14.12. Before this update requests from waveform records ignore .NORD, subsequently it is possible for truncated data to be returned in response to a default request.
-1 (or any negative value): This will always request the entire waveform, up to element_count values.
any other value: Returns the specified number of elements, up to element_count.

Fields in Augmented Values#

Summary of all available fields in augmented values.

The following fields are present in all augmented values.

.name: Name of record, always present.

.ok: Set to True, always present.

The following fields are present if .ok is True:

.datatype

This is the underlying EPICS data type of the value, and is one of the following values:

DBR_STRING	0	String (up to 40 characters)
DBR_SHORT	1	16-bit signed integer
DBR_FLOAT	2	32-bit floating point number
DBR_ENUM	3	Enumeration, should be value between 0 and 15, but the underlying data is a 16-bit integer
DBR_CHAR	4	8-bit signed integer
DBR_LONG	5	32-bit signed integer
DBR_DOUBLE	6	64-bit floating point number

.element_count: Number of elements in the underlying EPICS value. If this is not 1 then the value is treated as an array, otherwise up to this many elements may be present in the value.

The following fields are present in all values if FORMAT_TIME is specified.

.raw_stamp#: Record timestamp in raw format as provided by EPICS (but in the local Unix epoch, not the EPICS epoch). Is a tuple of the form (secs, nsec) with integer seconds and nanosecond values, provided in case full ns timestamp precision is required.

.timestamp#: Timestamp in seconds in format compatible with time.time() rounded to the nearest microsecond: for nanosecond precision use raw_stamp instead.

.datetime#

This is a dynamic property which returns timestamp as a datetime.datetime value by computing

datetime.datetime.fromtimestamp(value.timestamp)

from the timestamp attribute. This calculation takes local time into account.

Note

This is an incompatible change from cothread version 2.3 and earlier. In earlier versions this field did not exist but could be assigned to, in this release datetime is a read-only property which cannot be assigned to.

The following fields are present in all values if FORMAT_TIME or FORMAT_CTRL is specified.

.severity#

EPICS alarm severity, normally one of the values listed below.

0	No alarm
1	Alarm condition, minor severity
2	Alarm condition, major severity.
3	Invalid value.

.status#: Reason code associated with alarm severity, always present with severity code.

The following fields are returned if DBR_STSACK_STRING is specified:

.ackt#: Whether it is necessary to acknowledge transient alarms

.acks#: The highest severity unacknowledged alarm

The following fields are present in numeric values if FORMAT_CTRL is specified. Values of type DBR_ENUM or DBR_STRING are not numeric.

.units#: Units for display.

.upper_disp_limit#
.lower_disp_limit#: Suggested display limits for numerical values.

.upper_alarm_limit#
.lower_alarm_limit#
.upper_warning_limit#
.lower_warning_limit#
.upper_ctrl_limit#
.lower_ctrl_limit#: Various EPICS numeric limits.

.precision#: For floating point values only, the specified display precision (or 0 if not specified). Present if value is a floating point type.

The following field is only present in DBR_ENUM values.

.enums#: For enumeration values only, an array of enumeration strings indexable by enumeration value.

Error Code Values#

Error code values are used to indicate a success return from caput() (in which case .ok is True), to indicated disconnection using camonitor(), and to indicate any other failure, either as a return value or raised as an exception.

class cothread.catools.ca_nothing#

All error code values have type ca_nothing and provide the following fields:

.ok#

Set to True if the data is good, False if there was an error. Testing an error code value for boolean will return the value of .ok, so for example it is possible to write:

if not caput(pv, value, throw=False):
    process caput error

.name#: Name of the PV which generated this error..

.errorcode#

Channel access error code. The following values are worth noting:

ECA_SUCCESS#: Success error code. In this case .ok is True. Returned by successful caput() and connect() calls.

ECA_DISCONN#: Channel disconnected. This is used by camonitor() to report channel disconnect events.

ECA_TIMEOUT#: Channel timed out. Reported if user specified timeout ocurred before completion and if throw=False specified.

PV and PV_array Classes#

Two classes are provided for wrapping camonitor(). The PV class wraps access to a single PV and always contains the latest value. On the other hand, PV_array gathers a uniform array of PVs into a single array. These two classes can be imported from cothread.pv.

Note that both classes will automatically unsubscribe from their PVs when deleted.

class cothread.pv.PV(pv, on_update=None, initial_value=None, caput_wait=False, [initial_timeout, ]**kargs)#

Creates a wrapper to monitor pv. If an on_update function is passed it will be called with the class instance as argument after each update to the instance. The kargs are passed through to the called camonitor(). The flag caput_wait can be set to change the default behaviour of caput().

The behaviour of the first call to get() is affected by two arguments, initial_value and initial_timeout, at most one of which can be specified. If initial_timeout is specified then the first call to get() will block until this timeout expires or a valid PV value is available. Otherwise initial_value can be set to specify a value to return until the PV has updated.

Note

This is an incompatible change from cothread versions 2.11 and 2.12. In these versions the initial_timeout argument is named timeout, defaults to 5, and cannot be unset.

Note that blocking on a PV object for the initial update cannot be safely done from within a camonitor callback, as in this case the blocking operation is waiting for a camonitor callback to occur, and only one camonitor callback is processed at a time.

close()#: Closes the associated camonitor(). No further updates will occur. Note that it is sufficient to drop all references to the class, it will then automatically call close().

sync([timeout])#: This call will block until the PV object has seen at least one update. If initial_timeout was specified in the constructor then its associated deadline can be used as a default timeout, otherwise a timeout must be specified.

get()#

Returns the current value associated with the PV. This will be the most recently delivered PV value as notified through a camonitor() callback.

On the first call to get() if no value has yet been delivered (no callback has yet occurred) this call will block until the timeout passed to the constructor has expired or a value has arrived, and if the timeout expires then an exception is raised.

get_next(timeout=None, reset=False)#: Returns a fresh value associated with the PV, blocks and waits if necessary. Values are consumed by calling this method or reset(), values are generated by camonitor() callbacks, so to ensure the value is fresher than the point of call reset can be set to discard any pending value. A timeout can be specified to limit how long to wait for a new value, and a timeout exception may be raised.

reset()#: Discards any pending value for get_next(), ensures get_next() will block until a fresh value arrives.

caget(**kargs)#: Directly calls caget() on the underlying PV with the given arguments.

caput(value, **kargs)#: Directly calls caput() on the underlying PV with the given arguments. If caput_wait was set in the original PV constructor then by default caput() is called with wait=True, otherwise caput() is non blocking.

name#: This is the PV name, and should be the same as .value.name.

value#: This attribute is a property wrapping get() and caput(), so given pv = PV(pvname) then pv.value returns the most recent value for pv and pv.value = new_value will call caput(pvname, new_value).

class cothread.pv.PV_array(pvs, dtype=float, count=1, on_update=None, caput_wait=False, **kargs)#

Uses pvs to create an aggregate array containing the value of all specified PVs aggregated into a single numpy array. The type of all the elements is specified by dtype and the number of points contributed by each PV is given by count. If count is 1 the generated array is one dimensional of shape (len(pvs),), otherwise the shape is (len(pvs),count). The flag caput_wait can be set to change the default behaviour of caput().

At the same time arrays of length len(pvs) are created for the connection status, timestamp and severity of each PV.

If specified the on_update method will be called for each update to each field of the managed array. The arguments passed are the updated PV_array instance and the index of the update.

close()#: Closes all monitors. Note that this is called automatically when the last reference to the created PV_array instance is dropped.

get()#: Returns copy of current value. This will be a numpy array with shape and dtype determined by the arguments to the constructor. This is the same as the value returned by the value attribute.

caget(**kargs)#: Directly calls caget() on the list of PVs and returns an array of results; this should be the same shape and parameters as returned by get().

caput(value, **args)#: Directly calls caput() on the stored list of PVs. If caput_wait was set in the original PV constructor then by default caput() is called with wait=True, otherwise caput() is non blocking.

sync(timeout=5, throw=False)#: This method attempts to ensure that all of the PVs associated with this array have received at least one update by blocking.

value#: Returns copy of current value, same as get() when read, calls caput() when written to.

names#: Stores the names of the monitored PVs.

timestamp#: Timestamp of the most recent update for each monitored PV in standard time.time() format.

severity#: Array of EPICS severity codes for the most recent update for each PV.

status#: Array of EPICS status codes for the most recent update for each PV.

ok#: Connection status for each monitored PV. If any element of .ok is False then the PV is disconnected and the corresponding .value, .timestamp, .severity and .status elements contain old and stale values.

all_ok#: Returns aggregate status of .ok, True iff all PVs currently connected.

Note that the attributes value, ok, timestamp, severity, and status all return fresh copies of the underlying data. This means that the values returned are not affected by subsequent updates to the PV_array object.