Public Member Functions | Static Public Member Functions | Static Public Attributes | Private Member Functions | Static Private Attributes
tornado.ioloop.IOLoop Class Reference
Inheritance diagram for tornado.ioloop.IOLoop:
Inheritance graph
[legend]

List of all members.

Public Member Functions

def add_callback
def add_callback_from_signal
def add_future
def add_handler
def add_timeout
def call_at
def call_later
def close
def close_fd
def configurable_base
def configurable_default
def handle_callback_exception
def initialize
def install
def log_stack
def make_current
def remove_handler
def remove_timeout
def run_sync
def set_blocking_log_threshold
def set_blocking_signal_threshold
def spawn_callback
def split_fd
def start
def stop
def time
def update_handler

Static Public Member Functions

def clear_current
def clear_instance
def current
def initialized
def instance

Static Public Attributes

 ERROR = _EPOLLERR|_EPOLLHUP
int NONE = 0
 READ = _EPOLLIN
 WRITE = _EPOLLOUT

Private Member Functions

def _run_callback
def _setup_logging

Static Private Attributes

tuple _current = threading.local()
int _EPOLLERR = 0x008
tuple _EPOLLET = (1 << 31)
int _EPOLLHUP = 0x010
int _EPOLLIN = 0x001
tuple _EPOLLONESHOT = (1 << 30)
int _EPOLLOUT = 0x004
int _EPOLLPRI = 0x002
int _EPOLLRDHUP = 0x2000
tuple _instance_lock = threading.Lock()

Detailed Description

A level-triggered I/O loop.

We use ``epoll`` (Linux) or ``kqueue`` (BSD and Mac OS X) if they
are available, or else we fall back on select(). If you are
implementing a system that needs to handle thousands of
simultaneous connections, you should use a system that supports
either ``epoll`` or ``kqueue``.

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()

Definition at line 70 of file ioloop.py.


Member Function Documentation

def tornado.ioloop.IOLoop._run_callback (   self,
  callback 
) [private]
Runs a callback with error handling.

For use in subclasses.

Definition at line 559 of file ioloop.py.

def tornado.ioloop.IOLoop._setup_logging (   self) [private]
The IOLoop catches and logs exceptions, so it's
important that log output be visible.  However, python's
default behavior for non-root loggers (prior to python
3.2) is to print an unhelpful "no handlers could be
found" message rather than the actual log entry, so we
must explicitly configure logging if we've made it this
far without anything.

This method should be called from start() in subclasses.

Definition at line 333 of file ioloop.py.

def tornado.ioloop.IOLoop.add_callback (   self,
  callback,
  args,
  kwargs 
)
Calls the given callback on the next I/O loop iteration.

It is safe to call this method from any thread at any time,
except from a signal handler.  Note that this is the **only**
method in `IOLoop` that makes this thread-safety guarantee; all
other interaction with the `IOLoop` must be done from that
`IOLoop`'s thread.  `add_callback()` may be used to transfer
control from other threads to the `IOLoop`'s thread.

To add a callback from a signal handler, see
`add_callback_from_signal`.

Reimplemented in tornado.ioloop.PollIOLoop, tornado.platform.twisted.TwistedIOLoop, and tornado.platform.asyncio.BaseAsyncIOLoop.

Definition at line 507 of file ioloop.py.

def tornado.ioloop.IOLoop.add_callback_from_signal (   self,
  callback,
  args,
  kwargs 
)
Calls the given callback on the next I/O loop iteration.

Safe for use from a Python signal handler; should not be used
otherwise.

Callbacks added with this method will be run without any
`.stack_context`, to avoid picking up the context of the function
that was interrupted by the signal.

Reimplemented in tornado.ioloop.PollIOLoop, and tornado.platform.twisted.TwistedIOLoop.

Definition at line 522 of file ioloop.py.

def tornado.ioloop.IOLoop.add_future (   self,
  future,
  callback 
)
Schedules a callback on the ``IOLoop`` when the given
`.Future` is finished.

The callback is invoked with one argument, the
`.Future`.

Definition at line 547 of file ioloop.py.

def tornado.ioloop.IOLoop.add_handler (   self,
  fd,
  handler,
  events 
)
Registers the given handler to receive the given events for ``fd``.

The ``fd`` argument may either be an integer file descriptor or
a file-like object with a ``fileno()`` method (and optionally a
``close()`` method, which may be called when the `IOLoop` is shut
down).

The ``events`` argument is a bitwise or of the constants
``IOLoop.READ``, ``IOLoop.WRITE``, and ``IOLoop.ERROR``.

When an event occurs, ``handler(fd, events)`` will be run.

