/Demo/threads/Coroutine.py

  1# Coroutine implementation using Python threads.
  2#
  3# Combines ideas from Guido's Generator module, and from the coroutine
  4# features of Icon and Simula 67.
  5#
  6# To run a collection of functions as coroutines, you need to create
  7# a Coroutine object to control them:
  8#    co = Coroutine()
  9# and then 'create' a subsidiary object for each function in the
 10# collection:
 11#    cof1 = co.create(f1 [, arg1, arg2, ...]) # [] means optional,
 12#    cof2 = co.create(f2 [, arg1, arg2, ...]) #... not list
 13#    cof3 = co.create(f3 [, arg1, arg2, ...])
 14# etc.  The functions need not be distinct; 'create'ing the same
 15# function multiple times gives you independent instances of the
 16# function.
 17#
 18# To start the coroutines running, use co.tran on one of the create'd
 19# functions; e.g., co.tran(cof2).  The routine that first executes
 20# co.tran is called the "main coroutine".  It's special in several
 21# respects:  it existed before you created the Coroutine object; if any of
 22# the create'd coroutines exits (does a return, or suffers an unhandled
 23# exception), EarlyExit error is raised in the main coroutine; and the
 24# co.detach() method transfers control directly to the main coroutine
 25# (you can't use co.tran() for this because the main coroutine doesn't
 26# have a name ...).
 27#
 28# Coroutine objects support these methods:
 29#
 30# handle = .create(func [, arg1, arg2, ...])
 31#    Creates a coroutine for an invocation of func(arg1, arg2, ...),
 32#    and returns a handle ("name") for the coroutine so created.  The
 33#    handle can be used as the target in a subsequent .tran().
 34#
 35# .tran(target, data=None)
 36#    Transfer control to the create'd coroutine "target", optionally
 37#    passing it an arbitrary piece of data. To the coroutine A that does
 38#    the .tran, .tran acts like an ordinary function call:  another
 39#    coroutine B can .tran back to it later, and if it does A's .tran
 40#    returns the 'data' argument passed to B's tran.  E.g.,
 41#
 42#    in coroutine coA   in coroutine coC    in coroutine coB
 43#      x = co.tran(coC)   co.tran(coB)        co.tran(coA,12)
 44#      print x # 12
 45#
 46#    The data-passing feature is taken from Icon, and greatly cuts
 47#    the need to use global variables for inter-coroutine communication.
 48#
 49# .back( data=None )
 50#    The same as .tran(invoker, data=None), where 'invoker' is the
 51#    coroutine that most recently .tran'ed control to the coroutine
 52#    doing the .back.  This is akin to Icon's "&source".
 53#
 54# .detach( data=None )
 55#    The same as .tran(main, data=None), where 'main' is the
 56#    (unnameable!) coroutine that started it all.  'main' has all the
 57#    rights of any other coroutine:  upon receiving control, it can
 58#    .tran to an arbitrary coroutine of its choosing, go .back to
 59#    the .detach'er, or .kill the whole thing.
 60#
 61# .kill()
 62#    Destroy all the coroutines, and return control to the main
 63#    coroutine.  None of the create'ed coroutines can be resumed after a
 64#    .kill().  An EarlyExit exception does a .kill() automatically.  It's
 65#    a good idea to .kill() coroutines you're done with, since the
 66#    current implementation consumes a thread for each coroutine that
 67#    may be resumed.
 68
 69import thread
 70import sync
 71
 72class _CoEvent:
 73    def __init__(self, func):
 74        self.f = func
 75        self.e = sync.event()
 76
 77    def __repr__(self):
 78        if self.f is None:
 79            return 'main coroutine'
 80        else:
 81            return 'coroutine for func ' + self.f.func_name
 82
 83    def __hash__(self):
 84        return id(self)
 85
 86    def __cmp__(x,y):
 87        return cmp(id(x), id(y))
 88
 89    def resume(self):
 90        self.e.post()
 91
 92    def wait(self):
 93        self.e.wait()
 94        self.e.clear()
 95
 96class Killed(Exception): pass
 97class EarlyExit(Exception): pass
 98
 99class Coroutine:
100    def __init__(self):
101        self.active = self.main = _CoEvent(None)
102        self.invokedby = {self.main: None}
103        self.killed = 0
104        self.value  = None
105        self.terminated_by = None
106
107    def create(self, func, *args):
108        me = _CoEvent(func)
109        self.invokedby[me] = None
110        thread.start_new_thread(self._start, (me,) + args)
111        return me
112
113    def _start(self, me, *args):
114        me.wait()
115        if not self.killed:
116            try:
117                try:
118                    apply(me.f, args)
119                except Killed:
120                    pass
121            finally:
122                if not self.killed:
123                    self.terminated_by = me
124                    self.kill()
125
126    def kill(self):
127        if self.killed:
128            raise TypeError, 'kill() called on dead coroutines'
129        self.killed = 1
130        for coroutine in self.invokedby.keys():
131            coroutine.resume()
132
133    def back(self, data=None):
134        return self.tran( self.invokedby[self.active], data )
135
136    def detach(self, data=None):
137        return self.tran( self.main, data )
138
139    def tran(self, target, data=None):
140        if not self.invokedby.has_key(target):
141            raise TypeError, '.tran target %r is not an active coroutine' % (target,)
142        if self.killed:
143            raise TypeError, '.tran target %r is killed' % (target,)
144        self.value = data
145        me = self.active
146        self.invokedby[target] = me
147        self.active = target
148        target.resume()
149
150        me.wait()
151        if self.killed:
152            if self.main is not me:
153                raise Killed
154            if self.terminated_by is not None:
155                raise EarlyExit, '%r terminated early' % (self.terminated_by,)
156
157        return self.value
158
159# end of module