Keyword¶
-
class
Cauldron.zmq.client.
Keyword
[source] [edit on github]¶ Bases:
Cauldron.base.client.Keyword
A client-side KTL keyword object.
Parameters: service :
Service
The parent KTL service.
name : str
The name of this keyword.
Notes
Each KTL keyword belongs to a specific service. The service is retained by weak reference by the keyword, to prevent reference cycles. Keyword objects only read from the keyword store when explicitly told to do so.
Along with the methods of this class, the Keyword interface specifies a dictionary-like interface for accessing features of keywords. The dictionary interface implements the following keys:
ascii
: Return the keyword value in theascii
encoding.binary
: Return a binary representation of the keyword value.broadcasts
: Whether this keyword broadcasts changes.name
: The name of this keyword, uppercased.monitored
: Whether this keyword is monitored for changes.monitor
: Same asmonitored
.populated
: Whether this keyword has been populated (read at least once).reads
: Whether this keyword can be read.writes
: Whether this keyword can be written.timestamp
: The last modified time of this keyword, usually just the time of last read.units
: The units of this keyword.
Only one method is not supported by the original KTL library,
stop()
, which could easily be subsumed intosubscribe()
with the keyword argumentstart=False
.Methods Summary
monitor
([start, prime, wait])Subscribe to broadcasts for this KTL keyword. read
([binary, both, wait, timeout])Perform a ktl_read() operation for this keyword. wait
([timeout, operator, value, sequence, ...])Wait for the Keyword to receive a new value, or if sequence is set, wait for the designated write operation to complete. write
(value[, wait, binary, timeout])Perform a KTL write for this keyword. Methods Documentation
-
monitor
(start=True, prime=True, wait=True)[source] [edit on github]¶ Subscribe to broadcasts for this KTL keyword.
If
start
is set to False, the subscription will be shut down. Ifprime
is set to False, there will be no priming read of the keyword value; the default behavior is to perform a priming read. Ifwait
is set to False, the priming read (if requested) will not block while waiting for the priming read to complete.This is an abstract method. Backends must implement this method
-
read
(binary=False, both=False, wait=True, timeout=None)[source] [edit on github]¶ Perform a ktl_read() operation for this keyword.
The default behavior is to do a blocking read and return the ascii representation of the keyword value. If
binary
is set to True, only the binary representation will be returned; Ifboth
is set to True, both representations will be returned in a (binary, ascii) tuple. Ifwait
is set to False, the KTL read operation will be performed in a background thread, and any resulting updates would trigger any callbacks registered viacallback()
. If atimeout
is specified (in seconds), and wait is set to True,read()
will raise a TimeoutException if the timeout expires before a response is received.This is an abstract method. Backends must implement this method
-
wait
(timeout=None, operator=None, value=None, sequence=None, reset=False, case=False)[source] [edit on github]¶ Wait for the Keyword to receive a new value, or if sequence is set, wait for the designated write operation to complete.
If
value
is set, with or without operator being set,wait()
effectively acts as a wrapper towaitFor()
. Ifreset
is set to True, the notification flag will be cleared before waiting against it- this is dangerous, as this introduces a race condition between the arrival of the event itself, and the invocation ofwait()
. If the event occurs first, the caller may wind up waiting indefinitely. Iftimeout
(in whole or partial seconds) is set,wait()
will return False if no update occurs before the timeout expires. Otherwise,wait()
returns True to indicate that the wait completed successfully.This is an abstract method. Backends must implement this method
-
write
(value, wait=True, binary=False, timeout=None)[source] [edit on github]¶ Perform a KTL write for this keyword.
value
is the new value to write to the keyword. Ifbinary
is set to True, value will be interpreted as a binary representation; the default behavior is to interpret value as an ascii representation. The behavior of timeout is the same as forread()
.This is an abstract method. Backends must implement this method