Windows¶

Windows NT 5.0 (Windows 2000 Professional) or later is supported, including the cygwin environment.

The time() function and its variants are based on the QueryPerformanceCounter() high resolution timer system call. This clock is guaranteed to be monotonic and have 1 microsecond precision or better.

The sleep() function is based on the CreateWaitableTimer() and SetWaitableTimer() system calls.

Note that the sleep() function for Windows is not guaranteed to be accurate because it is not possible to create blocking (non polling) delays based on the clock source used. However it should have significantly higher precision than the standard 15ms windows timers and will be fine for short delays.

Mac OS X¶

The time() function and its variants are based on the mach_absolute_time() system call.

The clock is guaranteed to be monotonic. Apple provides no guarantees on precision, however in practice it is usually based on hardware tick counters in the processor or support chips and so is extremely high precision (microseconds or better).

The sleep() function is based on the nanosleep() system call. It is unclear whether this uses the same underlying counter as mach_absolute_time().

Linux¶

The time() function and its variants are based on the clock_gettime() system call requesting CLOCK_MONOTONIC.

The sleep() function is based on the nanosleep() system call. It is unclear whether this uses the same underlying counter as CLOCK_MONOTONIC.

time(), timeMicros() and timeNanos()¶

dvbcss.monotonic_time.time()[source]¶

Return monotonic time in seconds and fractions of seconds (as a float). The precision is operating system dependent.

dvbcss.monotonic_time.timeMicros()[source]¶

Return monotonic time in integer microseconds. The precision is operating system dependent.

dvbcss.monotonic_time.timeNanos()[source]¶

Return monotonic time in integer nanoseconds. The precision is operating system dependent.

sleep()¶

dvbcss.monotonic_time.sleep(t)[source]¶

Sleep for specified number of second and fractions of seconds (as a float). The precision is operating system dependent.

Throws TimeoutError:
	if the underlying system call used to sleep reported a timeout (OS dependent behaviour)
Throws InterruptedException:
	if a signal or other interruption is received while sleeping (OS dependent behaviour)

Note

For all supported operating systems, the sleep() function is not guaranteed to use the same underlying timer as the time() and therefore should be considered inaccurate.

Simple hierarchies of clocks¶

Here is a simple example where a clock represents a timeline and another represents a timeline related to the first by a correlation:

from dvbcss.clock import SysClock
from dvbcss.clock import CorrelatedClock

# create a clock based on dvbcss.monotonic_time.time() that ticks in milliseconds
sysClock = SysClock(tickRate=1000)

# create a clock to represent a timeline 
baseTimeline = CorrelatedClock(parentClock=sysClock, tickRate=25, correlation=(0,0))

