Task scheduling for clocks

Module: dvbcss.task

Introduction

The dvbcss.task module provides sleep and scheduling functions for use with the dvbcss.clock module. These functions track adjustments to clocks (such as changes in the tick rate or tick value/offset) to ensure that the sleep or scheduled event happen when the clock actually reaches the target tick count value.

To use this module, just import it and directly call the functions sleepFor(), sleepUntil(), scheduleEvent() or runAt().

Note

Scheduling happens on a single thread, so if you use the runAt() function, try to keep the callback code as fast and simple as possible, so that it returns control as quickly as possible.

See How the dvbcss.task module works internally for information on how the internals of the Task module work.

Example

A simple example:

from dvbcss.clock import SysClock
from dvbcss.clock import CorrelatedClock
from dvbcss.task import sleepFor, runAt

s = SysClock()
c = CorrelatedClock(parentClock=s, tickRate=1000)

# wait 1 second
sleepFor(c, numTicks=1000)

# schedule callback in 5 seconds
def foo(message):
    print "Callback!", message

runAt(clock=c, whenTicks=c.ticks+5000, foo, "Tick count progressed by 5 seconds")

# ... but change the correlation to make the clock jump 1 second forward
#     causing the callback to happen one second earlier
c.correlation = (c.correlation[0], c.correlation[1] + 1000)

# ... the callback will now happen in 4 seconds time instead

Functions

dvbcss.task.sleepUntil(clock, whenTicks)

Sleep until the specified clock reaches the specified tick value.

Parameters:

• clock – (dvbcss.clock.ClockBase) Clock to sleep against the ticks of.
• whenTicks – (int) The tick value of the clock at which this function returns.

Returns after the specified tick value is reached.

dvbcss.task.sleepFor(clock, numTicks)

Sleep for the number of ticks of the specified clock.

Parameters:

• clock – (dvbcss.clock.ClockBase) Clock to sleep against the ticks of.
• numTicks – (int) The number of ticks to sleep for.

Returns after the elapsed number of ticks of the specified clock have passed.

dvbcss.task.scheduleEvent(clock, whenTicks, event)

Schedule the threading.Event to be called when the specified clock reaches (or passes) the specified tick value.

Parameters:

• clock – (dvbcss.clock.ClockBase) Clock to schedule the event against
• whenTicks – (int) The tick value of the clock at which the event is to be triggered.
• event – (threading.Event) python Event object that the :method:threading.Event.set method will be called on at the scheduled time

dvbcss.task.runAt(clock, whenTicks, callBack, args=None, kwargs=None)

Call the specified callback function when the specified clock reaches (or passes) the specified tick value.

The callback happens on the single thread used within the clock scheduling system. You should avoid writing code that hogs this thread to do substantial processing.

Parameters:

• clock – (dvbcss.clock.ClockBase) Clock to schedule the callback against
• whenTicks – (int) The tick value of the clock at which the callback is to be called.
• callback – (callable) Function to be called
• args – A list of positional arguments to be passed to the callback function when it is called.
• kwargs – A dict of keyword arguments to be pased to the callback function when it is called.