.. versionchanged:: 4.0
   Added the ability to pass file-like objects in addition to
   raw file descriptors.

Reimplemented in tornado.ioloop.PollIOLoop, tornado.platform.twisted.TwistedIOLoop, and tornado.platform.asyncio.BaseAsyncIOLoop.

Definition at line 256 of file ioloop.py.

def tornado.ioloop.IOLoop.add_timeout (   self,
  deadline,
  callback,
  args,
  kwargs 
)
Runs the ``callback`` at the time ``deadline`` from the I/O loop.

Returns an opaque handle that may be passed to
`remove_timeout` to cancel.

``deadline`` may be a number denoting a time (on the same
scale as `IOLoop.time`, normally `time.time`), or a
`datetime.timedelta` object for a deadline relative to the
current time.  Since Tornado 4.0, `call_later` is a more
convenient alternative for the relative case since it does not
require a timedelta object.

Note that it is not safe to call `add_timeout` from other threads.
Instead, you must use `add_callback` to transfer control to the
`IOLoop`'s thread, and then call `add_timeout` from there.

Subclasses of IOLoop must implement either `add_timeout` or
`call_at`; the default implementations of each will call
the other.  `call_at` is usually easier to implement, but
subclasses that wish to maintain compatibility with Tornado
versions prior to 4.0 must use `add_timeout` instead.

.. versionchanged:: 4.0
   Now passes through ``*args`` and ``**kwargs`` to the callback.

Reimplemented in tornado.platform.twisted.TwistedIOLoop.

Definition at line 435 of file ioloop.py.

def tornado.ioloop.IOLoop.call_at (   self,
  when,
  callback,
  args,
  kwargs 
)
Runs the ``callback`` at the absolute time designated by ``when``.

``when`` must be a number using the same reference point as
`IOLoop.time`.

Returns an opaque handle that may be passed to `remove_timeout`
to cancel.  Note that unlike the `asyncio` method of the same
name, the returned object does not have a ``cancel()`` method.

See `add_timeout` for comments on thread-safety and subclassing.

.. versionadded:: 4.0

Reimplemented in tornado.ioloop.PollIOLoop, and tornado.platform.asyncio.BaseAsyncIOLoop.

Definition at line 482 of file ioloop.py.

def tornado.ioloop.IOLoop.call_later (   self,
  delay,
  callback,
  args,
  kwargs 
)
Runs the ``callback`` after ``delay`` seconds have passed.

Returns an opaque handle that may be passed to `remove_timeout`
to cancel.  Note that unlike the `asyncio` method of the same
name, the returned object does not have a ``cancel()`` method.

See `add_timeout` for comments on thread-safety and subclassing.

.. versionadded:: 4.0

Definition at line 469 of file ioloop.py.

Definition at line 207 of file ioloop.py.

Clear the global `IOLoop` instance.

.. versionadded:: 4.0

Definition at line 161 of file ioloop.py.

def tornado.ioloop.IOLoop.close (   self,
  all_fds = False 
)
Closes the `IOLoop`, freeing any resources used.

If ``all_fds`` is true, all file descriptors registered on the
IOLoop will be closed (not just the ones created by the
`IOLoop` itself).

Many applications will only use a single `IOLoop` that runs for the
entire lifetime of the process.  In that case closing the `IOLoop`
is not necessary since everything will be cleaned up when the
process exits.  `IOLoop.close` is provided mainly for scenarios
such as unit tests, which create and destroy a large number of
``IOLoops``.

An `IOLoop` must be completely stopped before it can be closed.  This
means that `IOLoop.stop()` must be called *and* `IOLoop.start()` must
be allowed to return before attempting to call `IOLoop.close()`.
Therefore the call to `close` will usually appear just after
the call to `start` rather than near the call to `stop`.

.. versionchanged:: 3.1
   If the `IOLoop` implementation supports non-integer objects
   for "file descriptors", those objects will have their
   ``close`` method when ``all_fds`` is true.

Reimplemented in tornado.ioloop.PollIOLoop, tornado.platform.twisted.TwistedIOLoop, and tornado.platform.asyncio.BaseAsyncIOLoop.

Definition at line 229 of file ioloop.py.

def tornado.ioloop.IOLoop.close_fd (   self,
  fd 
)
Utility method to close an ``fd``.

If ``fd`` is a file-like object, we close it directly; otherwise
we use `os.close`.

