Keyword

class Cauldron.zmq.client.Keyword

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 the ascii 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 as monitored.
• 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 into subscribe() with the keyword argument start=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)

Subscribe to broadcasts for this KTL keyword.

If start is set to False, the subscription will be shut down. If prime is set to False, there will be no priming read of the keyword value; the default behavior is to perform a priming read. If wait 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)

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; If both is set to True, both representations will be returned in a (binary, ascii) tuple. If wait is set to False, the KTL read operation will be performed in a background thread, and any resulting updates would trigger any callbacks registered via callback(). If a timeout 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)

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 to waitFor(). If reset 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 of wait(). If the event occurs first, the caller may wind up waiting indefinitely. If timeout (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)

Perform a KTL write for this keyword.

value is the new value to write to the keyword. If binary 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 for read().

This is an abstract method. Backends must implement this method