Keyword

class Cauldron.base.client.Keyword

Bases: Cauldron.base.core._BaseKeyword

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

callback(function[, remove, preferred])	Request that a callback function be invoked whenever a KTL broadcast is received for this keyword.
cast(value)	Cast to a native python datatype.
clone()	Clone this keyword.
isAlive()	Check that the heartbeats associated with this keyword are themselves alive; if they are, return True, otherwise return False.
monitor([start, prime, wait])	Subscribe to broadcasts for this KTL keyword.
poll([period, start])	Poll a keyword for updates.
propagate()	Invoke any/all callbacks registered via callback().
read([binary, both, wait, timeout])	Perform a ktl_read() operation for this keyword.
subscribe([start, prime, wait])	Subscribe to broadcasts for this KTL 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.
waitfor(expression[, timeout, case])	Wait for a particular expression to be true.
write(value[, wait, binary, timeout])	Perform a KTL write for this keyword.

Methods Documentation

callback(function, remove=False, preferred=False)

Request that a callback function be invoked whenever a KTL broadcast is received for this keyword.

The callback function should accept as its sole argument a Keyword instance. If remove is set to False, the designated function will be removed from the set of active callbacks. If preferred is set to True, this callback will be remembered as a preferred callback, which gets invoked before all other non-preferred callbacks.

callback() is typically used in conjunction with monitor(), or poll() if the specific KTL keyword does not support broadcasts.

cast(value)

Cast to a native python datatype.

When the “binary” value of a keyword is requested, cast() is used to convert to the native python type.

This method can be overridden to provide specific behavior in user subclasses.

clone()

Clone this keyword.

isAlive()

Check that the heartbeats associated with this keyword are themselves alive; if they are, return True, otherwise return False. If no heartbeats are associated with this Keyword instance, a NoHeartbeatsError exception will be raised.

Warning

isAlive is not implemented in the Cauldron version of the KTL API.

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

poll(period=1, start=True)

Poll a keyword for updates.

In circumstances when a KTL keyword cannot (or will not) reliably broadcast updates, polling can be established. If start is True, a non-blocking call to Keyword.read() will be invoked every period. seconds; if start is False, polling for this keyword will be discontinued.

Warning

Polling keywords is inefficient, as it requires a discrete ktl_read() operation for each polling event for each keyword polled. Using monitor() is a far better choice if supported by the service’s KTL client library.

Warning

poll is not implemented in the Cauldron version of the KTL API.

propagate()

Invoke any/all callbacks registered via callback().

This is an internal function, invoked after a Keyword instance successfully completes a read() call, or a KTL broadcast event occurs.

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

subscribe(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.

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

waitfor(expression, timeout=None, case=False)

Wait for a particular expression to be true.

Warning

waitfor is not implemented in the Cauldron version of the KTL API.

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