# poll mechanics

    def poll(self, condition_func, poll_func, timeout_secs):
        now = datetime.datetime.now()
        timeout = now + datetime.timedelta(seconds=timeout_secs)
        # define generator closure
        def _poll():
            now = datetime.datetime.now()
            if now > timeout:
                raise RuntimeError('%s: poll timeout' % self)
            d = deferLater(reactor, 2, poll_func)
            # condition_func must raise StopIteration when done
            d.addCallback(condition_func)
            def _handle_exc(failure):
                if failure.type == StopIteration:
                    failure.raiseException()
                else:
                    return failure
            d.addErrback(_handle_exc)
            yield d
        # create a polling task
        task = cooperate(_poll())
        d = task.whenDone()
        d.addCallback(lambda _: self)
        return d

    # set up polling task

    def _pollState(self, ignore, context):
        poll_func = functools.partial(self.refresh, None, context)
        def condition_func(result):
            state = result['state']
            log.debug('%s: state (%s)' % (self, state))
            if state == 'running':
                raise StopIteration
            return state
        d = self.poll(condition_func, poll_func, 30)
        return d