cache Package

cache Package

client Module

NICOS cache clients.

class nicos.cache.client.BaseCacheClient(name, **config)

Bases: nicos.core.device.Device

Bases: Device

An extensible read/write client for the NICOS cache.

Parameters

prefix (str, mandatory in setup)

Cache key prefix.

server (str, mandatory in setup)

“host:port” of the cache instance to connect to.

Parameters inherited from the base classes: description, loglevel, lowlevel

class nicos.cache.client.CacheClient(name, **config)

Bases: nicos.cache.client.BaseCacheClient

Bases: BaseCacheClient

Parameters inherited from the base classes: description, loglevel, lowlevel, prefix, server

class nicos.cache.client.DaemonCacheClient(name, **config)

Bases: nicos.cache.client.CacheClient

Bases: CacheClient

Parameters inherited from the base classes: description, loglevel, lowlevel, prefix, server

server Module

NICOS cache server.

Cache protocol documentation

• The Cache server listens by default on TCP and UDP port 14869 (it will also receive UDP broadcasts).

• The protocol is line-based. The basic syntax for a line (requests and responses) is

  [time1] [+|-] [time2] [@] key op [value] crlf

  The op is one character and decides the basic meaning of the request or response.

• Keys are hierarchic, with levels separated by an arbitrary number of slashes.

• All values are strings. The cache server does not interpret them in any way, but the NICOS clients do.

Setting a key (op ‘=’)

• time1 is the UNIX timestamp of the value.
• time2 is the TTL (time to live) in seconds, after which the key expires.
• Both are optional: time1 defaults to current time, ttl to no expiration.
• Instead of time+ttl@, time-expirationtime@ is also supported. TTL is then expirationtime - time.
• Without any value, the key is deleted.

Examples:

1327504784.71+5@nicos/temp/value=5.003     # explicit time and ttl given
nicos/temp/setpoint=5                      # no time and ttl given
+5@nicos/temp/value=1.102                  # only ttl given
nicos/temp/value=                          # key deletion

Response: none.

Querying a single key (op ‘?’)

• When an @ is present, the timestamp is returned with the reply.
• With time1-time2@ or time1+timeinterval@, a history query is made and several values can be returned.
• The value, if present, is ignored.

Examples:

nicos/temp/value?                         # request only the value
@nicos/temp/value?                        # request value with timestamp
1327504780-1327504790@nicos/temp/value?   # request all values in time range

Response: except for history queries, a single line in the form key=value or time@key=value, see below. If the key is nonexistent or expired, the form is [time@]key! or [time@]key!value. For history queries, a number of lines of the same form.

Querying with wildcard (op ‘*’)

• Matching is done by a simple substring search: all keys for which the requested key is a substring are returned.
• History queries are not allowed.
• Like for op ‘?’, timestamps are returned if @ is present.
• The value, if present, is ignored.

Examples:

nicos/temp/*                              # request only values
@nicos/temp/*                             # request values with timestamps

Response: each value whose key contains the key given is returned as a single line as for single query.

Subscribing to updates (op ‘:’)

• Matching is done by a simple substring search: the subscription is for all keys for which the requested key is a substring.
• When a @ is present, the updates contain the timestamp.

Response: none immediately, but every update matching the given key is sent to the client, either as [time@]key=value or [time@]key!value (if the key has expired).

Locking (op ‘$’)

The lock mechanism allows only one client at the same time to obtain a lock on a given identifier. This can be used to synchronize access of multiple NICOS clients to a shared resource (but is slow!).

• time1 is the time when the lock is requested (default current time).
• time2 is the ttl for the lock. It defaults to 1800 seconds.
• key is the identifier for the lock.
• value must be either +clientid (lock) or -clientid (unlock); clientid is a string uniquely identifying the client.

Response:

• on lock: one of

  key$otherclientid      # already locked by other client, request denied
  key$                   # locked successfully

• on unlock: one of

  key$otherclientid      # not locked by this client, request denied
  key$                   # unlocked successfully

class nicos.cache.server.CacheDatabase(name, **config)

Bases: nicos.core.device.Device

Bases: Device

Parameters inherited from the base classes: description, loglevel, lowlevel

class nicos.cache.server.CacheServer(name, **config)

Bases: nicos.core.device.Device

Bases: Device

The server class.

Attached devices

db

The cache database instance. Type: CacheDatabase.

Parameters

server (str, mandatory in setup)

Address to bind to (host or host:port).

Parameters inherited from the base classes: description, loglevel, lowlevel

class nicos.cache.server.CacheUDPConnection(udpsocket, remoteaddr, log, maxsize=1496)

Bases: object

An UDP connection to use instead of a TCP connection in the CacheWorker.

close()

fileno()

recv(maxbytes)

sendall(data)

settimeout(timeout)

shutdown(how)

class nicos.cache.server.CacheUDPQueue(conn)

Bases: object

Pseudo-queue for synchronous writes to UDP connections.

get()

put(msg)

class nicos.cache.server.CacheUDPWorker(db, connection, name='', initstring='', initdata='', loglevel=None)

Bases: nicos.cache.server.CacheWorker

Bases: CacheWorker

join()

start_sender(name)

class nicos.cache.server.CacheWorker(db, connection, name='', initstring='', initdata='', loglevel=None)

Bases: object

Worker thread class for the cache server.

closedown()

is_active()

join()

start_sender(name)

update(key, op, value, time, ttl)

Check if we need to send the update given.

writeto(data)

class nicos.cache.server.FlatfileCacheDatabase(name, **config)

Bases: nicos.cache.server.CacheDatabase

Bases: CacheDatabase

Cache database which writes historical values to disk in a flatfile (ASCII) format.

The store format is the following:

• Each cache key is separated at the last slash. The part before the slash is called “category” (usually prefix + a device name).
• For each category, there is a subdirectory (with slashes in the category name replaced by dashes) in the store path. This contains subdirectories for every year, and these subdirectories contain one file per day, in the format “MM-DD”.
• These files are also hardlinked at another hierarchy, starting with year and day subdirectories, where the files are named by category.

For example, the cache entries for category “nicos/slit” at 2012-01-05 are available in the files nicos-slit/2012/01-05 and 2012/01-05/nicos-slit.

The format of these files is a simple three-column tab-separated ascii format: the first column is the last part of the cache key (which combined with the category gives the full key); the second column is the Unix timestamp of the change, and the third column is the actual value.

All values should be valid Python literals, but this is not enforced by the cache server, rather by the NICOS clients. The value can also a single dash, this indicates that at the given timestamp the latest value for this key expired.

Parameters

storepath (str, mandatory in setup)

Directory where history stores should be saved.

Parameters inherited from the base classes: description, loglevel, lowlevel

class nicos.cache.server.MemoryCacheDatabase(name, **config)

Bases: nicos.cache.server.CacheDatabase

Bases: CacheDatabase

Central database of cache values, keeps everything in memory.

Parameters inherited from the base classes: description, loglevel, lowlevel

utils Module

NICOS cache utils.

class nicos.cache.utils.Entry(time, ttl, value)

Bases: object

expired

time

ttl

value

nicos.cache.utils.all_days(fromtime, totime)

nicos.cache.utils.cache_dump(obj)

nicos.cache.utils.cache_load(entry)