# Encoding: UTF-8
"""Gillcup's Clock Class
In Gillcup, animation means two things: running code at specified times,
and changing object properties with time.
You will notice that the preceding sentence mentions time quite a lot. But
what is this time?
You could determine time by looking at the computer's clock, but that would
only work with real-time animations. When you'd want to render a movie,
where each frame takes 2 seconds to draw and there are 25 frames per
second, you'd be stuck.
That's why Gillcup introduces a flexible source of time, the Clock, which
keeps track of time and schedules actions.
Time is measured in “time units”.
What a time unit means is entirely up to the application – it could be
seconds, movie/simulation frames, etc.
"""
from __future__ import unicode_literals, division, print_function
import collections
import weakref
import heapq
from gillcup.properties import AnimatedProperty
_HeapEntry = collections.namedtuple('EventHeapEntry', 'time index action')
# Next action index; used to keep FIFO ordering for actions scheduled
# for the same time
next_index = 0
class Clock(object):
"""Keeps track of time and schedules events.
Attributes:
.. attribute:: time
The current time on the clock. Never assign to it directly;
use :meth:`~gillcup.Clock.advance()` instead.
"""
def __init__(self):
# Time on the clock
self.time = 0
# Heap queue of scheduled actions
self.events = []
# Update functions (see `schedule_update_function`)
self.update_functions = WeakSet()
# Recursion guard flag for advance()
self.advancing = False
# List of dependent clocks
self._subclocks = set()
speed = AnimatedProperty(1, docstring="""Speed of the clock.
When calling update(), the interval is multiplied by this value.
The speed is an AnimatedProperty. When changing, beware that it is only
checked when advance() is called or when a scheduled action is run,
so speed animations will be only approximate.
For better accuracy, call :meth:`~gillcup.Clock.advance`
with small *dt*, or schedule a periodic dummy action at small inervals.
""")
@property
def _next_event(self):
try:
event = self.events[0]
events = [(event.time - self.time, event.index, self, event)]
except IndexError:
events = []
for subclock in self._subclocks:
event = subclock._next_event # pylint: disable=W0212
if event:
remain, index, clock, event = event
try:
remain /= subclock.speed
except ZeroDivisionError:
# zero speed – events never happen
pass
else:
events.append((remain, index, clock, event))
try:
return min(events)
except ValueError:
return None
def advance(self, dt):
"""Call to advance the clock's time
Steps the clock dt units to the future, pausing at times when actions
are scheduled, and running them.
Attempting to move to the past (dt<0) will raise an error.
"""
dt *= self.speed
if dt < 0:
raise ValueError('Moving backwards in time')
if self.advancing:
raise RuntimeError('Clock.advance called recursively')
self.advancing = True
try:
while True:
event = self._next_event
if not event:
break
event_dt, _index, clock, event = event
if event_dt > dt:
break
if dt:
self._advance(event_dt)
self._run_update_functions()
dt -= event_dt
_evt = heapq.heappop(clock.events)
assert _evt is event and clock.time == event.time
clock.time = event.time
event.action()
if dt:
self._advance(dt)
self._run_update_functions()
finally:
self.advancing = False
def _advance(self, dt):
self.time += dt
for subclock in self._subclocks:
subclock._advance(dt * subclock.speed) # pylint: disable=W0212
def schedule(self, action, dt=0):
"""Schedule an action to be run "dt" time units from the current time
Scheduling is stable: if two things are scheduled for the same
time, they will be called in the order they were scheduled.
Scheduling an action in the past (dt<0) will raise an error.
If the scheduled callable has a “schedule_callback” method, it will
be called with the clock and the time it's been scheduled at.
"""
global next_index
if dt < 0:
raise ValueError('Scheduling an action in the past')
next_index += 1
scheduled_time = self.time + dt
entry = _HeapEntry(scheduled_time, next_index, action)
heapq.heappush(self.events, entry)
try:
schedule_callback = action.schedule_callback
except AttributeError:
pass
else:
schedule_callback(self, scheduled_time)
def schedule_update_function(self, function):
"""Schedule a function to be called every time the clock advances
Then function will be called a lot, so it shouldn't be very expensive.
Only a weak reference is made to the function, so the caller should
ensure another reference to it is retained as long as it should be
called.
"""
self.update_functions.add(function)
def unschedule_update_function(self, function):
"""Unschedule a function scheduled by `schedule_update_function`
"""
# Don't raise an error if the function is no longer there – we're
# dealing with weakrefs.
self.update_functions.discard(function)
def _run_update_functions(self):
for update_function in list(self.update_functions):
update_function()
for subclock in self._subclocks:
subclock._run_update_functions() # pylint: disable=W0212
class Subclock(Clock):
"""A Clock that advances in sync with another Clock
A Subclock advances whenever its *parent* clock does.
Its `speed` attribute specifies the relative speed relative to the parent
clock. For example, if speed==2, the subclock will run twice as fast as its
parent clock.
Unlike clocks synchronized via actions or update functions, the actions
scheduled on a parent Clock and all subclocks are run in the correct
sequence, with all clocks at the correct times when each action is run.
"""
def __init__(self, parent, speed=1):
super(Subclock, self).__init__()
self.speed = speed
parent._subclocks.add(self) # pylint: disable=W0212
try: # pragma: no cover
WeakSet = weakref.WeakSet # pylint: disable=E1101
except AttributeError: # pragma: no cover
class WeakSet(weakref.WeakKeyDictionary):
"""Stripped-down WeakSet implementation for Python 2.6
(only defines the methods we need)
"""
def add(self, item):
"""Add an item to the set"""
self[item] = None
def discard(self, item):
"""Remove an item from the set"""
self.pop(item)