tornado.ioloop — Main event loop¶
- IOLoop objects¶

tornado.ioloop — Main event loop¶

An I/O event loop for non-blocking sockets.

Typical applications will use a single IOLoop object, in theIOLoop.instance singleton. The IOLoop.start method should usuallybe called at the end of the main() function. Atypical applications mayuse more than one IOLoop, such as one IOLoop per thread, or per unittestcase.

In addition to I/O events, the IOLoop can also schedule time-based events.IOLoop.add_timeout is a non-blocking alternative to time.sleep.

IOLoop objects¶

class tornado.ioloop.IOLoop[源代码]¶

A level-triggered I/O loop.

We use epoll (Linux) or kqueue (BSD and Mac OS X) if theyare available, or else we fall back on select(). If you areimplementing a system that needs to handle thousands ofsimultaneous connections, you should use a system that supportseither epoll or kqueue.

Example usage for a simple TCP server:

import errno
import functools
import tornado.ioloop
import socket

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

if name == '__main':
    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 = tornado.ioloop.IOLoop.current()
    callback = functools.partial(connection_ready, sock)
    io_loop.add_handler(sock.fileno(), callback, io_loop.READ)
    io_loop.start()

By default, a newly-constructed IOLoop becomes the thread’s currentIOLoop, unless there already is a current IOLoop. This behaviorcan be controlled with the make_current argument to the IOLoopconstructor: if make_current=True, the new IOLoop will alwaystry to become current and it raises an error if there is already acurrent instance. If make_current=False, the new IOLoop willnot try to become current.

在 4.2 版更改: Added the make_current keyword argument to the IOLoopconstructor.

Running an IOLoop¶

static IOLoop.current(instance=True)[源代码]¶: Returns the current thread’s IOLoop.

If an IOLoop is currently running or has been marked ascurrent by make_current, returns that instance. If there isno current IOLoop, returns IOLoop.instance() (i.e. themain thread’s IOLoop, creating one if necessary) if instanceis true.

In general you should use IOLoop.current as the default whenconstructing an asynchronous object, and use IOLoop.instancewhen you mean to communicate to the main thread from a differentone.

在 4.1 版更改: Added instance argument to control the fallback toIOLoop.instance().

IOLoop.makecurrent()[源代码]¶: Makes this the IOLoop for the current thread.

An IOLoop automatically becomes current for its threadwhen it is started, but it is sometimes useful to callmake_current explicitly before starting the IOLoop,so that code run at startup time can find the rightinstance.

在 4.1 版更改: An IOLoop created while there is no current IOLoopwill automatically become current.

_static IOLoop.instance()[源代码]¶: Returns a global IOLoop instance.

Most applications have a single, global IOLoop running on themain thread. Use this method to get this instance fromanother thread. In most other cases, it is better to use current()to get the current thread’s IOLoop.

static IOLoop.initialized()[源代码]¶: Returns true if the singleton instance has been created.

IOLoop.install()[源代码]¶: Installs this IOLoop object as the singleton instance.

This is normally not necessary as instance() will createan IOLoop on demand, but you may want to call install to usea custom subclass of IOLoop.

When using an IOLoop subclass, install must be called priorto creating any objects that implicitly create their ownIOLoop (e.g., tornado.httpclient.AsyncHTTPClient).

static IOLoop.clearinstance()[源代码]¶: Clear the global IOLoop instance.

4.0 新版功能.

IOLoop.start()[源代码]¶: Starts the I/O loop.

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

IOLoop.stop()[源代码]¶

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 asunit 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 runits callback, whether that callback was invoked before orafter ioloop.start.

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

IOLoop.run_sync(_func, timeout=None)[源代码]¶

Starts the IOLoop, runs the given function, and stops the loop.

The function must return either a yieldable object orNone. If the function returns a yieldable object, theIOLoop will run until the yieldable is resolved (andrun_sync() will return the yieldable’s result). If it raisesan exception, the IOLoop will stop and the exception will bere-raised to the caller.

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

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

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

if name == 'main':
    IOLoop.current().runsync(main)

在 4.3 版更改: Returning a non-None, non-yieldable value is now an error.

IOLoop.close(_all_fds=False)[源代码]¶: Closes the IOLoop, freeing any resources used.

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

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

An IOLoop must be completely stopped before it can be closed. Thismeans that IOLoop.stop() must be called _andIOLoop.start() mustbe allowed to return before attempting to call IOLoop.close().Therefore the call to close will usually appear just afterthe call to start rather than near the call to stop.

在 3.1 版更改: If the IOLoop implementation supports non-integer objectsfor “file descriptors”, those objects will have theirclose method when all_fds is true.

I/O events¶

IOLoop.addhandler(_fd, handler, events)[源代码]¶: Registers the given handler to receive the given events for fd.

The fd argument may either be an integer file descriptor ora file-like object with a fileno() method (and optionally aclose() method, which may be called when the IOLoop is shutdown).

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

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

在 4.0 版更改: Added the ability to pass file-like objects in addition toraw file descriptors.

IOLoop.updatehandler(_fd, events)[源代码]¶: Changes the events we listen for fd.

在 4.0 版更改: Added the ability to pass file-like objects in addition toraw file descriptors.

IOLoop.removehandler(_fd)[源代码]¶: Stop listening for events on fd.