# create a clock representing another timeline, where time zero corresponds to time 100
# on the parent timeline
subTimeline = CorrelatedClock(parentClock=baseTimeline, tickRate=25, correlation=(100,0)

At some point later in time during the program, we query the values of all the clocks, confirming that the sub timeline is always 100 ticks ahead of the base timeline.

def printTimes():
    sys  = sysClock.ticks()
    base = baseTimeline.ticks()
    sub  = subTimeline.ticks()
    print "SysClock      ticks = %d", sys
    print "Base timeline ticks = %d", base
    print "Sub timeline  ticks = %d", sub
    
>>> printTimes()
SysClock      ticks = 20000
Base timeline ticks = 500
Sub timeline  ticks = 600 

Note that in these examples, for clarity, the tick count on the sysClock is artificially low. It would likely be a much larger value.

We then change the correlation for the base timeline, declaring tick 25 on its baseline to correspond to tick 0 on its parent timeline, and both the base timeline and the sub timeline reflect this:

>>> baseTimeline.correlation = (0,25)
>>> printTimes()
SysClock      ticks = 30000
Base timeline ticks = 775
Sub timeline  ticks = 875 

Clock speed adjustment¶

All clocks have a speed property. Normally this is 1.0. Some clock classes support changing this value. This scales the rate at which the clock ticks relative to its parent. For example, 0.5 corresponds to half speed; 2.0 = double speed, 0 = frozen and -1.0 = reverse.

Clocks will take speed into account when returning their current tick position or converting it to or from the tick value of a parent clock. However it does not alter the tickRate property. A child clock will similarly ignore the speed property of a parent clock. In this way, the speed property can be used to tweak the speed of time, or to emulate speed control (fast forward, rewind, pause) for a media timeline.

Here is an example where we create 3 clocks in a chain and all tick initially at 100 ticks per second:

>>> import time
>>> baseClock = Sysclock(tickRate=100)
>>> clock1 = TunableClock(parent=baseClock, tickRate=100)
>>> clock2 = TunableClock(parent=clock1, tickRate=100)

We confirm that both clock1 and its child - clock2 - tick at 100 ticks per second:

>>> print clock1.ticks; time.sleep(1.0); print clock1.ticks
5023
5123
>>> print clock2.ticks; time.sleep(1.0); print clock2.ticks
2150
2250

If we change the tick rate of clock1 this affects clock1, but its child - clock2 - continues to tick at 100 ticks every second:

>>> clock1.tickRate = 200
>>> print clock1.ticks; time.sleep(1.0); print clock1.ticks
5440
5640
>>> print clock2.ticks; time.sleep(1.0); print clock2.ticks
4103
4203

But if we instead change the speed multiplier of clock1 then this not only affects the ticking rate of clock1 but also of its child - clock2:

>>> clock1.tickRate = 100
>>> clock1.speed = 2.0
>>> print clock1.ticks; time.sleep(1.0); print clock1.ticks
5740
5940
>>> print clock2.ticks; time.sleep(1.0); print clock2.ticks
4603
4803

Translating tick values between clocks¶

The clock classes provide mechanisms to translate a tick value from one clock to a tick value of another clock such that it still represents the same moment in time. So long as both clocks share a common ancestor clock, the conversion will be possible.

toParentTicks() and fromParentTicks() converts tick values for a clock to/from its parent clock. toOtherClockTicks() will convert a tick value for this clock to the corresponding tick value for any other clock with a common ancestor to this one.

from dvbcss.clock import SysClock
from dvbcss.clock import CorrelatedClock

# create a clock based on dvbcss.monotonic_time.time() that ticks in milliseconds
sysClock = SysClock(tickRate=1000)

#                                       +------------+
#                                   .-- | mediaClock |
# +----------+     +-----------+ <--'   +------------+
# | sysClock | <-- | wallClock | 
# +----------+     +-----------+ <--.   +-----------------+
#                                   '-- | otherMediaClock |
#                                       +-----------------+

wallClock = CorrelatedClock(parentClock=sysClock, tickRate=1000000000, correlation=(0,0))
mediaClock = CorrelatedClock(parentClock=wallClock, tickRate=25, correlation=(500021256, 0))
otherMediaClock = CorrelatedClock(parentClock=wallClock, tickRate=30, correlation=(21093757, 0))

# calculate wall clock time 'w' corresponding to a mediaClock time 1582:
t = 1582
w = mediaClock.toParentTicks(t)    
print "When MediaClock ticks =", t, " wall clock ticks =", w

# calculate mediaClock time 'm' corresponding to wall clock time 1920395
w = 1920395
m = mediaClock.fromParentTicks(w)
print "When wall clock ticks =", w, " media clock ticks =", m

# calculate other media clock time corresponding to media clock time 2248
t = 2248
o = mediaClock.toOtherClockTicks(otherMediaClock, t)
print "When MediaClock ticks =", t, " other media clock ticks =", o

Implementing new clocks¶

Implement a new clock class by subclassing ClockBase and implementing the stub methods.

For example, here is a clock that is the same as its parent (same tick rate) except that its current tick value differs by a fixed offset.

from dvbcss.clock import ClockBase

class FixedTicksOffsetClock(ClockBase):

    def __init__(self, parent, offset):
        super(FixedTicksOffsetClock,self).__init__()
        self._parent = parent
        self._offset = offset
        
    def calcWhen(self, ticksWhen):
        return self._parent.calcWhen(ticksWhen - self._offset)
        
    def fromParentTicks(self, ticks):
        return ticks + self._offset
        
    def getParent(self):
        return self._parent
        
    @property
    def tickRate(self):
        return self._parent.tickRate
    
    @property
    def ticks(self)
        return self._parent.ticks + self._offset
        
    def toParentTicks(self, ticks):
        return ticks - self._offset

In use:

>>> f = FixedTicksOffsetClock(parentClock, 100)
>>> print parentClock.ticks, f.ticks
216 316

When doing this, you must decide whether to allow the speed to be adjusted. If you do, then it must be taken into account in the calculations for the methods: calcWhen(), fromParentTicks() and toParentTicks().

measurePrecision - estimate measurement precision of a clock¶

dvbcss.clock.measurePrecision(clock, sampleSize=10000)[source]¶

Do a very rough experiment to work out the precision of the provided clock.

Works by empirically looking for the smallest observable difference in the tick count.

Parameters:	clock – (:class:dvbcss.clock.ClockBase) Clock to measure sampleSize – (int) Number of iterations (sample size) to estimate the precision over
Returns:	(float) estimate of clock measurement precision (in seconds)

ClockBase - base class for clocks¶

class dvbcss.clock.ClockBase(**kwargs)[source]¶

Base class for all clock classes.

By default, adjusting tickRate and speed are not permitted unless a subclass overrides and implements a property setter.

bind(dependent)[source]¶

Bind for notification if this clock changes.

Parameters:	dependent – When this clock changes, the notify() method of this dependent will be called, passing a single argument that is this clock.

calcWhen(ticksWhen)[source]¶

Return:	“when” in terms of the underlying clock behind the root clock implementation (e.g. monotonic_time.time() in the case of SysClock)

This is a stub for this method. Sub-classes should implement it.

fromParentTicks(ticks)[source]¶

This is a stub for this method. Sub-classes should implement it.

Method to convert from a tick value for this clock’s parent to the equivalent tick value (representing the same point in time) for this clock.

Implementations should use the parent clock’s tickRate and speed properties when performing the conversion.

Returns:	The specified tick value for the parent clock converted to the timescale of this clock.
Throws StopIteration:
	if this clock has no parent

getEffectiveSpeed()[source]¶

Returns the ‘effective speed’ of this clock.

This is equal to multiplying together the speed properties of this clock and all of the parents up to the root clock.

getParent()[source]¶

This is a stub for this method. Sub-classes should implement it.

Returns:	ClockBase representing the immediate parent of this clock, or None if it is a root clock.

nanos[source]¶

(read only) The tick count of this clock, but converted to units of nanoseconds, based on the current tick rate (but ignoring the speed property).

nanosToTicks(nanos)[source]¶

Convert the supplied nanosecond to number of ticks given the current tick rate of this clock (but ignoring the speed property).

Parameters:	nanos – nanoseconds value
Returns:	number of ticks equivalent to the supplied nanosecond value

notify(cause)[source]¶

Call to notify this clock that the clock on which it is based (its parent) has changed relative to the underlying timing source.

Parameters:	cause – The clock that is calling this method.

Will notify all dependents of this clock (entities that have registered themselves by calling bind()).

speed[source]¶

(read/write float) The speed at which the clock is running. Does not change the reported tickRate value, but will affect how ticks are calculated from parent clock ticks. Default = 1.0 = normal tick rate.

tickRate[source]¶

(read only)The tick rate (in ticks per second) of this clock.

This is a stub for this method. Sub-classes should implement it.

ticks[source]¶

(read only) The tick count for this clock.

This is a stub for this method. Sub-classes should implement it.

toOtherClockTicks(otherClock, ticks)[source]¶

Converts a tick value for this clock into a tick value corresponding to the timescale of another clock.

Parameters:	otherClock – A clock object representing another clock. ticks – A time (tick value) for this clock
Returns:	The tick value of the otherClock that represents the same moment in time.
Throws NoCommonClock:
	if there is no common ancestor clock (meaning it is not possible to convert

toParentTicks(ticks)[source]¶

This is a stub for this method. Sub-classes should implement it.

Method to convert from a tick value for this clock to the equivalent tick value (representing the same point in time) for the parent clock.

Implementations should use the parent clock’s tickRate and speed properties when performing the conversion.

Returns:	The specified tick value of this clock converted to the timescale of the parent clock.
Throws StopIteration:
	if this clock has no parent

unbind(dependent)[source]¶

Unbind from notification if this clock changes.

Parameters:	dependent – The dependent to unbind from receiving notifications.

SysClock - Clock based on time module¶

class dvbcss.clock.SysClock(tickRate=1000000, **kwargs)[source]¶

A clock based directly on the standard library timer function monotonic_time.time(). Returns integer ticks when its ticks property is queried.

The default tick rate is 1 million ticks per second, but a different tick rate can be chosen during initialisation.

It is not permitted to change the tickRate or speed property of this clock because it directly represents a system clock.

Parameters:	tickRate – (int) tick rate for this clock (in ticks per second)

bind(dependent)[source]¶

Bind for notification if this clock changes.

Parameters:	dependent – When this clock changes, the notify() method of this dependent will be called, passing a single argument that is this clock.

calcWhen(ticksWhen)[source]¶

Return:	“when” in terms of the underlying clock behind the root clock implementation (e.g. monotonic_time.time() in the case of SysClock)

(Documentation inherited from ClockBase)

fromParentTicks(ticks)[source]¶

Method to convert from a tick value for this clock’s parent to the equivalent tick value (representing the same point in time) for this clock.

Implementations should use the parent clock’s tickRate and speed properties when performing the conversion.

returns:	The specified tick value for the parent clock converted to the timescale of this clock.
throws StopIteration:
	if this clock has no parent

(Documentation inherited from ClockBase)

getEffectiveSpeed()[source]¶

Returns the ‘effective speed’ of this clock.

This is equal to multiplying together the speed properties of this clock and all of the parents up to the root clock.

getParent()[source]¶

returns:	ClockBase representing the immediate parent of this clock, or None if it is a root clock.

(Documentation inherited from ClockBase)

nanos[source]¶

(read only) The tick count of this clock, but converted to units of nanoseconds, based on the current tick rate (but ignoring the speed property).

nanosToTicks(nanos)[source]¶

Convert the supplied nanosecond to number of ticks given the current tick rate of this clock (but ignoring the speed property).

Parameters:	nanos – nanoseconds value
Returns:	number of ticks equivalent to the supplied nanosecond value

notify(cause)[source]¶

Call to notify this clock that the clock on which it is based (its parent) has changed relative to the underlying timing source.

Parameters:	cause – The clock that is calling this method.

Will notify all dependents of this clock (entities that have registered themselves by calling bind()).

speed[source]¶

(read/write float) The speed at which the clock is running. Does not change the reported tickRate value, but will affect how ticks are calculated from parent clock ticks. Default = 1.0 = normal tick rate.

tickRate[source]¶

(read only)The tick rate (in ticks per second) of this clock.

(Documentation inherited from ClockBase)

ticks[source]¶

(read only) The tick count for this clock.

(Documentation inherited from ClockBase)

toOtherClockTicks(otherClock, ticks)[source]¶

Converts a tick value for this clock into a tick value corresponding to the timescale of another clock.

Parameters:	otherClock – A clock object representing another clock. ticks – A time (tick value) for this clock
Returns:	The tick value of the otherClock that represents the same moment in time.
Throws NoCommonClock:
	if there is no common ancestor clock (meaning it is not possible to convert

toParentTicks(ticks)[source]¶

Method to convert from a tick value for this clock to the equivalent tick value (representing the same point in time) for the parent clock.

Implementations should use the parent clock’s tickRate and speed properties when performing the conversion.

returns:	The specified tick value of this clock converted to the timescale of the parent clock.
throws StopIteration:
	if this clock has no parent

(Documentation inherited from ClockBase)

unbind(dependent)[source]¶

Unbind from notification if this clock changes.

Parameters:	dependent – The dependent to unbind from receiving notifications.

CorrelatedClock - Clock correlated to another clock¶

class dvbcss.clock.CorrelatedClock(parentClock, tickRate, correlation=(0, 0), **kwargs)[source]¶

A clock locked to the tick count of the parent clock by a correlation and frequency setting.

Correlation is a tuple (parentTicks, selfTicks)

When the parent clock ticks property has the value parentTicks, the ticks property of this clock shall have the value selfTicks.

This relationship can be illustrated as follows:

You can alter the correlation and tickRate and speed of this clock dynamically. Changes to tickRate and speed will not shift the point of correlation. This means that a change in tickRate or speed will probably cause the current tick value of the clock to jump. The amount it jumps by will be proportional to the distance the current time is from the point of correlation:

If you want a speed change to only affect the ticks from a particular point (e.g. the current tick value) onwards then you must re-base the correlation. There is a function provided to do that in some circumstances:

c = CorrelatedClock(parentClock=parent, tickRate=1000, correlation=(50,78))

   ... time passes ...
   
# now freeze the clock AT ITS CURRENT TICK VALUE

c.rebaseCorrelationAtTicks(c.ticks)
c.speed = 0

# now resume the clock but at half speed, but again without the tick value jumping
c.correlation = ( parent.ticks, c.ticks )
c.speed = 0.5

Note

The maths to calculate and convert tick values will be performed, by default, as integer maths unless the parameters controlling the clock (tickRate etc) are floating point, or the ticks property of the parent clock supplies floating point values.

Parameters:	parentClock – The parent clock for this clock. tickRate – (int) tick rate for this clock (in ticks per second) correlation – (tuple(int, int)) The intial correlation for this clock. A tuple (parent tick value, this clock tick value)

bind(dependent)[source]¶

Bind for notification if this clock changes.

Parameters:	dependent – When this clock changes, the notify() method of this dependent will be called, passing a single argument that is this clock.

calcWhen(ticksWhen)[source]¶

Return:	“when” in terms of the underlying clock behind the root clock implementation (e.g. monotonic_time.time() in the case of SysClock)

(Documentation inherited from ClockBase)

correlation[source]¶

Read or change the correlation tuple (parentTicks, selfTicks) of this clock to its parent clock.

Assign a new tuple (parentTicks, selfTicks) to change the correlation. This value must be a tuple, not a list.

fromParentTicks(ticks)[source]¶

Method to convert from a tick value for this clock’s parent to the equivalent tick value (representing the same point in time) for this clock.

Implementations should use the parent clock’s tickRate and speed properties when performing the conversion.

returns:	The specified tick value for the parent clock converted to the timescale of this clock.
throws StopIteration:
	if this clock has no parent

(Documentation inherited from ClockBase)

getEffectiveSpeed()[source]¶

Returns the ‘effective speed’ of this clock.

This is equal to multiplying together the speed properties of this clock and all of the parents up to the root clock.

getParent()[source]¶

returns:	ClockBase representing the immediate parent of this clock, or None if it is a root clock.

(Documentation inherited from ClockBase)

nanos[source]¶

(read only) The tick count of this clock, but converted to units of nanoseconds, based on the current tick rate (but ignoring the speed property).

nanosToTicks(nanos)[source]¶

Convert the supplied nanosecond to number of ticks given the current tick rate of this clock (but ignoring the speed property).

Parameters:	nanos – nanoseconds value
Returns:	number of ticks equivalent to the supplied nanosecond value

notify(cause)[source]¶

Call to notify this clock that the clock on which it is based (its parent) has changed relative to the underlying timing source.

Parameters:	cause – The clock that is calling this method.

Will notify all dependents of this clock (entities that have registered themselves by calling bind()).

rebaseCorrelationAtTicks(tickValue)[source]¶

Changes the correlation property to an equivalent correlation (that does not change the timing relationship between parent clock and this clock) where the tick value for this clock is the provided tick value.

speed[source]¶

(read/write float) The speed at which the clock is running.

Does not change the reported tickRate value, but will affect how ticks are calculated from parent clock ticks. Default = 1.0 = normal tick rate.

(Documentation inherited from ClockBase)

tickRate[source]¶

Read or change the tick rate (in ticks per second) of this clock. The value read is not affected by the value of the speed property.

ticks[source]¶

(read only) The tick count for this clock.

(Documentation inherited from ClockBase)

toOtherClockTicks(otherClock, ticks)[source]¶

Converts a tick value for this clock into a tick value corresponding to the timescale of another clock.

Parameters:	otherClock – A clock object representing another clock. ticks – A time (tick value) for this clock
Returns:	The tick value of the otherClock that represents the same moment in time.
Throws NoCommonClock:
	if there is no common ancestor clock (meaning it is not possible to convert

toParentTicks(ticks)[source]¶

Method to convert from a tick value for this clock to the equivalent tick value (representing the same point in time) for the parent clock.

Implementations should use the parent clock’s tickRate and speed properties when performing the conversion.

returns:	The specified tick value of this clock converted to the timescale of the parent clock.
throws StopIteration:
	if this clock has no parent

(Documentation inherited from ClockBase)

unbind(dependent)[source]¶

Unbind from notification if this clock changes.

Parameters:	dependent – The dependent to unbind from receiving notifications.

TunableClock - Clock with dynamically adjustable frequency and tick offset¶

class dvbcss.clock.TunableClock(parentClock, tickRate, ticks=0, **kwargs)[source]¶

A clock whose tick offset and speed can be adjusted on the fly. Must be based on another clock.

Advancement of time of this clock is based on the tick count and rates reported by the supplied parent clock.

If you adjust the tickRate or speed, then the change is applied going forward from the moment it is made. E.g. if you are observing the rate of increase of the ticks property, then doubling the speed wil cause the ticks property to start increasing faster but will not cause it to suddenly jump value.

Note

The maths to calculate and convert tick values will be performed, by default, as integer maths unless the parameters controlling the clock (tickRate etc) are floating point, or the ticks property of the parent clock supplies floating point values.

Parameters:	parentClock – The parent clock for this clock. tickRate – The tick rate (ticks per second) for this clock. ticks – The starting tick value for this clock.

The specified starting tick value applies from the moment this object is initialised.

adjustTicks(offset)[source]¶

Change the tick count of this clock by the amount specified.

bind(dependent)[source]¶

Bind for notification if this clock changes.

Parameters:	dependent – When this clock changes, the notify() method of this dependent will be called, passing a single argument that is this clock.

calcWhen(ticksWhen)[source]¶

Return:	“when” in terms of the underlying clock behind the root clock implementation (e.g. monotonic_time.time() in the case of SysClock)

(Documentation inherited from ClockBase)

fromParentTicks(ticks)[source]¶

Method to convert from a tick value for this clock’s parent to the equivalent tick value (representing the same point in time) for this clock.

Implementations should use the parent clock’s tickRate and speed properties when performing the conversion.

returns:	The specified tick value for the parent clock converted to the timescale of this clock.
throws StopIteration:
	if this clock has no parent

(Documentation inherited from ClockBase)

getEffectiveSpeed()[source]¶

Returns the ‘effective speed’ of this clock.

This is equal to multiplying together the speed properties of this clock and all of the parents up to the root clock.

getParent()[source]¶

returns:	ClockBase representing the immediate parent of this clock, or None if it is a root clock.

(Documentation inherited from ClockBase)

nanos[source]¶

(read only) The tick count of this clock, but converted to units of nanoseconds, based on the current tick rate (but ignoring the speed property).

nanosToTicks(nanos)[source]¶

Convert the supplied nanosecond to number of ticks given the current tick rate of this clock (but ignoring the speed property).

Parameters:	nanos – nanoseconds value
Returns:	number of ticks equivalent to the supplied nanosecond value

notify(cause)[source]¶

Call to notify this clock that the clock on which it is based (its parent) has changed relative to the underlying timing source.

Parameters:	cause – The clock that is calling this method.

Will notify all dependents of this clock (entities that have registered themselves by calling bind()).

slew[source]¶

This is an alternative method of querying or adjusting the speed property.

The slew (in ticks per second) currently applied to this clock.

Setting this property will set the speed property to correspond to the specified slew.

For example: for a clock with tickRate of 100, then a slew of -25 corresponds to a speed of 0.75

speed[source]¶

(read/write float) The speed at which the clock is running.

Does not change the reported tickRate value, but will affect how ticks are calculated from parent clock ticks. Default = 1.0 = normal tick rate.

(Documentation inherited from ClockBase)

tickRate[source]¶

Read or change the tick rate (in ticks per second) of this clock. The value read is not affected by the value of the speed property.

ticks[source]¶

(read only) The tick count for this clock.

(Documentation inherited from ClockBase)

toOtherClockTicks(otherClock, ticks)[source]¶

Converts a tick value for this clock into a tick value corresponding to the timescale of another clock.

Parameters:	otherClock – A clock object representing another clock. ticks – A time (tick value) for this clock
Returns:	The tick value of the otherClock that represents the same moment in time.
Throws NoCommonClock:
	if there is no common ancestor clock (meaning it is not possible to convert

toParentTicks(ticks)[source]¶

Method to convert from a tick value for this clock to the equivalent tick value (representing the same point in time) for the parent clock.

Implementations should use the parent clock’s tickRate and speed properties when performing the conversion.

returns:	The specified tick value of this clock converted to the timescale of the parent clock.
throws StopIteration:
	if this clock has no parent

(Documentation inherited from ClockBase)

unbind(dependent)[source]¶

Unbind from notification if this clock changes.

Parameters:	dependent – The dependent to unbind from receiving notifications.

RangeCorrelatedClock - Clock correlated to another clock¶

class dvbcss.clock.RangeCorrelatedClock(parentClock, tickRate, correlation1, correlation2, **kwargs)[source]¶

A clock locked to the tick count of the parent clock by two different points of correlation.

Each correlation is a tuple (parentTicks, selfTicks)

This relationship can be illustrated as follows:

The tickRate you set is purely advisory - it is the tickRate reported to clocks that use this clock as the parent, and may differ from what the reality of the two correlations represents!

Parameters:	parentClock – The parent clock for this clock. tickRate – The advisory tick rate (ticks per second) for this clock. correlation1 – (tuple(int, int)) The first point of correlation for this clock. A tuple (parent tick value, this clock tick value) correlation2 – (tuple(int, int)) The second point of correlation for this clock. A tuple (parent tick value, this clock tick value)

bind(dependent)[source]¶

Bind for notification if this clock changes.

Parameters:	dependent – When this clock changes, the notify() method of this dependent will be called, passing a single argument that is this clock.

calcWhen(ticksWhen)[source]¶

Return:	“when” in terms of the underlying clock behind the root clock implementation (e.g. monotonic_time.time() in the case of SysClock)

(Documentation inherited from ClockBase)

correlation1[source]¶

Read or change the first correlation tuple (parentTicks, selfTicks) of this clock to its parent clock.

Assign a new tuple (parentTicks, selfTicks) to change the correlation. This value must be a tuple, not a list.

correlation2[source]¶

Read or change the first correlation tuple (parentTicks, selfTicks) of this clock to its parent clock.

Assign a new tuple (parentTicks, selfTicks) to change the correlation. This value must be a tuple, not a list.

fromParentTicks(ticks)[source]¶

Method to convert from a tick value for this clock’s parent to the equivalent tick value (representing the same point in time) for this clock.

Implementations should use the parent clock’s tickRate and speed properties when performing the conversion.

returns:	The specified tick value for the parent clock converted to the timescale of this clock.
throws StopIteration:
	if this clock has no parent

(Documentation inherited from ClockBase)

getEffectiveSpeed()[source]¶

Returns the ‘effective speed’ of this clock.

This is equal to multiplying together the speed properties of this clock and all of the parents up to the root clock.

getParent()[source]¶

returns:	ClockBase representing the immediate parent of this clock, or None if it is a root clock.

(Documentation inherited from ClockBase)

nanos[source]¶

(read only) The tick count of this clock, but converted to units of nanoseconds, based on the current tick rate (but ignoring the speed property).

nanosToTicks(nanos)[source]¶

Convert the supplied nanosecond to number of ticks given the current tick rate of this clock (but ignoring the speed property).

Parameters:	nanos – nanoseconds value
Returns:	number of ticks equivalent to the supplied nanosecond value

notify(cause)[source]¶

Call to notify this clock that the clock on which it is based (its parent) has changed relative to the underlying timing source.

Parameters:	cause – The clock that is calling this method.

Will notify all dependents of this clock (entities that have registered themselves by calling bind()).

speed[source]¶

(read/write float) The speed at which the clock is running.

Does not change the reported tickRate value, but will affect how ticks are calculated from parent clock ticks. Default = 1.0 = normal tick rate.

(Documentation inherited from ClockBase)

tickRate[source]¶

Read the tick rate (in ticks per second) of this clock. The value read is not affected by the value of the speed property.

ticks[source]¶

(read only) The tick count for this clock.

(Documentation inherited from ClockBase)

toOtherClockTicks(otherClock, ticks)[source]¶

Converts a tick value for this clock into a tick value corresponding to the timescale of another clock.

Parameters:	otherClock – A clock object representing another clock. ticks – A time (tick value) for this clock
Returns:	The tick value of the otherClock that represents the same moment in time.
Throws NoCommonClock:
	if there is no common ancestor clock (meaning it is not possible to convert

toParentTicks(ticks)[source]¶

Method to convert from a tick value for this clock to the equivalent tick value (representing the same point in time) for the parent clock.

Implementations should use the parent clock’s tickRate and speed properties when performing the conversion.

returns:	The specified tick value of this clock converted to the timescale of the parent clock.
throws StopIteration:
	if this clock has no parent

(Documentation inherited from ClockBase)

unbind(dependent)[source]¶

Unbind from notification if this clock changes.

Parameters:	dependent – The dependent to unbind from receiving notifications.

Overview¶

The CSS-WC server is based on a simple generic framework for building UDP servers

Classes¶

Overview¶

The CSS-CII and CSS-TS servers subclass the WebSocket server functionality for cherrypy implemented by ws4py in the cherrypyserver module.

CIIServer and TSServer both inherit from a common base implementation WSServerTool provided in the dvbcss.protocol.server module.

The Tool provides the hook into cherrypy for handling the connection request and upgrading it to a WebSocket connection, spawning an object representing the WebSocket connection and which implements the WebSocket protocols.

The base server object class is intended to manage all WebSocket connections for a particular server endpoint. It therefore provides its own customised WebScoket class that is bound to that particular server object instance.

The tool is enabled via an “on” configuration when setting up the mount point in cherrypy. The tool also expects to a “handler_cls” property set in the configuration at the mount point. This property points to a WebSocket class which can be instantiated to handle the connection.

Example usage: creating a server at “ws://<host>:80/endpoint” just using the base classes provided here:

import cherrypy
from ws4py.server.cherrypyserver import WebSocketPlugin
from dvbcss.protocol.server import WSServerBase, WSServerTool

# plug the tool into cherrypy as "my_server"
cherrypy.tools.my_server = WSServerTool()

WebSocketPlugin(cherrypy.engine).subscribe()

# create my server
myServer = WSServerBase()

# bind it to the URL path /endpoint in the cherrypy server
class Root(object):
    @cherrypy.expose
    def endpoint(self):
        pass

cfg = {"/endpoint": {'tools.my_server.on': True,
                'tools.my_server.handler_cls': myServer.handler
               }
      }

cherrypy.tree.mount(Root(), "/", config=cfg)

# activate cherrypy web server on port 80
cherrypy.config.update({"server.socket_port":80})
cherrypy.engine.start()

See documentation for WSServerBase for information on creating subclasses to implement specific endpoints.

Classes¶

class .WebSocketHandler(WebSocket)[source]¶

This class is created and returned by the WSServerBase._makeHandlerClass() method and each class returned is bound to the instance of WSServerBase that created it.

It is intended to be provided to cherrypy as the “handler_cls” configuration parameter for the WebSocket tool. It is instantiated for every connection made.

These are subclasses of the ws4py WebSocket class and represent an individual WebSocket connection.

Instances of this class call through to WSServerBase._addConnection() and WSServerBase._removeConnection() and WSServerBase._receivedMessage() to inform the parent server of the WebSocket opening, closing and receiving messages.

classmethod isEnabled(cls)[source]¶

Returns:	True if the server endpoint is enabled, otherwise False.

classmethod canAllocateConnection(cls)[source]¶

Returns:	True only if the connection limit of the parent server has not yet been reached. Otherwise False.

id(self)[source]¶

Returns:	A human readable connection ID