Caution

This page documents the latest, unreleased version of Buildbot. For documentation for released versions, see https://docs.buildbot.net/current/.

3.8.12. State connector

class buildbot.db.state.StateConnectorComponent

This class handles maintaining arbitrary key-value state for Buildbot objects. Each object can store arbitrary key-value pairs, where the values are any JSON-encodable value. Each pair can be set and retrieved atomically.

Objects are identified by their (user-visible) name and their class. This allows, for example, a nightly_smoketest object of class NightlyScheduler to maintain its state even if it moves between masters, but avoids cross-contaminating state between different classes of objects with the same name.

Note that “class” is not interpreted literally, and can be any string that will uniquely identify the class for the object; if classes are renamed, they can continue to use the old names.

An instance of this class is available at master.db.state.

Objects are identified by objectid.

getObjectId(name, class_name)
Parameters:

  • name – name of the object

  • class_name – object class name

Returns:

the objectid, via a Deferred.

Get the object ID for this combination of name and class. This will add a row to the ‘objects’ table if none exists already.

getState(objectid, name[, default])
Parameters:

  • objectid – objectid on which the state should be checked

  • name – name of the value to retrieve

  • default – (optional) value to return if name is not present

Returns:

state value via a Deferred

Raises:

KeyError – if name is not present and no default is given

Raises:

TypeError if JSON parsing fails

Get the state value for key name for the object with id objectid.

setState(objectid, name, value)
Parameters:

  • objectid – the objectid for which the state should be changed

  • name – the name of the value to change

  • value (JSON-able value) – the value to set

  • returns – value actually written via Deferred

Raises:

TypeError if JSONification fails

Set the state value for name for the object with id objectid, overwriting any existing value. In case of two racing writes, the first (as per db rule) one wins, the seconds returns the value from the first.

atomicCreateState(objectid, name, thd_create_callback)
Parameters:

  • objectid – the objectid for which the state should be created

  • name – the name of the value to create

  • thd_create_callback – the function to call from thread to create the value if non-existent. (returns JSON-able value)

  • returns – Deferred

Raises:

TypeError if JSONification fails

Atomically creates the state value for name for the object with id objectid. If there is an existing value, returns that instead. This implementation ensures the state is created only once for the whole cluster.

Those 3 methods have their threaded equivalent, thdGetObjectId, thdGetState, thdSetState that is intended to run in synchronous code, (e.g master.cfg environment).