U d@sTdZddlZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl mZddlmZmZmZmZmZddlmZddlmZmZmZddlZddlmZmZmZmZm Z m!Z!m"Z"m#Z#ej$rddlm%Z%m&Z&dd l'm(Z(ne)Z(Gd d d e(Z*e!d Z+e!d e*dZ,GdddeZ-Gddde)Z.Gddde)Z/dS)aAn I/O event loop for non-blocking sockets. In Tornado 6.0, `.IOLoop` is a wrapper around the `asyncio` event loop, with a slightly different interface. The `.IOLoop` interface is now provided primarily for backwards compatibility; new code should generally use the `asyncio` event loop interface directly. The `IOLoop.current` class method provides the `IOLoop` instance corresponding to the running `asyncio` event loop. N) isawaitable)Future is_future chain_futurefuture_set_exc_infofuture_add_done_callback)app_log) Configurable TimeoutError import_object)UnionAnyTypeOptionalCallableTypeVarTuple Awaitable)DictList)Protocolc@s(eZdZedddZddddZdS) _SelectablereturncCsdSNselfrr2/tmp/pip-unpacked-wheel-fekwu36z/tornado/ioloop.pyfileno=sz_Selectable.filenoNcCsdSrrrrrrclose@sz_Selectable.close)__name__ __module__ __qualname__intrr rrrrr<sr_T_S)boundcseZdZdZdZdZdZdZeZ e de ddfd d Z e dd d d Zdd ddZe dd ddZeje dd ddZeje dieeddddZe djeeddddZdd ddZe dd ddZe dd ddZdd ddZe eed d d!Ze eed d"d#Zdkeedd$d%d&Zdledd(d)d*Zeje e!e e gdfe dd+d,d-Z"eje#e!e#e gdfe dd+d.d-Z"e$e e%fe!d/e dd+d0d-Z"e$e e%fe dd1d2d3Z&e$e e%fdd4d5d6Z'dd d7d8Z(dd d9d:Z)dme!ee*e d;dd?Z,e$e*e-j.fe!e e e/d@dAdBZ0e*e!e e e/dCdDdEZ1e*e!e e e/dFdGdHZ2e/ddIdJdKZ3e!e e ddLdMdNZ4e!e e ddLdOdPZ5e!e e ddLdQdRZ6dSe!dTgdfddUdVdWZ7ee8j9j:e!dXe;fe ee!ge fdd_d`daZ?e@ddbdcddZAe$e e%feBe e$e e%ffd4dedfZCe$e e%fdd4dgdhZDZES)nIOLoopa An I/O event loop. As of Tornado 6.0, `IOLoop` is a wrapper around the `asyncio` event loop. Example usage for a simple TCP server: .. testcode:: import asyncio import errno import functools import socket import tornado.ioloop from tornado.iostream import IOStream async def handle_connection(connection, address): stream = IOStream(connection) message = await stream.read_until_close() print("message from client:", message.decode().strip()) def connection_ready(sock, fd, events): while True: try: connection, address = sock.accept() except BlockingIOError: return connection.setblocking(0) io_loop = tornado.ioloop.IOLoop.current() io_loop.spawn_callback(handle_connection, connection, address) async def 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(("", 8888)) 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) await asyncio.Event().wait() if __name__ == "__main__": asyncio.run(main()) .. testoutput:: :hide: Most applications should not attempt to construct an `IOLoop` directly, and instead initialize the `asyncio` event loop and use `IOLoop.current()`. In some cases, such as in test frameworks when initializing an `IOLoop` to be run in a secondary thread, it may be appropriate to construct an `IOLoop` with ``IOLoop(make_current=False)``. Constructing an `IOLoop` without the ``make_current=False`` argument is deprecated since Tornado 6.2. In general, an `IOLoop` cannot survive a fork or be shared across processes in any way. When multiple processes are being used, each process should create its own `IOLoop`, which also implies that any objects which depend on the `IOLoop` (such as `.AsyncHTTPClient`) must also be created in the child processes. As a guideline, anything that starts processes (including the `tornado.process` and `multiprocessing` modules) should do so as early as possible, ideally the first thing the application does after loading its configuration, and *before* any calls to `.IOLoop.start` or `asyncio.run`. .. versionchanged:: 4.2 Added the ``make_current`` keyword argument to the `IOLoop` constructor. .. versionchanged:: 5.0 Uses the `asyncio` event loop by default. The ``IOLoop.configure`` method cannot be used on Python 3 except to redundantly specify the `asyncio` event loop. .. deprecated:: 6.2 It is deprecated to create an event loop that is "current" but not running. This means it is deprecated to pass ``make_current=True`` to the ``IOLoop`` constructor, or to create an ``IOLoop`` while no asyncio event loop is running unless ``make_current=False`` is used. rz$Union[None, str, Type[Configurable]]N)implkwargsrc sRddlm}t|trt|}t|tr:t||s:tdtt |j |f|dS)Nr)BaseAsyncIOLoopz5only AsyncIOLoop is allowed when asyncio is available) tornado.platform.asyncior. isinstancestrr type issubclass RuntimeErrorsuperr( configure)clsr,r-r. __class__rrr6s   zIOLoop.configurercCstS)aKDeprecated alias for `IOLoop.current()`. .. versionchanged:: 5.0 Previously, this method returned a global singleton `IOLoop`, in contrast with the per-thread `IOLoop` returned by `current()`. In nearly all cases the two were the same (when they differed, it was generally used from non-Tornado threads to communicate back to the main thread's `IOLoop`). This distinction is not present in `asyncio`, so in order to facilitate integration with that package `instance()` was changed to be an alias to `current()`. Applications using the cross-thread communications aspect of `instance()` should instead set their own global variable to point to the `IOLoop` they want to use. .. deprecated:: 5.0 )r(currentrrrrinstanceszIOLoop.instancecCs |dS)a`Deprecated alias for `make_current()`. .. versionchanged:: 5.0 Previously, this method would set this `IOLoop` as the global singleton used by `IOLoop.instance()`. Now that `instance()` is an alias for `current()`, `install()` is an alias for `make_current()`. .. deprecated:: 5.0 N make_currentrrrrinstalls zIOLoop.installcCs tdS)akDeprecated alias for `clear_current()`. .. versionchanged:: 5.0 Previously, this method would clear the `IOLoop` used as the global singleton by `IOLoop.instance()`. Now that `instance()` is an alias for `current()`, `clear_instance()` is an alias for `clear_current()`. .. deprecated:: 5.0 N)r( clear_currentrrrrclear_instanceszIOLoop.clear_instancecCsdSrrrrrrr:szIOLoop.currentT)r;rcCsdSrrr;rrrr:sc Csxz t}Wn$ttfk r0|s*YdSYnXz tj|WStk rr|rjddlm}|dd}nd}YnX|S)aCReturns the current thread's `IOLoop`. If an `IOLoop` is currently running or has been marked as current by `make_current`, returns that instance. If there is no current `IOLoop` and ``instance`` is true, creates one. .. versionchanged:: 4.1 Added ``instance`` argument to control the fallback to `IOLoop.instance()`. .. versionchanged:: 5.0 On Python 3, control of the current `IOLoop` is delegated to `asyncio`, with this and other methods as pass-through accessors. The ``instance`` argument now controls whether an `IOLoop` is created automatically when there is none, instead of whether we fall back to `IOLoop.instance()` (which is now an alias for this method). ``instance=False`` is deprecated, since even if we do not create an `IOLoop`, this method may initialize the asyncio loop. .. deprecated:: 6.2 It is deprecated to call ``IOLoop.current()`` when no `asyncio` event loop is running. Nr)AsyncIOMainLoopTr<) asyncioZget_event_loopr4AssertionErrorr(_ioloop_for_asyncioKeyErrorr/rB)r;ZlooprBr:rrrr:s     cCs tdS)aMakes 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` explicitly before starting the `IOLoop`, so that code run at startup time can find the right instance. .. versionchanged:: 4.1 An `IOLoop` created while there is no current `IOLoop` will automatically become current. .. versionchanged:: 5.0 This method also sets the current `asyncio` event loop. .. deprecated:: 6.2 The concept of an event loop that is "current" without currently running is deprecated in asyncio since Python 3.10. All related functionality in Tornado is also deprecated. Instead, start the event loop with `asyncio.run` before interacting with it. NNotImplementedErrorrrrrr=szIOLoop.make_currentcCstjdtddtdS)zClears the `IOLoop` for the current thread. Intended primarily for use by test frameworks in between tests. .. versionchanged:: 5.0 This method also clears the current `asyncio` event loop. .. deprecated:: 6.2 zclear_current is deprecated) stacklevelN)warningswarnDeprecationWarningr(_clear_currentrrrrr?3s zIOLoop.clear_currentcCs tjdd}|dk r|dS)NFrA)r(r:_clear_current_hook)oldrrrrNDs zIOLoop._clear_currentcCsdS)zInstance method called when an IOLoop ceases to be current. May be overridden by subclasses as a counterpart to make_current. NrrrrrrOJszIOLoop._clear_current_hookcCstSr)r()r7rrrconfigurable_baseQszIOLoop.configurable_basecCsddlm}|S)Nr) AsyncIOLoop)r/rR)r7rRrrrconfigurable_defaultUs zIOLoop.configurable_default)r=rcCsV|dkr"tjdddkrR|n0|rRtjdd}|dk rJ||k rJtd|dS)NFrAzcurrent IOLoop already exists)r(r:r=r4)rr=r:rrr initialize[s  zIOLoop.initializeF)all_fdsrcCs tdS)aCloses 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. NrG)rrUrrrr fsz IOLoop.close)fdhandlereventsrcCsdSrrrrVrWrXrrr add_handlerszIOLoop.add_handlercCsdSrrrYrrrrZs).NcCs tdS)a+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()`` and ``close()`` method. 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. NrGrYrrrrZs)rVrXrcCs tdS)zChanges the events we listen for ``fd``. .. versionchanged:: 4.0 Added the ability to pass file-like objects in addition to raw file descriptors. NrG)rrVrXrrrupdate_handlerszIOLoop.update_handler)rVrcCs tdS)zStop listening for events on ``fd``. .. versionchanged:: 4.0 Added the ability to pass file-like objects in addition to raw file descriptors. NrGrrVrrrremove_handlerszIOLoop.remove_handlercCs tdS)zStarts 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. NrGrrrrstartsz IOLoop.startcCs tdS)aStop the I/O loop. If the event loop is not currently running, the next call to `start()` will return immediately. 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. NrGrrrrstops z IOLoop.stop)functimeoutrcsdgddfdd }||dk rVddfdd }||}|dk rp|ddk stdsdstd|d S) aStarts the `IOLoop`, runs the given function, and stops the loop. The function must return either an awaitable object or ``None``. If the function returns an awaitable object, the `IOLoop` will run until the awaitable is resolved (and `run_sync()` will return the awaitable's result). 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 `asyncio.TimeoutError` is raised. This method is useful to allow asynchronous calls in a ``main()`` function:: async def main(): # do stuff... if __name__ == '__main__': IOLoop.current().run_sync(main) .. versionchanged:: 4.3 Returning a non-``None``, non-awaitable value is now an error. .. versionchanged:: 5.0 If a timeout occurs, the ``func`` coroutine will be cancelled. .. versionchanged:: 6.2 ``tornado.util.TimeoutError`` is now an alias to ``asyncio.TimeoutError``. Nrcsz&}|dk r$ddlm}||}Wn0tk rVt}|d<t|tYn,Xt|rj|d<nt}|d<||ddk st  dfdddS)Nr)convert_yieldedcsSr)r_)futurerrrz.IOLoop.run_sync..run..) Z tornado.genrb Exceptionrrsysexc_inforZ set_resultrD add_future)resultrbZfutr` future_cellrrrruns     zIOLoop.run_sync..runcs(ddk stds$dS)Nr)rDcancelr_r)rlrrrtimeout_callbacks z)IOLoop.run_sync..timeout_callbackrz$Operation timed out after %s seconds) add_callback add_timeouttimer^remove_timeoutrDZ cancelleddoner rj)rr`rarmroZtimeout_handlerrkrrun_syncs     zIOLoop.run_synccCstS)aReturns 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. Historically, the IOLoop could be customized to use e.g. `time.monotonic` instead of `time.time`, but this is not currently supported and so this method is equivalent to `time.time`. )rrrrrrrrs z IOLoop.time)deadlinecallbackargsr-rcOs\t|tjr |j||f||St|tjrL|j|||f||Std|dS)aRuns 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. Unsupported deadline %rN) r0numbersRealcall_atdatetime timedeltarr total_seconds TypeError)rrvrwrxr-rrrrq!s  zIOLoop.add_timeout)delayrwrxr-rcOs|j|||f||S)aRuns 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 )r|rr)rrrwrxr-rrr call_laterJs zIOLoop.call_later)whenrwrxr-rcOs|j||f||S)aRuns 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 )rq)rrrwrxr-rrrr|YszIOLoop.call_at)rarcCs tdS)zCancels 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. NrG)rrarrrrskszIOLoop.remove_timeout)rwrxr-rcOs tdS)a3Calls 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`. NrGrrwrxr-rrrrpts zIOLoop.add_callbackcOs tdS)zCalls the given callback on the next I/O loop iteration. Safe for use from a Python signal handler; should not be used otherwise. NrGrrrradd_callback_from_signalszIOLoop.add_callback_from_signalcOs|j|f||dS)zCalls the given callback on the next IOLoop iteration. As of Tornado 6.0, this method is equivalent to `add_callback`. .. versionadded:: 4.0 Nrprrrrspawn_callbackszIOLoop.spawn_callbackz0Union[Future[_T], concurrent.futures.Future[_T]]z Future[_T])rcrwrcsHttr"fddn"ts.ttfdddS)aASchedules a callback on the ``IOLoop`` when the given `.Future` is finished. The callback is invoked with one argument, the `.Future`. This method only accepts `.Future` objects and not other awaitables (unlike most of Tornado where the two are interchangeable). cstSr) _run_callback functoolspartialfrwrcrrrrdrez#IOLoop.add_future..cs SrrrrrrrdreN)r0rZadd_done_callbackrrDr)rrcrwrrrris  zIOLoop.add_future.)executorr`rxrcsh|dkr:t|ds4ddlm}tjj|dd|_|j}|j|f|}t| |fddS) zRuns a function in a ``concurrent.futures.Executor``. If ``executor`` is ``None``, the IO loop's default executor will be used. Use `functools.partial` to pass keyword arguments to ``func``. .. versionadded:: 5.0 N _executorr) cpu_count) max_workerscs t|Sr)rrZt_futurerrrdrez(IOLoop.run_in_executor..) hasattrZtornado.processr concurrentfuturesZThreadPoolExecutorrZsubmitrri)rrr`rxrZc_futurerrrrun_in_executors   zIOLoop.run_in_executor)rrcCs ||_dS)zfSets the default executor to use with :meth:`run_in_executor`. .. versionadded:: 5.0 N)r)rrrrrset_default_executorszIOLoop.set_default_executor)rwrcCszR|}|dk rPddlm}z||}Wn|jk r@YnX|||jWn8tjk rhYn$tk rt j d|ddYnXdS)zRuns a callback with error handling. .. versionchanged:: 6.0 CancelledErrors are no longer logged. Nr)genException in callback %rTrh) ZtornadorrbZ BadYieldErrorri_discard_future_resultrCZCancelledErrorrfrerror)rrwretrrrrrs zIOLoop._run_callback)rcrcCs |dS)z;Avoid unhandled-exception warnings from spawned coroutines.N)rj)rrcrrrrszIOLoop._discard_future_resultcCst|tr||fS||fSr)r0r$rr\rrrsplit_fds zIOLoop.split_fdcCs<z"t|trt|n|Wntk r6YnXdSr)r0r$osr OSErrorr\rrrclose_fds    zIOLoop.close_fd)T)T)N)F)N)Fr!r"r#__doc__NONEREADWRITEERRORdictrE classmethodr r6 staticmethodr;r>r@typingoverloadr:boolrr=r?rNrOrr rQrSrTr r$rrZr&r rr[r]r^r_floatrurrr}r~objectrqrr|rsrprrrirrZExecutorr%rrrrrrrrr __classcell__rrr8rr(HsT )      L  *       %     r(c@sVeZdZdZdddgZeegdfeddddZde d d d Z de d d d Z dS)_Timeoutz2An IOLoop timeout, a UNIX timestamp and a callbackrvrw tdeadlineN)rvrwio_looprcCs8t|tjstd|||_||_|t|jf|_dS)Nry) r0rzr{rrvrwnextZ_timeout_counterr)rrvrwrrrr__init__/s  z_Timeout.__init__)otherrcCs |j|jkSrrrrrrr__lt__?sz_Timeout.__lt__cCs |j|jkSrrrrrr__le__Bsz_Timeout.__le__) r!r"r#r __slots__rrr(rrrrrrrrr)s   rc@seZdZdZdegeefeej e fe ddddZ dddd Z ddd d Z edd d ZddddZddddZe ddddZdS)PeriodicCallbackaSchedules the given callback to be called periodically. The callback is called every ``callback_time`` milliseconds when ``callback_time`` is a float. Note that the timeout is given in milliseconds, while most other time-related functions in Tornado use seconds. ``callback_time`` may alternatively be given as a `datetime.timedelta` object. If ``jitter`` is specified, each callback time will be randomly selected within a window of ``jitter * callback_time`` milliseconds. Jitter can be used to reduce alignment of events with similar periods. A jitter of 0.1 means allowing a 10% variation in callback time. The window is centered on ``callback_time`` so the total number of calls within a given interval should not be significantly affected by adding jitter. 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. .. versionchanged:: 5.0 The ``io_loop`` argument (deprecated since version 4.1) has been removed. .. versionchanged:: 5.1 The ``jitter`` argument is added. .. versionchanged:: 6.2 If the ``callback`` argument is a coroutine, and a callback runs for longer than ``callback_time``, subsequent invocations will be skipped. Previously this was only true for regular functions, not coroutines, which were "fire-and-forget" for `PeriodicCallback`. The ``callback_time`` argument now accepts `datetime.timedelta` objects, in addition to the previous numeric milliseconds. rN)rw callback_timejitterrcCsR||_t|tjr&|tjdd|_n|dkr6td||_||_d|_d|_dS)Nr))Z millisecondsrz4Periodic callback must have a positive callback_timeF) rwr0r}r~r ValueErrorr_running_timeout)rrwrrrrrrls zPeriodicCallback.__init__rcCs(t|_d|_|j|_|dS)zStarts the timer.TN)r(r:rrrr _next_timeout_schedule_nextrrrrr^}s  zPeriodicCallback.startcCs(d|_|jdk r$|j|jd|_dS)zStops the timer.FN)rrrrsrrrrr_s zPeriodicCallback.stopcCs|jS)zfReturns ``True`` if this `.PeriodicCallback` has been started. .. versionadded:: 4.1 )rrrrr is_runningszPeriodicCallback.is_runningcsl|js dSzRz&|}|dk r0t|r0|IdHWn&tk rXtjd|jddYnXW5|XdS)NrTr)rrrwrrfrr)rvalrrr_runszPeriodicCallback._runcCs.|jr*||j|j|j|j|_dSr)r _update_nextrrrrqrrrrrrrrszPeriodicCallback._schedule_next) current_timercCsn|jd}|jr*|d|jtd9}|j|kr\|jt||j|d|7_n|j|7_dS)Ng@@r)g?)rrrandomrmathfloor)rrZcallback_time_secrrrrs   zPeriodicCallback._update_next)r)r!r"r#rrrrr r}r~rrr^r_rrrrrrrrrrFs)    r)0rrCconcurrent.futuresrr}rrzrrgrrrrrKinspectrZtornado.concurrentrrrrrZ tornado.logrZ tornado.utilr r r rr r rrrrrr TYPE_CHECKINGrrZtyping_extensionsrrrr%r&r(rrrrrrs@   ( f