This method is provided for use by `IOLoop` subclasses (in
implementations of ``IOLoop.close(all_fds=True)`` and should
not generally be used by application code.

.. versionadded:: 4.0

Definition at line 608 of file ioloop.py.

Returns the base class of a configurable hierarchy.

This will normally return the class in which it is defined.
(which is *not* necessarily the same as the cls classmethod parameter).

Reimplemented from tornado.util.Configurable.

Definition at line 211 of file ioloop.py.

Returns the implementation class to be used if none is configured.

Reimplemented from tornado.util.Configurable.

Definition at line 215 of file ioloop.py.

Returns the current thread's `IOLoop`.

If an `IOLoop` is currently running or has been marked as current
by `make_current`, returns that instance.  Otherwise returns
`IOLoop.instance()`, i.e. the main thread's `IOLoop`.

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.current()

In general you should use `IOLoop.current` as the default when
constructing an asynchronous object, and use `IOLoop.instance`
when you mean to communicate to the main thread from a different
one.

Definition at line 170 of file ioloop.py.

def tornado.ioloop.IOLoop.handle_callback_exception (   self,
  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`.

Definition at line 575 of file ioloop.py.

Initialize a `Configurable` subclass instance.

Configurable classes should use `initialize` instead of ``__init__``.

Reimplemented from tornado.util.Configurable.

Reimplemented in tornado.platform.asyncio.AsyncIOLoop, and tornado.platform.asyncio.AsyncIOMainLoop.

Definition at line 226 of file ioloop.py.

Returns true if the singleton instance has been created.

Definition at line 146 of file ioloop.py.

Installs this `IOLoop` object as the singleton instance.

This is normally not necessary as `instance()` will create
an `IOLoop` on demand, but you may want to call `install` to use
a custom subclass of `IOLoop`.

Definition at line 150 of file ioloop.py.

Returns a global `IOLoop` instance.

Most applications have a single, global `IOLoop` running on the
main thread.  Use this method to get this instance from
another thread.  To get the current thread's `IOLoop`, use `current()`.

Definition at line 131 of file ioloop.py.

def tornado.ioloop.IOLoop.log_stack (   self,
  signal,
  frame 
)
Signal handler to log the stack trace of the current thread.

For use with `set_blocking_signal_threshold`.

Definition at line 316 of file ioloop.py.

Makes this the `IOLoop` for the current thread.

An `IOLoop` automatically becomes current for its thread
when it is started, but it is sometimes useful to call
`make_current` explictly before starting the `IOLoop`,
so that code run at startup time can find the right
instance.

Definition at line 195 of file ioloop.py.

def tornado.ioloop.IOLoop.remove_handler (   self,
  fd 
)
Stop listening for events on ``fd``.

.. versionchanged:: 4.0
   Added the ability to pass file-like objects in addition to
   raw file descriptors.

Reimplemented in tornado.ioloop.PollIOLoop, tornado.platform.twisted.TwistedIOLoop, and tornado.platform.asyncio.BaseAsyncIOLoop.

Definition at line 284 of file ioloop.py.

def tornado.ioloop.IOLoop.remove_timeout (   self,
  timeout 
)
Cancels a pending timeout.

The argument is a handle as returned by `add_timeout`.  It is
safe to call `remove_timeout` even if the callback has already
been run.

Reimplemented in tornado.ioloop.PollIOLoop, tornado.platform.twisted.TwistedIOLoop, and tornado.platform.asyncio.BaseAsyncIOLoop.

Definition at line 498 of file ioloop.py.

def tornado.ioloop.IOLoop.run_sync (   self,
  func,
  timeout = None 
)
Starts the `IOLoop`, runs the given function, and stops the loop.

If the function returns a `.Future`, the `IOLoop` will run
until the future is resolved.  If it raises an exception, the
`IOLoop` will stop and the exception will be re-raised to the
caller.

The keyword-only argument ``timeout`` may be used to set
a maximum duration for the function.  If the timeout expires,
a `TimeoutError` is raised.

This method is useful in conjunction with `tornado.gen.coroutine`
to allow asynchronous calls in a ``main()`` function::

    @gen.coroutine
    def main():
# do stuff...

    if __name__ == '__main__':
IOLoop.instance().run_sync(main)

Definition at line 373 of file ioloop.py.

def tornado.ioloop.IOLoop.set_blocking_log_threshold (   self,
  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)``

Definition at line 307 of file ioloop.py.

def tornado.ioloop.IOLoop.set_blocking_signal_threshold (   self,
  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 `signal` module for more information.
If ``action`` is None, the process will be killed if it is
blocked for too long.

Reimplemented in tornado.ioloop.PollIOLoop.

Definition at line 293 of file ioloop.py.

def tornado.ioloop.IOLoop.spawn_callback (   self,
  callback,
  args,
  kwargs 
)
Calls the given callback on the next IOLoop iteration.

Unlike all other callback-related methods on IOLoop,
``spawn_callback`` does not associate the callback with its caller's
``stack_context``, so it is suitable for fire-and-forget callbacks
that should not interfere with the caller.

.. versionadded:: 4.0

Definition at line 534 of file ioloop.py.

def tornado.ioloop.IOLoop.split_fd (   self,
  fd 
)
Returns an (fd, obj) pair from an ``fd`` parameter.

We accept both raw file descriptors and file-like objects as
input to `add_handler` and related methods.  When a file-like
object is passed, we must retain the object itself so we can
close it correctly when the `IOLoop` shuts down, but the
poller interfaces favor file descriptors (they will accept
file-like objects and call ``fileno()`` for you, but they
always return the descriptor itself).

This method is provided for use by `IOLoop` subclasses and should
not generally be used by application code.

.. versionadded:: 4.0

Definition at line 587 of file ioloop.py.

Starts the I/O loop.

The loop will run until one of the callbacks calls `stop()`, which
will make the loop stop after the current event iteration completes.

Reimplemented in tornado.ioloop.PollIOLoop, tornado.platform.twisted.TwistedIOLoop, and tornado.platform.asyncio.BaseAsyncIOLoop.

Definition at line 325 of file ioloop.py.

Stop the I/O loop.

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``.

Note that even after `stop` has been called, the `IOLoop` is not
completely stopped until `IOLoop.start` has also returned.
Some work that was scheduled before the call to `stop` may still
be run before the `IOLoop` shuts down.

Reimplemented in tornado.ioloop.PollIOLoop, tornado.platform.twisted.TwistedIOLoop, and tornado.platform.asyncio.BaseAsyncIOLoop.

Definition at line 349 of file ioloop.py.

Returns the current time according to the `IOLoop`'s clock.

The return value is a floating-point number relative to an
unspecified time in the past.

By default, the `IOLoop`'s time function is `time.time`.  However,
it may be configured to use e.g. `time.monotonic` instead.
Calls to `add_timeout` that pass a number instead of a
`datetime.timedelta` should use this function to compute the
appropriate time, so they can work no matter what time function
is chosen.

Reimplemented in tornado.ioloop.PollIOLoop.

Definition at line 420 of file ioloop.py.

def tornado.ioloop.IOLoop.update_handler (   self,
  fd,
  events 
)
Changes the events we listen for ``fd``.

.. versionchanged:: 4.0
   Added the ability to pass file-like objects in addition to
   raw file descriptors.

Reimplemented in tornado.ioloop.PollIOLoop, tornado.platform.twisted.TwistedIOLoop, and tornado.platform.asyncio.BaseAsyncIOLoop.

Definition at line 275 of file ioloop.py.


Member Data Documentation

tuple tornado::ioloop.IOLoop::_current = threading.local() [static, private]

Definition at line 128 of file ioloop.py.

int tornado::ioloop.IOLoop::_EPOLLERR = 0x008 [static, private]

Definition at line 113 of file ioloop.py.

tuple tornado::ioloop.IOLoop::_EPOLLET = (1 << 31) [static, private]

Definition at line 117 of file ioloop.py.

int tornado::ioloop.IOLoop::_EPOLLHUP = 0x010 [static, private]

Definition at line 114 of file ioloop.py.

int tornado::ioloop.IOLoop::_EPOLLIN = 0x001 [static, private]

Definition at line 110 of file ioloop.py.

tuple tornado::ioloop.IOLoop::_EPOLLONESHOT = (1 << 30) [static, private]

Definition at line 116 of file ioloop.py.

int tornado::ioloop.IOLoop::_EPOLLOUT = 0x004 [static, private]

Definition at line 112 of file ioloop.py.

int tornado::ioloop.IOLoop::_EPOLLPRI = 0x002 [static, private]

Definition at line 111 of file ioloop.py.

int tornado::ioloop.IOLoop::_EPOLLRDHUP = 0x2000 [static, private]

Definition at line 115 of file ioloop.py.

tuple tornado::ioloop.IOLoop::_instance_lock = threading.Lock() [static, private]

Definition at line 126 of file ioloop.py.

Definition at line 123 of file ioloop.py.

int tornado::ioloop.IOLoop::NONE = 0 [static]

Definition at line 120 of file ioloop.py.

Definition at line 121 of file ioloop.py.

Definition at line 122 of file ioloop.py.


The documentation for this class was generated from the following file:


rosbridge_server
Author(s): Jonathan Mace
autogenerated on Wed Sep 13 2017 03:18:20