How the dvbcss.task module works internally

Introduction

The dvbcss.task module internally implements a task scheduler based around a single daemon thread with an internal priority queue.

Sleep and callback methods cause a task objet to be queued. The scheduler picks up the queued task and adds it to the priority queue and binds to the Clock so that it is notified of adjustments to the clock. When a task is added to the queue, the clock is queried to calculate the true time at which the tick count is expected to be reached by calling dvbcss.clock.ClockBase.calcWhen()

If a clock is adjusted the affected tasks are marked as deprecated (but remain in the priority queue) and new tasks are rescheduled with a recalculated time.

When one of the clocks involved has speed 0, then it may not be possible to calculate the time at which the task is to be scheduled. This happens when dvbcss.clock.ClockBase.calcWhen() returns Not a number (nan). The task will not be immediately added to the priority queue, however it will be added later once the clock speed returns to a non-zero value. This happens automatically as part of the rescheduling process when a clock is adjusted.

Objects

dvbcss.task.scheduler = <dvbcss.task._Scheduler object>

Task scheduler. Starts an internal threading.Thread with theading.Thread.daemon set to True.

This is an internal of the Task module. For normal use you should not need to access it.

Variables:

• taskheap – the priority queue of tasks
• addQueue – threadsafe queue of tasks to be added to the priority queue
• rescheduleQueue – thereadsafe queue of clocks that have been adjusted and therefore which need to trigger rescheduling of tasks
• updateEvent – theading.Event used to wake the scheduler thread whenever there is work pending (items added to addQueue or rescheduleQueue)
• clock_Tasks – mapping of clocks to takss that depend on them

Running instance of the dvbcss.task._Scheduler

Classes

class dvbcss.task._Scheduler(*args, **kwargs)

Task scheduler. Starts an internal threading.Thread with theading.Thread.daemon set to True.

This is an internal of the Task module. For normal use you should not need to access it.

Variables:

• taskheap – the priority queue of tasks
• addQueue – threadsafe queue of tasks to be added to the priority queue
• rescheduleQueue – thereadsafe queue of clocks that have been adjusted and therefore which need to trigger rescheduling of tasks
• updateEvent – theading.Event used to wake the scheduler thread whenever there is work pending (items added to addQueue or rescheduleQueue)
• clock_Tasks – mapping of clocks to takss that depend on them

Starts the scheduler thread at initialisation.

notify(causeClock)

Callback entry point for when a clock is adjusted

Parameters:causeClock – (dvbcss.clock.ClockBase) The clock that was adjusted and is therefore causing this notification of adjustment.

run()

Main runloop of the scheduler.

While looping:

1. Checks the queue of tasks to be added to the scheduler

   The time the task is due to be executed is calculated and used as the sort key when the task is inserted into a priority queue.

2. Checks any queued requests to reschedule tasks (due to clock adjustments)

   The existing task in the scheduler priority queue is “deprecated” And a new task is scheduled with the revised time of execution

3. checks any tasks that need to now be executed

Dequeues them and executes them, or ignores them if they are marked as deprecated

schedule(clock, whenTicks, callBack, args, kwargs)

Queue up a task for scheduling

Parameters:

• clock – (dvbcss.clock.ClockBase) the clock against which the task is scheduled
• whenTicks – (int) The tick value of the clock at which the scheduled task is to be executed
• callback – (func) The function (the task) that will be called at the scheduled time
• args – (list) List of arguments to be passed to the function when it is invoked
• kwargs – (dict) Dictionary of keyword arguments to be passed to the function when it is invoked

stop()

Stops the scheduler if it is running.

class dvbcss.task._Task(clock, whenTicks, callBack, args, kwargs, n=0)

Representation of a scheduled task. This is an internal of the Task module. For normal use you should not need to acess it.

Initialiser

Parameters:

• clock – (dvbcss.clock.ClockBase) the clock against which the task is scheduled
• whenTicks – (int) The tick value of the clock at which the scheduled task is to be executed
• callback – (func) The function (the task) that will be called at the scheduled time
• args – (list) List of arguments to be passed to the function when it is invoked
• kwargs – (dict) Dictionary of keyword arguments to be passed to the function when it is invoked
• n – (int) Generation count. Incremented whenever the task is based on a previous task (i.e. it is a rescheduled task)

regenerateAndDeprecate()

Sets the deleted flag of this task to True, and returns a new task the same as this one but not deleted and with the scheduled time ‘when’ recalculated from the clock