pymin/eventloop.py

   1 # vim: set encoding=utf-8 et sw=4 sts=4 :
   2
   3 r"""
   4 A simple event loop.
   5
   6 Please see EventLoop class documentation for more info.
   7 """
   8
   9 import select
  10 import errno
  11 import signal
  12 from select import POLLIN, POLLPRI, POLLERR
  13
  14 __ALL__ = ('EventLoop', 'LoopInterruptedError')
  15
  16 class LoopInterruptedError(RuntimeError):
  17     r"""
  18     LoopInterruptedError(select_error) -> LoopInterruptedError instance.
  19
  20     This class is raised when the event loop is interrupted in an unexpected
  21     way. It wraps a select error, which can be accessed using the 'select_error'
  22     attribute.
  23     """
  24
  25     def __init__(self, select_error):
  26         r"""Initialize the object.
  27
  28         See the class documentation for more info.
  29         """
  30         self.select_error = select_error
  31
  32     def __repr__(self):
  33         r"repr(obj) -> Object representation."
  34         return 'LoopInterruptedError(select_error=%r)' % self.select_error
  35
  36     def __str__(self):
  37         r"str(obj) -> String representation."
  38         return 'Loop interrupted: %s' % self.select_error
  39
  40 # Flag to know if a timer was expired
  41 timeout = False
  42
  43 # Alarm Signal handler
  44 def alarm_handler(signum, stack_frame):
  45     global timeout
  46     timeout = True
  47
  48 class EventLoop:
  49     r"""EventLoop(file[, timer[, handler[, timer_handler]]]) -> EventLoop.
  50
  51     This class implements a simple event loop based on select module.
  52     It "listens" to activity a single 'file' object (a file, a pipe,
  53     a socket, or even a simple file descriptor) and calls a 'handler'
  54     function (or the handle() method if you prefer subclassing) every
  55     time the file is ready for reading (or has an error).
  56
  57     If a 'timer' is supplied, then the timer_handler() function object
  58     (or the handle_timer() method) is called every 'timer' seconds.
  59
  60     This is a really simple example of usage using a hanlder callable:
  61
  62     >>> import os
  63     >>> def handle(event_loop):
  64             data = os.read(event_loop.fileno, 100)
  65             os.write(1, 'Received message: %r\n' % data)
  66     >>> p = EventLoop(0, handle)
  67     >>> p.loop(once=True)
  68
  69     In this example only one event is handled (see the 'once' argument
  70     of loop).
  71
  72     A more complex example, making a subclass and explicitly stopping
  73     the loop, looks something like this:
  74
  75     >>> class Test(EventLoop):
  76     >>>     def handle(self):
  77     >>>         data = os.read(self.fileno, 100)
  78     >>>         if data == 'q\n':
  79     >>>             self.stop()
  80     >>>         else:
  81     >>>             os.write(1, 'Received message: %r\n' % data)
  82     >>>     def handle_timer(self):
  83     >>>         print time.strftime('%c')
  84     >>> p = Test(0, timer=5)
  85     >>> p.loop()
  86
  87     This example loops until the user enters a single "q", when stop()
  88     is called and the event loop is exited.
  89     """
  90
  91     def __init__(self, file, handler=None, timer=None, timer_handler=None):
  92         r"""Initialize the EventLoop object.
  93
  94         See EventLoop class documentation for more info.
  95         """
  96         self.poll = select.poll()
  97         self._stop = False
  98         self.__register(file)
  99         self.timer = timer
 100         self.handler = handler
 101         self.timer_handler = timer_handler
 102
 103     def __register(self, file):
 104         r"__register(file) -> None :: Register a new file for polling."
 105         self._file = file
 106         self.poll.register(self.fileno, POLLIN | POLLPRI | POLLERR)
 107
 108     def set_file(self, file):
 109         r"""set_file(file) -> None :: New file object to be monitored
 110
 111         Unregister the previous file object being monitored and register
 112         a new one.
 113         """
 114         self.poll.unregister(self.fileno)
 115         self.__register(file)
 116
 117     def get_file(self):
 118         r"get_file() -> file object/int :: Get the current file object/fd."
 119         return self._file
 120
 121     file = property(get_file, set_file, doc='File object (or descriptor)')
 122
 123     def get_fileno(self):
 124         r"get_fileno() -> int :: Get the current file descriptor"
 125         if hasattr(self.file, 'fileno'):
 126             return self.file.fileno()
 127         return self.file
 128
 129     fileno = property(get_fileno, doc='File descriptor (never a file object)')
 130
 131     def stop(self):
 132         r"""stop() -> None :: Stop the event loop.
 133
 134         The event loop will be interrupted as soon as the current handler
 135         finishes.
 136         """
 137         self._stop = True
 138
 139     def loop(self, once=False):
 140         r"""loop([once]) -> None :: Wait for events.
 141
 142         Wait for events and handle then when they arrive. If once is True,
 143         then only 1 event is processed and then this method returns.
 144         """
 145         # Flag modified by the signal handler
 146         global timeout
 147         # If we use a timer, we set up the signal
 148         if self.timer is not None:
 149             signal.signal(signal.SIGALRM, alarm_handler)
 150             signal.alarm(self.timer)
 151         while True:
 152             try:
 153                 res = self.poll.poll()
 154             except select.error, e:
 155                 # The error is not an interrupt caused by the alarm, then raise
 156                 if e.args[0] != errno.EINTR or not timeout:
 157                     raise LoopInterruptedError(e)
 158             # There was a timeout, so execute the timer handler
 159             if timeout:
 160                 timeout = False
 161                 self.handle_timer()
 162                 signal.alarm(self.timer)
 163             # Not a timeout, execute the regular handler
 164             else:
 165                 self.handle()
 166             # Look if we have to stop
 167             if self._stop or once:
 168                 self._stop = False
 169                 break
 170
 171     def handle(self):
 172         r"handle() -> None :: Abstract method to be overriden to handle events."
 173         self.handler(self)
 174
 175     def handle_timer(self):
 176         r"handle() -> None :: Abstract method to be overriden to handle events."
 177         self.timer_handler(self)
 178
 179 if __name__ == '__main__':
 180
 181     import os
 182     import time
 183
 184     def handle(event_loop):
 185         data = os.read(event_loop.fileno, 100)
 186         os.write(1, 'Received message: %r\n' % data)
 187
 188     p = EventLoop(0, handle)
 189
 190     os.write(1, 'Say something once: ')
 191     p.loop(once=True)
 192     os.write(1, 'Great!\n')
 193
 194     class Test(EventLoop):
 195         def handle(self):
 196             data = os.read(self.fileno, 100)
 197             if data == 'q\n':
 198                 self.stop()
 199             else:
 200                 os.write(1, 'Received message: %r\n' % data)
 201         def handle_timer(self):
 202             print time.strftime('%c')
 203
 204     p = Test(0, timer=5)
 205
 206     os.write(1, 'Say a lot of things, then press write just "q" to stop: ')
 207     p.loop()
 208     os.write(1, 'Ok, bye!\n')
 209