# 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).