Caution
Buildbot no longer supports Python 2.7 on the Buildbot master.
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 classNightlyScheduler
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 idobjectid
.
- 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 idobjectid
, 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 idobjectid
. 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).