在 4.0 版更改: Added the ability to pass file-like objects in addition toraw file descriptors.

Callbacks and timeouts¶

IOLoop.addcallback(_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 onlymethod in IOLoop that makes this thread-safety guarantee; allother interaction with the IOLoop must be done from thatIOLoop‘s thread. add_callback() may be used to transfercontrol from other threads to the IOLoop‘s thread.

To add a callback from a signal handler, seeadd_callback_from_signal.

IOLoop.addcallback_from_signal(_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 usedotherwise.

Callbacks added with this method will be run without anystack_context, to avoid picking up the context of the functionthat was interrupted by the signal.

IOLoop.addfuture(_future, callback)[源代码]¶: Schedules a callback on the IOLoop when the givenFuture is finished.

The callback is invoked with one argument, theFuture.

IOLoop.addtimeout(_deadline, callback, *args, **kwargs)[源代码]¶: Runs the callback at the time deadline from the I/O loop.

Returns an opaque handle that may be passed toremove_timeout to cancel.

deadline may be a number denoting a time (on the samescale as IOLoop.time, normally time.time), or adatetime.timedelta object for a deadline relative to thecurrent time. Since Tornado 4.0, call_later is a moreconvenient alternative for the relative case since it does notrequire 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 theIOLoop‘s thread, and then call add_timeout from there.

Subclasses of IOLoop must implement either add_timeout orcall_at; the default implementations of each will callthe other. call_at is usually easier to implement, butsubclasses that wish to maintain compatibility with Tornadoversions prior to 4.0 must use add_timeout instead.

在 4.0 版更改: Now passes through args and **kwargs to the callback.

IOLoop.callat(_when, callback, _args, kwargs)[源代码]¶: Runs the callback at the absolute time designated by when.

when must be a number using the same reference point asIOLoop.time.

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

See add_timeout for comments on thread-safety and subclassing.

4.0 新版功能.

IOLoop.call_later(_delay, callback, *args, _kwargs)[源代码]¶: Runs the callback after delay seconds have passed.

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

See add_timeout for comments on thread-safety and subclassing.

4.0 新版功能.

IOLoop.remove_timeout(_timeout)[源代码]¶: Cancels a pending timeout.

The argument is a handle as returned by add_timeout. It issafe to call remove_timeout even if the callback has alreadybeen run.

IOLoop.spawncallback(_callback, *args, **kwargs)[源代码]¶: Calls the given callback on the next IOLoop iteration.

Unlike all other callback-related methods on IOLoop,spawncallback does not associate the callback with its caller’sstack_context, so it is suitable for fire-and-forget callbacksthat should not interfere with the caller.

4.0 新版功能.

IOLoop.time()[源代码]¶: Returns the current time according to the IOLoop‘s clock.

The return value is a floating-point number relative to anunspecified 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 adatetime.timedelta should use this function to compute theappropriate time, so they can work no matter what time functionis chosen.

_class tornado.ioloop.PeriodicCallback(callback, callback_time, io_loop=None)[源代码]¶

Schedules the given callback to be called periodically.

The callback is called every callback_time milliseconds.Note that the timeout is given in milliseconds, while most othertime-related functions in Tornado use seconds.

If the callback runs for longer than callback_time milliseconds,subsequent invocations will be skipped to get back on schedule.

start must be called after the PeriodicCallback is created.

在 4.1 版更改: The io_loop argument is deprecated.

start()[源代码]¶: Starts the timer.

stop()[源代码]¶: Stops the timer.

is_running()[源代码]¶: Return True if this PeriodicCallback has been started.

4.1 新版功能.

Debugging and error handling¶

IOLoop.handlecallback_exception(_callback)[源代码]¶: This method is called whenever a callback run by the IOLoopthrows an exception.

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

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

IOLoop.setblocking_signal_threshold(_seconds, action)[源代码]¶: Sends a signal if the IOLoop is blocked for more thans seconds.

Pass seconds=None to disable. Requires Python 2.6 on a unixyplatform.

The action parameter is a Python signal handler. Read thedocumentation for the signal module for more information.If action is None, the process will be killed if it isblocked for too long.

IOLoop.setblocking_log_threshold(_seconds)[源代码]¶: Logs a stack trace if the IOLoop is blocked for more thans seconds.

Equivalent to setblocking_signal_threshold(seconds, self.log_stack)

IOLoop.log_stack(_signal, frame)[源代码]¶: Signal handler to log the stack trace of the current thread.

For use with set_blocking_signal_threshold.

Methods for subclasses¶

IOLoop.initialize(make_current=None)[源代码]¶

IOLoop.closefd(_fd)[源代码]¶: Utility method to close an fd.

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

This method is provided for use by IOLoop subclasses (inimplementations of IOLoop.close(allfds=True) and shouldnot generally be used by application code.

4.0 新版功能.

IOLoop.split_fd(_fd)[源代码]¶: Returns an (fd, obj) pair from an fd parameter.

We accept both raw file descriptors and file-like objects asinput to add_handler and related methods. When a file-likeobject is passed, we must retain the object itself so we canclose it correctly when the IOLoop shuts down, but thepoller interfaces favor file descriptors (they will acceptfile-like objects and call fileno() for you, but theyalways return the descriptor itself).

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

4.0 新版功能.

原文:

https://tornado-zh-cn.readthedocs.io/zh_CN/latest/ioloop.html