docs: def unique_service(self, role, candidate=None):
          '''
          Retrieve a unique service, possibly setting or heartbeating it first.
  
          A "unique service" is a service with only one instance for a given
          role. Uniqueness is enforced by using the role name as the primary key
          `{'id':role, ...}`.
  
          Args:
              role (str): role name
              candidate (dict): if supplied, candidate info for the unique
                  service, explained below
  
          `candidate` normally represents "myself, this instance of the service".
          When a service supplies `candidate`, it is nominating itself for
          selection as the unique service, or retaining its claim to the role
          (heartbeating).
  
          If `candidate` is supplied:
  
              First, atomically in a single rethinkdb query, checks if there is
              already a unique healthy instance of this service in rethinkdb, and
              if not, sets `candidate` as the unique service.
  
              Looks at the result of that query to determine if `candidate` is
              the unique service or not. If it is, updates 'last_heartbeat' in
              rethinkdb.
  
              To determine whether `candidate` is the unique service, checks that
              all the fields other than 'first_heartbeat' and 'last_heartbeat'
              have the same value in `candidate` as in the value returned from
              rethinkdb.
  
              ***Important***: this means that the caller must ensure that none
              of the fields of the unique service ever change. Don't store things
              like 'load' or any other volatile value in there. If you try to do
              that, heartbeats will end up not being sent, and the unique service
              will flap among the candidates.
  
          Finally, retrieves the service from rethinkdb and returns it, if it is
          healthy.
  
          Returns:
              the unique service, if there is one and it is healthy, otherwise
              None
          '''
          # use the same concept of 'now' for all queries
          now = doublethink.utcnow()
          if candidate is not None:
              candidate['id'] = role
  
              if not 'ttl' in candidate:
                  raise Exception("candidate is missing required field 'ttl'")
              val = candidate['ttl']
              if not (isinstance(val, float) or isinstance(val, int)) or val <= 0:
                  raise Exception("'ttl' must be a number > 0")
  
              candidate['first_heartbeat'] = now
              candidate['last_heartbeat'] = now
              if not 'host' in candidate:
                  candidate['host'] = socket.gethostname()
              if not 'pid' in candidate:
                  candidate['pid'] = os.getpid()
  
              result = self.rr.table(
                      self.table, read_mode='majority').get(role).replace(
                              lambda row: r.branch(
                                  r.branch(
                                      row,
                                      row['last_heartbeat'] > now - row['ttl'],
                                      False),
                                  row, candidate),
                              return_changes='always').run()
              new_val = result['changes'][0]['new_val']
              if all([new_val.get(k) == candidate[k] for k in candidate
                      if k not in ('first_heartbeat', 'last_heartbeat')]):
                  # candidate is the unique_service, send a heartbeat
                  del candidate['first_heartbeat'] # don't touch first_heartbeat
                  self.rr.table(self.table).get(role).update(candidate).run()
  
          results = list(self.rr.table(
              self.table, read_mode='majority').get_all(role).filter(
                  lambda row: row['last_heartbeat'] > now - row['ttl']).run())
          if results:
              return results[0]
          else:
              return None