### Navigation

- index
- modules |
- next |
- previous |
- home|
- search|
- API »
- The PyZMQ API »

# eventloop.ioloop

## Module: `eventloop.ioloop`

Inheritance diagram for `zmq.eventloop.ioloop`:

A level-triggered I/O loop for non-blocking sockets.

## Classes

### `DelayedCallback`

class `zmq.eventloop.ioloop.``DelayedCallback`(callback, callback_time, io_loop=None)

  Bases: `zmq.eventloop.ioloop.PeriodicCallback`

  Schedules the given callback to be called once.

  The callback is called after the object is created by callback_time milliseconds.

  `start`()
  `stop`()

### `IOLoop`

class `zmq.eventloop.ioloop.``IOLoop`(impl=None)

  Bases: `object`

  A level-triggered I/O loop.

  We use epoll if it is available, or else we fall back on select(). If you are implementing a system that needs to handle 1000s of simultaneous connections, you should use Linux and either compile our epoll module or use Python 2.6+ to get epoll support.

  Example usage for a simple TCP server:

      import errno
      import functools
      import ioloop
      import socket

      def connection_ready(sock, fd, events):
          while True:
              try:
                  connection, address = sock.accept()
              except socket.error, e:
                  if e.args[0] not in (errno.EWOULDBLOCK, errno.EAGAIN):
                      raise
                  return
              connection.setblocking(0)
              handle_connection(connection, address)

      sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)
      sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
      sock.setblocking(0)
      sock.bind(("", port))
      sock.listen(128)

      io_loop = ioloop.IOLoop.instance()
      callback = functools.partial(connection_ready, sock)
      io_loop.add_handler(sock.fileno(), callback, io_loop.READ)
      io_loop.start()

  `add_callback`(callback)

    Calls the given callback on the next I/O loop iteration.

    This is thread safe because set.add is an atomic operation. The rest of the API is not thread safe.

  `add_handler`(fd, handler, events)

    Registers the given handler to receive the given events for fd.

  `add_timeout`(deadline, callback)

    Calls the given callback at the time deadline from the I/O loop.

  `handle_callback_exception`(callback)

    This method is called whenever a callback run by the IOLoop throws an exception.

    By default simply logs the exception as an error. Subclasses may override this method to customize reporting of exceptions.

    The exception itself is not passed explicitly, but is available in sys.exc_info.

  classmethod `initialized`()
  classmethod `instance`()

    Returns a global IOLoop instance.

    Most single-threaded applications have a single, global IOLoop. Use this method instead of passing around IOLoop instances throughout your code.

    A common pattern for classes that depend on IOLoops is to use a default argument to enable programs with multiple IOLoops but not require the argument for simpler applications:

    > class MyClass(object):
    >   def __init__(self, io_loop=None):
    >     self.io_loop = io_loop or IOLoop.instance()

  `log_stack`(signal, frame)

    Signal handler to log the stack trace of the current thread.

    For use with set_blocking_signal_threshold.

  `remove_handler`(fd)

    Stop listening for events on fd.

  `remove_timeout`(timeout)
  `running`()

    Returns true if this IOLoop is currently running.

  `set_blocking_log_threshold`(seconds)

    Logs a stack trace if the ioloop is blocked for more than s seconds. Equivalent to set_blocking_signal_threshold(seconds, self.log_stack)

  `set_blocking_signal_threshold`(seconds, action)

    Sends a signal if the ioloop is blocked for more than s seconds.

    Pass seconds=None to disable. Requires python 2.6 on a unixy platform.

    The action parameter is a python signal handler. Read the documentation for the python ‘signal’ module for more information. If action is None, the process will be killed if it is blocked for too long.

  `start`()

    Starts the I/O loop.

    The loop will run until one of the I/O handlers calls stop(), which will make the loop stop after the current event iteration completes.

  `stop`()

    Stop the loop after the current event loop iteration is complete. If the event loop is not currently running, the next call to start() will return immediately.

    To use asynchronous methods from otherwise-synchronous code (such as unit tests), you can start and stop the event loop like this:

    > ioloop = IOLoop() async_method(ioloop=ioloop, callback=ioloop.stop) ioloop.start()

    ioloop.start() will return after async_method has run its callback, whether that callback was invoked before or after ioloop.start.

  `update_handler`(fd, events)

    Changes the events we listen for fd.

### `PeriodicCallback`

class `zmq.eventloop.ioloop.``PeriodicCallback`(callback, callback_time, io_loop=None)

  Bases: `object`

  Schedules the given callback to be called periodically.

  The callback is called every callback_time milliseconds.

  `start`()
  `stop`()

### Navigation

- index
- modules |
- next |
- previous |
- home|
- search|
- API »
- The PyZMQ API »