A minimal example of how Orca might interact with the CouchDB database

orca_db_example.py

'''A minimal example of how Orca might interact with the CouchDB database
to load settings from the DB at startup and write settings to the DB only
when they change.

Because Orca is the only *producer* of the database data, it can keep track
internally of whether the detector configuration has changed.

  NO: Checking in-memory settings against values in the DB

      for fec in fecs:
          db_fec = load_from_db(fec.id)
          if fec != db_fec:
              write_to_db(fec)

  YES: Keeping track of 'dirty' state internally

      for fec in fecs:
          if fec.changed:
              write_to_db(fec)

'''

import json

# This dictionary represents the CouchDB detector database, indexed by
# board ID
orcadb = {
    # This is a FEC document
    'f123': {
        'type': 'fec',
        'vthr': [1, 2, 3, 4]
    }
}


class Detector:
    '''The master detector object, which contains the hardware.

    In this example, the hardware is a collection of FECs.

    This object initializes itself by loading from the database. It could
    alternatively load from a file, with minimal changes.
    '''
    def __init__(self):
        self.fecs = {}
        for fec_id, fec_doc in orcadb.items():
            self.fecs[fec_id] = FEC(fec_id, fec_doc)
            print 'Loaded FEC', fec_id, 'settings from DB'

    def start_run(self, run_id):
        print 'Starting run', run_id

        # Write the settings to the DB, only for boards that have changed
        for board_id, fec in self.fecs.items():
            if fec.changed:
                print 'FEC', board_id, 'changed!'
                print ' Write to DB:', str(fec)
                fec.changed = False

        # Start the run
        # ...


class FEC:
    '''Represents the (in-memory) hardware settings for a Front-End Card.

    We always use getters and setters as an interface, which allows us to
    track changes.

    :param board_id: Hexadecimal board identifier
    :param settings: A dictionary of settings (a FEC document)
    '''
    def __init__(self, board_id, settings):
        self.board_id = board_id

        # Initialize object from DB values
        self.vthr = settings['vthr']

        # Flag to track changes
        self.changed = False

    def __str__(self):
        '''Return a JSON representation of the object.'''
        o = {
            'board_id': self.board_id,
            'vthr': self.vthr
        }
        return json.dumps(o)

    def set_vthr(self, vthr):
        '''Set the vthrs and note that they've changed.

        :param vthrs: The new vthr array
        '''
        self.vthr = vthr
        self.changed = True

    def get_vthr(self):
        '''Retrieve the vthr array.'''
        return self.vthr


if __name__ == '__main__':
    detector = Detector()

    # Start some runs
    detector.start_run(100)
    detector.start_run(101)

    # Change a setting
    detector.fecs['f123'].set_vthr([5, 6, 7, 8])

    # Start some runs
    detector.start_run(102)
    detector.start_run(103)