1"""The tasks module provides a simple light-weight alternative to threads. 2 3When you have a long-running job you will want to run it in the background, 4while the user does other things. There are four ways to do this: 5 6 - Use a new thread for each task. 7 - Use callbacks from an idle handler. 8 - Use a recursive mainloop. 9 - Use this module. 10 11Using threads causes a number of problems: they introduce race conditions, 12often lead to many subtle bugs, and they require lots of resources (you 13probably wouldn't want 10,000 threads running at once). In particular, two 14threads can run at exactly the same time (perhaps on different processors), so 15you have to be really careful that they don't both try to update the same 16variables at the same time. This requires lots of messy locking, which is hard 17to get right. 18 19Callbacks work within a single thread. For example, you open a dialog box and 20then tell the system to call one function if it's closed, and another if the 21user clicks OK, etc. The function that opened the box then returns, and the 22system calls one of the given callback functions later. Callbacks only 23execute one at a time, so you don't have to worry about race conditions. 24However, they are often very awkward to program with, because you have to 25save state somewhere and then pass it to the functions when they're called. 26 27A recursive mainloop only works with nested tasks (you can create a 28sub-task, but the main task can't continue until the sub-task has 29finished), so they are not appropriate for long-running jobs. 30 31Tasks use Python's generator API to provide a more pleasant interface to 32callbacks. See the Task class (below) for more information. 33""" 34 35# Copyright (C) 2009, Thomas Leonard 36# See the README file for details, or visit http://0install.net. 37 38fromzeroinstallimport_,support,logger,gobject 39importsys 40 41ifgobject:
102raiseException("No mainloop available: install python3-gi or tulip")
103tulip=loop=Fail()104else:105loop=tulip.get_event_loop()106107# The list of Blockers whose event has happened, in the order they were108# triggered109_run_queue=[]
112"""See if any of the blockers have pending exceptions.113 If reporter is None, raise the first and log the rest.114 @type blockers: [L{Blocker}]115 @param reporter: invoke this function on each error"""116ex=None117ifisinstance(blockers,Blocker):118blockers=(blockers,)119forbinblockers:120ifb.exception:121b.exception_read=True122ifreporter:123try:124reporter(*b.exception)125except:126logger.warning("Failure reporting error! Error was: %s",repr(b.exception[0]))127raise128elifexisNone:129ex=b.exception130else:131logger.warning(_("Multiple exceptions waiting; skipping %s"),b.exception[0])132ifex:133support.raise_with_traceback(ex[0],ex[1])
136"""A Blocker object starts life with 'happened = False'. Tasks can137 ask to be suspended until 'happened = True'. The value is changed138 by a call to trigger().139140 Example:141142 >>> kettle_boiled = tasks.Blocker()143 >>> def make_tea():144 print "Get cup"145 print "Add tea leaves"146 yield kettle_boiled147 print "Pour water into cup"148 print "Brew..."149 yield tasks.TimeoutBlocker(120, "Brewing")150 print "Add milk"151 print "Ready!"152 >>> tasks.Task(make_tea())153154 Then elsewhere, later::155156 print "Kettle boiled!"157 kettle_boiled.trigger()158159 You can also yield a list of Blockers. Your function will resume160 after any one of them is triggered. Use blocker.happened to161 find out which one(s). Yielding a Blocker that has already162 happened is the same as yielding None (gives any other Tasks a163 chance to run, and then continues).164 """165166exception=None167
169"""@type name: str"""170self.happened=False# False until event triggered171self._zero_lib_tasks=set()# Tasks waiting on this blocker172self.name=name
175"""The event has happened. Note that this cannot be undone;176 instead, create a new Blocker to handle the next occurance177 of the event.178 @param exception: exception to raise in waiting tasks179 @type exception: (Exception, traceback)"""180ifself.happened:return# Already triggered181self.happened=True182self.exception=exception183self.exception_read=False184#assert self not in _run_queue # Slow185ifnot_run_queue:186_schedule()187_run_queue.append(self)188189ifexception:190assertisinstance(exception,tuple),exception191ifnotself._zero_lib_tasks:192logger.info(_("Exception from '%s', but nothing is waiting for it"),self)193importtraceback194logger.debug(''.join(traceback.format_exception(type(exception[0]),exception[0],exception[1])))
195196# (causes leaks by preventing blockers from being GC'd if in cycles)197#def __del__(self):198# if self.exception and not self.exception_read:199# warn(_("Blocker %(blocker)s garbage collected without having it's exception read: %(exception)s"), {'blocker': self, 'exception': self.exception})200
202"""Called by the schedular when a Task yields this203 Blocker. If you override this method, be sure to still204 call this method with Blocker.add_task(self)!205 @type task: L{Task}"""206asserttasknotinself._zero_lib_tasks,"Blocking on a single task twice: %s (%s)"%(task,self)207self._zero_lib_tasks.add(task)
210"""Called by the schedular when a Task that was waiting for211 this blocker is resumed.212 @type task: L{Task}"""213self._zero_lib_tasks.remove(task)
222"""An IdleBlocker blocks until a task starts waiting on it, then223 immediately triggers. An instance of this class is used internally224 when a Task yields None."""
234"""Trigger after 'timeout' seconds (may be a fraction).235 @type timeout: float236 @type name: str"""237Blocker.__init__(self,name)238loop.call_later(timeout,self._timeout)
294"""Create a new Task when you have some long running function to295 run in the background, but which needs to do work in 'chunks'.296 Example:297298 >>> from zeroinstall import tasks299 >>> def my_task(start):300 for x in range(start, start + 5):301 print "x =", x302 yield None303304 >>> tasks.Task(my_task(0))305 >>> tasks.Task(my_task(10))306 >>> mainloop()307308 Yielding None gives up control of the processor to another Task,309 causing the sequence printed to be interleaved. You can also yield a310 Blocker (or a list of Blockers) if you want to wait for some311 particular event before resuming (see the Blocker class for details).312 """313
315"""Call next(iterator) from a glib idle function. This function316 can yield Blocker() objects to suspend processing while waiting317 for events. name is used only for debugging.318 @type name: str"""319self.iterator=iterator320self.finished=Blocker(name)321# Block new task on the idle handler...322_idle_blocker.add_task(self)323self._zero_blockers=(_idle_blocker,)324logger.info(_("Scheduling new task: %s"),self)
327# Remove from our blockers' queues328forblockerinself._zero_blockers:329blocker.remove_task(self)330# Resume the task331try:332new_blockers=next(self.iterator)333exceptStopIteration:334# Task ended335self.finished.trigger()336return337exceptSystemExit:338raise339except(Exception,KeyboardInterrupt)asex:340# Task crashed341logger.info(_("Exception from '%(name)s': %(exception)s"),{'name':self.finished.name,'exception':ex})342#import traceback343#debug(''.join(traceback.format_exception(*sys.exc_info())))344tb=sys.exc_info()[2]345self.finished.trigger(exception=(ex,tb))346return347ifnew_blockersisNone:348# Just give up control briefly349new_blockers=(_idle_blocker,)350else:351ifisinstance(new_blockers,Blocker):352# Wrap a single yielded blocker into a list353new_blockers=(new_blockers,)354# Are we blocking on something that already happened?355forblockerinnew_blockers:356asserthasattr(blocker,'happened'),"Not a Blocker: %s from %s"%(blocker,self)357ifblocker.happened:358new_blockers=(_idle_blocker,)359logger.info(_("Task '%(task)s' waiting on ready blocker %(blocker)s!"),{'task':self,'blocker':blocker})360break361else:362logger.info(_("Task '%(task)s' stopping and waiting for '%(new_blockers)s'"),{'task':self,'new_blockers':new_blockers})363# Add to new blockers' queues364forblockerinnew_blockers:365blocker.add_task(self)366self._zero_blockers=new_blockers
380global_idle_blocker381assert_run_queue382383next=_run_queue[0]384assertnext.happened385386ifnextis_idle_blocker:387# Since this blocker will never run again, create a388# new one for future idling.389_idle_blocker=IdleBlocker("(idle)")390elifnext._zero_lib_tasks:391logger.info(_("Running %(task)s due to triggering of '%(next)s'"),{'task':next._zero_lib_tasks,'next':next})392else:393logger.info(_("Running %s"),next)394395tasks=frozenset(next._zero_lib_tasks)396iftasks:397next.noticed=True398399fortaskintasks:400# Run 'task'.401task._resume()402403del_run_queue[0]404405if_run_queue:406loop.call_soon(_handle_run_queue)
409"""Decorator that turns a generator function into a function that runs the410 generator as a Task and returns the Task's finished blocker.411 @param name: the name for the Task412 @type name: str"""413defdeco(fn):414defrun(*args,**kwargs):415returnTask(fn(*args,**kwargs),name).finished
421"""Decorator that turns a generator function into a function that runs the422 generator as a Task and returns the Task's finished blocker."""423defrun(*args,**kwargs):424returnTask(fn(*args,**kwargs),fn.__name__).finished