asyncio-eventloop.rst 32.7 KB
Newer Older
1
.. currentmodule:: asyncio
2

3
.. _asyncio-event-loop:
4

5 6
Base Event Loop
===============
7

8 9
**Source code:** :source:`Lib/asyncio/events.py`

10
The event loop is the central execution device provided by :mod:`asyncio`.
11
It provides multiple facilities, including:
12

13
* Registering, executing and cancelling delayed calls (timeouts).
14

15
* Creating client and server :ref:`transports <asyncio-transport>` for various
16
  kinds of communication.
17

18 19
* Launching subprocesses and the associated :ref:`transports
  <asyncio-transport>` for communication with an external program.
20

21
* Delegating costly function calls to a pool of threads.
22

23
.. class:: BaseEventLoop
24

25 26 27 28 29 30 31 32 33 34
   This class is an implementation detail.  It is a subclass of
   :class:`AbstractEventLoop` and may be a base class of concrete
   event loop implementations found in :mod:`asyncio`.  It should not
   be used directly; use :class:`AbstractEventLoop` instead.
   ``BaseEventLoop`` should not be subclassed by third-party code; the
   internal interface is not stable.

.. class:: AbstractEventLoop

   Abstract base class of event loops.
35

36 37
   This class is :ref:`not thread safe <asyncio-multithreading>`.

38 39 40
Run an event loop
-----------------

41
.. method:: AbstractEventLoop.run_forever()
42

43 44 45 46 47 48 49 50 51
   Run until :meth:`stop` is called.  If :meth:`stop` is called before
   :meth:`run_forever()` is called, this polls the I/O selector once
   with a timeout of zero, runs all callbacks scheduled in response to
   I/O events (and those that were already scheduled), and then exits.
   If :meth:`stop` is called while :meth:`run_forever` is running,
   this will run the current batch of callbacks and then exit.  Note
   that callbacks scheduled by callbacks will not run in that case;
   they will run the next time :meth:`run_forever` is called.

52
   .. versionchanged:: 3.5.1
53

54
.. method:: AbstractEventLoop.run_until_complete(future)
55

56
   Run until the :class:`Future` is done.
57

58
   If the argument is a :ref:`coroutine object <coroutine>`, it is wrapped by
59
   :func:`ensure_future`.
60 61 62

   Return the Future's result, or raise its exception.

63
.. method:: AbstractEventLoop.is_running()
64 65 66

   Returns running status of event loop.

67
.. method:: AbstractEventLoop.stop()
68 69 70

   Stop running the event loop.

71 72 73
   This causes :meth:`run_forever` to exit at the next suitable
   opportunity (see there for more details).

74
   .. versionchanged:: 3.5.1
75

76
.. method:: AbstractEventLoop.is_closed()
77 78 79 80 81

   Returns ``True`` if the event loop was closed.

   .. versionadded:: 3.4.2

82
.. method:: AbstractEventLoop.close()
83

84 85
   Close the event loop. The loop must not be running.  Pending
   callbacks will be lost.
86 87 88 89 90 91 92

   This clears the queues and shuts down the executor, but does not wait for
   the executor to finish.

   This is idempotent and irreversible. No other methods should be called after
   this one.

93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110

.. coroutinemethod:: AbstractEventLoop.shutdown_asyncgens()

   Schedule all currently open :term:`asynchronous generator` objects to
   close with an :meth:`~agen.aclose()` call.  After calling this method,
   the event loop will issue a warning whenever a new asynchronous generator
   is iterated.  Should be used to finalize all scheduled asynchronous
   generators reliably.  Example::

    try:
        loop.run_forever()
    finally:
        loop.run_until_complete(loop.shutdown_asyncgens())
        loop.close()

   .. versionadded:: 3.6


111
.. _asyncio-pass-keywords:
112 113 114 115

Calls
-----

116 117 118 119 120 121 122 123 124 125 126
Most :mod:`asyncio` functions don't accept keywords. If you want to pass
keywords to your callback, use :func:`functools.partial`. For example,
``loop.call_soon(functools.partial(print, "Hello", flush=True))`` will call
``print("Hello", flush=True)``.

.. note::
   :func:`functools.partial` is better than ``lambda`` functions, because
   :mod:`asyncio` can inspect :func:`functools.partial` object to display
   parameters in debug mode, whereas ``lambda`` functions have a poor
   representation.

127
.. method:: AbstractEventLoop.call_soon(callback, \*args)
128

129 130 131
   Arrange for a callback to be called as soon as possible.  The callback is
   called after :meth:`call_soon` returns, when control returns to the event
   loop.
132

133 134 135
   This operates as a :abbr:`FIFO (first-in, first-out)` queue, callbacks
   are called in the order in which they are registered.  Each callback
   will be called exactly once.
136 137 138 139

   Any positional arguments after the callback will be passed to the
   callback when it is called.

140 141
   An instance of :class:`asyncio.Handle` is returned, which can be
   used to cancel the callback.
142

143 144 145
   :ref:`Use functools.partial to pass keywords to the callback
   <asyncio-pass-keywords>`.

146
.. method:: AbstractEventLoop.call_soon_threadsafe(callback, \*args)
147 148 149

   Like :meth:`call_soon`, but thread safe.

150 151 152
   See the :ref:`concurrency and multithreading <asyncio-multithreading>`
   section of the documentation.

153

154 155
.. _asyncio-delayed-calls:

156 157 158 159 160 161 162 163
Delayed calls
-------------

The event loop has its own internal clock for computing timeouts.
Which clock is used depends on the (platform-specific) event loop
implementation; ideally it is a monotonic clock.  This will generally be
a different clock than :func:`time.time`.

164 165 166 167
.. note::

   Timeouts (relative *delay* or absolute *when*) should not exceed one day.

168

169
.. method:: AbstractEventLoop.call_later(delay, callback, *args)
170 171 172 173

   Arrange for the *callback* to be called after the given *delay*
   seconds (either an int or float).

174 175
   An instance of :class:`asyncio.Handle` is returned, which can be
   used to cancel the callback.
176 177 178 179 180 181 182 183 184

   *callback* will be called exactly once per call to :meth:`call_later`.
   If two callbacks are scheduled for exactly the same time, it is
   undefined which will be called first.

   The optional positional *args* will be passed to the callback when it
   is called. If you want the callback to be called with some named
   arguments, use a closure or :func:`functools.partial`.

185 186 187
   :ref:`Use functools.partial to pass keywords to the callback
   <asyncio-pass-keywords>`.

188
.. method:: AbstractEventLoop.call_at(when, callback, *args)
189 190

   Arrange for the *callback* to be called at the given absolute timestamp
191
   *when* (an int or float), using the same time reference as
192
   :meth:`AbstractEventLoop.time`.
193 194 195

   This method's behavior is the same as :meth:`call_later`.

196 197 198
   An instance of :class:`asyncio.Handle` is returned, which can be
   used to cancel the callback.

199 200 201
   :ref:`Use functools.partial to pass keywords to the callback
   <asyncio-pass-keywords>`.

202
.. method:: AbstractEventLoop.time()
203 204 205 206

   Return the current time, as a :class:`float` value, according to the
   event loop's internal clock.

207 208 209 210
.. seealso::

   The :func:`asyncio.sleep` function.

211

212 213 214
Futures
-------

215
.. method:: AbstractEventLoop.create_future()
216 217 218 219 220 221 222 223 224 225

   Create an :class:`asyncio.Future` object attached to the loop.

   This is a preferred way to create futures in asyncio, as event
   loop implementations can provide alternative implementations
   of the Future class (with better performance or instrumentation).

   .. versionadded:: 3.5.2


226 227
Tasks
-----
228

229
.. method:: AbstractEventLoop.create_task(coro)
230 231 232 233 234 235 236 237

   Schedule the execution of a :ref:`coroutine object <coroutine>`: wrap it in
   a future. Return a :class:`Task` object.

   Third-party event loops can use their own subclass of :class:`Task` for
   interoperability. In this case, the result type is a subclass of
   :class:`Task`.

238 239
   This method was added in Python 3.4.2. Use the :func:`async` function to
   support also older Python versions.
240 241 242

   .. versionadded:: 3.4.2

243
.. method:: AbstractEventLoop.set_task_factory(factory)
244 245

   Set a task factory that will be used by
246
   :meth:`AbstractEventLoop.create_task`.
247 248 249 250 251 252 253 254 255 256

   If *factory* is ``None`` the default task factory will be set.

   If *factory* is a *callable*, it should have a signature matching
   ``(loop, coro)``, where *loop* will be a reference to the active
   event loop, *coro* will be a coroutine object.  The callable
   must return an :class:`asyncio.Future` compatible object.

   .. versionadded:: 3.4.4

257
.. method:: AbstractEventLoop.get_task_factory()
258 259 260 261 262

   Return a task factory, or ``None`` if the default one is in use.

   .. versionadded:: 3.4.4

263

264
Creating connections
265
--------------------
266

267
.. coroutinemethod:: AbstractEventLoop.create_connection(protocol_factory, host=None, port=None, \*, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None)
268 269

   Create a streaming transport connection to a given Internet *host* and
270 271 272 273
   *port*: socket family :py:data:`~socket.AF_INET` or
   :py:data:`~socket.AF_INET6` depending on *host* (or *family* if specified),
   socket type :py:data:`~socket.SOCK_STREAM`.  *protocol_factory* must be a
   callable returning a :ref:`protocol <asyncio-protocol>` instance.
274

275
   This method is a :ref:`coroutine <coroutine>` which will try to
276 277 278 279 280
   establish the connection in the background.  When successful, the
   coroutine returns a ``(transport, protocol)`` pair.

   The chronological synopsis of the underlying operation is as follows:

281
   #. The connection is established, and a :ref:`transport <asyncio-transport>`
282 283 284
      is created to represent it.

   #. *protocol_factory* is called without arguments and must return a
285
      :ref:`protocol <asyncio-protocol>` instance.
286 287 288 289 290 291 292 293 294 295 296 297 298 299

   #. The protocol instance is tied to the transport, and its
      :meth:`connection_made` method is called.

   #. The coroutine returns successfully with the ``(transport, protocol)``
      pair.

   The created transport is an implementation-dependent bidirectional stream.

   .. note::
      *protocol_factory* can be any kind of callable, not necessarily
      a class.  For example, if you want to use a pre-created
      protocol instance, you can pass ``lambda: my_protocol``.

300
   Options that change how the connection is created:
301 302 303 304 305 306 307

   * *ssl*: if given and not false, a SSL/TLS transport is created
     (by default a plain TCP transport is created).  If *ssl* is
     a :class:`ssl.SSLContext` object, this context is used to create
     the transport; if *ssl* is :const:`True`, a context with some
     unspecified default settings is used.

Berker Peksag's avatar
Berker Peksag committed
308
     .. seealso:: :ref:`SSL/TLS security considerations <ssl-security>`
309

310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331
   * *server_hostname*, is only for use together with *ssl*,
     and sets or overrides the hostname that the target server's certificate
     will be matched against.  By default the value of the *host* argument
     is used.  If *host* is empty, there is no default and you must pass a
     value for *server_hostname*.  If *server_hostname* is an empty
     string, hostname matching is disabled (which is a serious security
     risk, allowing for man-in-the-middle-attacks).

   * *family*, *proto*, *flags* are the optional address family, protocol
     and flags to be passed through to getaddrinfo() for *host* resolution.
     If given, these should all be integers from the corresponding
     :mod:`socket` module constants.

   * *sock*, if given, should be an existing, already connected
     :class:`socket.socket` object to be used by the transport.
     If *sock* is given, none of *host*, *port*, *family*, *proto*, *flags*
     and *local_addr* should be specified.

   * *local_addr*, if given, is a ``(local_host, local_port)`` tuple used
     to bind the socket to locally.  The *local_host* and *local_port*
     are looked up using getaddrinfo(), similarly to *host* and *port*.

332 333 334
   .. versionchanged:: 3.5

      On Windows with :class:`ProactorEventLoop`, SSL/TLS is now supported.
335

336 337 338 339 340
   .. seealso::

      The :func:`open_connection` function can be used to get a pair of
      (:class:`StreamReader`, :class:`StreamWriter`) instead of a protocol.

341

342
.. coroutinemethod:: AbstractEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0, reuse_address=None, reuse_port=None, allow_broadcast=None, sock=None)
343 344 345

   Create datagram connection: socket family :py:data:`~socket.AF_INET` or
   :py:data:`~socket.AF_INET6` depending on *host* (or *family* if specified),
346 347
   socket type :py:data:`~socket.SOCK_DGRAM`. *protocol_factory* must be a
   callable returning a :ref:`protocol <asyncio-protocol>` instance.
348

349
   This method is a :ref:`coroutine <coroutine>` which will try to
350 351 352
   establish the connection in the background.  When successful, the
   coroutine returns a ``(transport, protocol)`` pair.

353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369
   Options changing how the connection is created:

   * *local_addr*, if given, is a ``(local_host, local_port)`` tuple used
     to bind the socket to locally.  The *local_host* and *local_port*
     are looked up using :meth:`getaddrinfo`.

   * *remote_addr*, if given, is a ``(remote_host, remote_port)`` tuple used
     to connect the socket to a remote address.  The *remote_host* and
     *remote_port* are looked up using :meth:`getaddrinfo`.

   * *family*, *proto*, *flags* are the optional address family, protocol
     and flags to be passed through to :meth:`getaddrinfo` for *host*
     resolution. If given, these should all be integers from the
     corresponding :mod:`socket` module constants.

   * *reuse_address* tells the kernel to reuse a local socket in
     TIME_WAIT state, without waiting for its natural timeout to
370
     expire. If not specified will automatically be set to ``True`` on
371 372 373 374 375 376 377 378 379 380 381 382 383 384 385
     UNIX.

   * *reuse_port* tells the kernel to allow this endpoint to be bound to the
     same port as other existing endpoints are bound to, so long as they all
     set this flag when being created. This option is not supported on Windows
     and some UNIX's. If the :py:data:`~socket.SO_REUSEPORT` constant is not
     defined then this capability is unsupported.

   * *allow_broadcast* tells the kernel to allow this endpoint to send
     messages to the broadcast address.

   * *sock* can optionally be specified in order to use a preexisting,
     already connected, :class:`socket.socket` object to be used by the
     transport. If specified, *local_addr* and *remote_addr* should be omitted
     (must be :const:`None`).
386

387 388
   On Windows with :class:`ProactorEventLoop`, this method is not supported.

389 390 391
   See :ref:`UDP echo client protocol <asyncio-udp-echo-client-protocol>` and
   :ref:`UDP echo server protocol <asyncio-udp-echo-server-protocol>` examples.

392

393
.. coroutinemethod:: AbstractEventLoop.create_unix_connection(protocol_factory, path, \*, ssl=None, sock=None, server_hostname=None)
394 395 396 397 398 399

   Create UNIX connection: socket family :py:data:`~socket.AF_UNIX`, socket
   type :py:data:`~socket.SOCK_STREAM`. The :py:data:`~socket.AF_UNIX` socket
   family is used to communicate between processes on the same machine
   efficiently.

400
   This method is a :ref:`coroutine <coroutine>` which will try to
401 402 403
   establish the connection in the background.  When successful, the
   coroutine returns a ``(transport, protocol)`` pair.

404 405 406 407
   *path* is the name of a UNIX domain socket, and is required unless a *sock*
   parameter is specified.  Abstract UNIX sockets, :class:`str`, and
   :class:`bytes` paths are supported.

408
   See the :meth:`AbstractEventLoop.create_connection` method for parameters.
409 410 411 412

   Availability: UNIX.


413 414 415
Creating listening connections
------------------------------

416
.. coroutinemethod:: AbstractEventLoop.create_server(protocol_factory, host=None, port=None, \*, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None)
417

418 419
   Create a TCP server (socket type :data:`~socket.SOCK_STREAM`) bound to
   *host* and *port*.
420

421 422 423
   Return a :class:`Server` object, its :attr:`~Server.sockets` attribute
   contains created sockets. Use the :meth:`Server.close` method to stop the
   server: close listening sockets.
424

425
   Parameters:
426

427 428 429 430 431 432
   * The *host* parameter can be a string, in that case the TCP server is
     bound to *host* and *port*. The *host* parameter can also be a sequence
     of strings and in that case the TCP server is bound to all hosts of the
     sequence. If *host* is an empty string or ``None``, all interfaces are
     assumed and a list of multiple sockets will be returned (most likely one
     for IPv4 and another one for IPv6).
433

434 435 436
   * *family* can be set to either :data:`socket.AF_INET` or
     :data:`~socket.AF_INET6` to force the socket to use IPv4 or IPv6. If not set
     it will be determined from host (defaults to :data:`socket.AF_UNSPEC`).
437

438
   * *flags* is a bitmask for :meth:`getaddrinfo`.
439

440 441 442
   * *sock* can optionally be specified in order to use a preexisting
     socket object. If specified, *host* and *port* should be omitted (must be
     :const:`None`).
443

444 445
   * *backlog* is the maximum number of queued connections passed to
     :meth:`~socket.socket.listen` (defaults to 100).
446

447 448 449 450 451
   * *ssl* can be set to an :class:`~ssl.SSLContext` to enable SSL over the
     accepted connections.

   * *reuse_address* tells the kernel to reuse a local socket in
     TIME_WAIT state, without waiting for its natural timeout to
452
     expire. If not specified will automatically be set to ``True`` on
453 454
     UNIX.

455 456 457 458 459
   * *reuse_port* tells the kernel to allow this endpoint to be bound to the
     same port as other existing endpoints are bound to, so long as they all
     set this flag when being created. This option is not supported on
     Windows.

460
   This method is a :ref:`coroutine <coroutine>`.
461

462 463 464
   .. versionchanged:: 3.5

      On Windows with :class:`ProactorEventLoop`, SSL/TLS is now supported.
465

466 467 468 469 470
   .. seealso::

      The function :func:`start_server` creates a (:class:`StreamReader`,
      :class:`StreamWriter`) pair and calls back a function with this pair.

Victor Stinner's avatar
Victor Stinner committed
471
   .. versionchanged:: 3.5.1
472 473 474

      The *host* parameter can now be a sequence of strings.

475

476
.. coroutinemethod:: AbstractEventLoop.create_unix_server(protocol_factory, path=None, \*, sock=None, backlog=100, ssl=None)
477

478
   Similar to :meth:`AbstractEventLoop.create_server`, but specific to the
479 480
   socket family :py:data:`~socket.AF_UNIX`.

481 482
   This method is a :ref:`coroutine <coroutine>`.

483
   Availability: UNIX.
484

485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501
.. coroutinemethod:: BaseEventLoop.connect_accepted_socket(protocol_factory, sock, \*, ssl=None)

   Handle an accepted connection.

   This is used by servers that accept connections outside of
   asyncio but that use asyncio to handle them.

   Parameters:

   * *sock* is a preexisting socket object returned from an ``accept``
     call.

   * *ssl* can be set to an :class:`~ssl.SSLContext` to enable SSL over the
     accepted connections.

   This method is a :ref:`coroutine <coroutine>`.  When completed, the
   coroutine returns a ``(transport, protocol)`` pair.
502

503 504 505
Watch file descriptors
----------------------

506 507 508 509 510
On Windows with :class:`SelectorEventLoop`, only socket handles are supported
(ex: pipe file descriptors are not supported).

On Windows with :class:`ProactorEventLoop`, these methods are not supported.

511
.. method:: AbstractEventLoop.add_reader(fd, callback, \*args)
512 513 514 515

   Start watching the file descriptor for read availability and then call the
   *callback* with specified arguments.

516 517 518
   :ref:`Use functools.partial to pass keywords to the callback
   <asyncio-pass-keywords>`.

519
.. method:: AbstractEventLoop.remove_reader(fd)
520 521 522

   Stop watching the file descriptor for read availability.

523
.. method:: AbstractEventLoop.add_writer(fd, callback, \*args)
524 525 526 527

   Start watching the file descriptor for write availability and then call the
   *callback* with specified arguments.

528 529 530
   :ref:`Use functools.partial to pass keywords to the callback
   <asyncio-pass-keywords>`.

531
.. method:: AbstractEventLoop.remove_writer(fd)
532 533 534

   Stop watching the file descriptor for write availability.

535
The :ref:`watch a file descriptor for read events <asyncio-watch-read-event>`
536
example uses the low-level :meth:`AbstractEventLoop.add_reader` method to register
537 538
the file descriptor of a socket.

539 540 541 542

Low-level socket operations
---------------------------

543
.. coroutinemethod:: AbstractEventLoop.sock_recv(sock, nbytes)
544

545 546 547 548
   Receive data from the socket.  Modeled after blocking
   :meth:`socket.socket.recv` method.

   The return value is a bytes object
549 550 551
   representing the data received.  The maximum amount of data to be received
   at once is specified by *nbytes*.

552 553
   With :class:`SelectorEventLoop` event loop, the socket *sock* must be
   non-blocking.
554

555
   This method is a :ref:`coroutine <coroutine>`.
556

557
.. coroutinemethod:: AbstractEventLoop.sock_sendall(sock, data)
558

559 560 561 562
   Send data to the socket.  Modeled after blocking
   :meth:`socket.socket.sendall` method.

   The socket must be connected to a remote socket.
563 564 565
   This method continues to send data from *data* until either all data has
   been sent or an error occurs.  ``None`` is returned on success.  On error,
   an exception is raised, and there is no way to determine how much data, if
566
   any, was successfully processed by the receiving end of the connection.
567

568 569
   With :class:`SelectorEventLoop` event loop, the socket *sock* must be
   non-blocking.
570

571
   This method is a :ref:`coroutine <coroutine>`.
572

573
.. coroutinemethod:: AbstractEventLoop.sock_connect(sock, address)
574

575 576
   Connect to a remote socket at *address*.  Modeled after
   blocking :meth:`socket.socket.connect` method.
577

578 579
   With :class:`SelectorEventLoop` event loop, the socket *sock* must be
   non-blocking.
580

581
   This method is a :ref:`coroutine <coroutine>`.
582

583 584 585 586
   .. versionchanged:: 3.5.2
      ``address`` no longer needs to be resolved.  ``sock_connect``
      will try to check if the *address* is already resolved by calling
      :func:`socket.inet_pton`.  If not,
587
      :meth:`AbstractEventLoop.getaddrinfo` will be used to resolve the
588 589
      *address*.

590 591
   .. seealso::

592
      :meth:`AbstractEventLoop.create_connection`
593
      and  :func:`asyncio.open_connection() <open_connection>`.
594 595


596
.. coroutinemethod:: AbstractEventLoop.sock_accept(sock)
597

598 599 600 601
   Accept a connection.  Modeled after blocking
   :meth:`socket.socket.accept`.

   The socket must be bound to an address and listening
602 603 604 605 606
   for connections. The return value is a pair ``(conn, address)`` where *conn*
   is a *new* socket object usable to send and receive data on the connection,
   and *address* is the address bound to the socket on the other end of the
   connection.

607 608
   The socket *sock* must be non-blocking.

609
   This method is a :ref:`coroutine <coroutine>`.
610 611 612

   .. seealso::

613
      :meth:`AbstractEventLoop.create_server` and :func:`start_server`.
614 615 616 617


Resolve host name
-----------------
618

619
.. coroutinemethod:: AbstractEventLoop.getaddrinfo(host, port, \*, family=0, type=0, proto=0, flags=0)
620

621 622
   This method is a :ref:`coroutine <coroutine>`, similar to
   :meth:`socket.getaddrinfo` function but non-blocking.
623

624
.. coroutinemethod:: AbstractEventLoop.getnameinfo(sockaddr, flags=0)
625

626 627
   This method is a :ref:`coroutine <coroutine>`, similar to
   :meth:`socket.getnameinfo` function but non-blocking.
628 629


630 631
Connect pipes
-------------
632

633 634 635
On Windows with :class:`SelectorEventLoop`, these methods are not supported.
Use :class:`ProactorEventLoop` to support pipes on Windows.

636
.. coroutinemethod:: AbstractEventLoop.connect_read_pipe(protocol_factory, pipe)
637

638
   Register read pipe in eventloop.
639 640

   *protocol_factory* should instantiate object with :class:`Protocol`
641 642
   interface.  *pipe* is a :term:`file-like object <file object>`.
   Return pair ``(transport, protocol)``, where *transport* supports the
643 644
   :class:`ReadTransport` interface.

645 646 647
   With :class:`SelectorEventLoop` event loop, the *pipe* is set to
   non-blocking mode.

648
   This method is a :ref:`coroutine <coroutine>`.
649

650
.. coroutinemethod:: AbstractEventLoop.connect_write_pipe(protocol_factory, pipe)
651 652 653 654

   Register write pipe in eventloop.

   *protocol_factory* should instantiate object with :class:`BaseProtocol`
655 656
   interface. *pipe* is :term:`file-like object <file object>`.
   Return pair ``(transport, protocol)``, where *transport* supports
657 658
   :class:`WriteTransport` interface.

659 660 661
   With :class:`SelectorEventLoop` event loop, the *pipe* is set to
   non-blocking mode.

662
   This method is a :ref:`coroutine <coroutine>`.
663

664 665
.. seealso::

666 667
   The :meth:`AbstractEventLoop.subprocess_exec` and
   :meth:`AbstractEventLoop.subprocess_shell` methods.
668

669

670 671 672 673 674
UNIX signals
------------

Availability: UNIX only.

675
.. method:: AbstractEventLoop.add_signal_handler(signum, callback, \*args)
676 677 678 679 680 681

   Add a handler for a signal.

   Raise :exc:`ValueError` if the signal number is invalid or uncatchable.
   Raise :exc:`RuntimeError` if there is a problem setting up the handler.

682 683 684
   :ref:`Use functools.partial to pass keywords to the callback
   <asyncio-pass-keywords>`.

685
.. method:: AbstractEventLoop.remove_signal_handler(sig)
686 687 688 689 690 691 692 693 694 695

   Remove a handler for a signal.

   Return ``True`` if a signal handler was removed, ``False`` if not.

.. seealso::

   The :mod:`signal` module.


696 697 698 699 700 701 702
Executor
--------

Call a function in an :class:`~concurrent.futures.Executor` (pool of threads or
pool of processes). By default, an event loop uses a thread pool executor
(:class:`~concurrent.futures.ThreadPoolExecutor`).

703
.. coroutinemethod:: AbstractEventLoop.run_in_executor(executor, func, \*args)
704

705
   Arrange for a *func* to be called in the specified executor.
706

707 708
   The *executor* argument should be an :class:`~concurrent.futures.Executor`
   instance. The default executor is used if *executor* is ``None``.
709

710
   :ref:`Use functools.partial to pass keywords to the *func*
711 712
   <asyncio-pass-keywords>`.

713 714
   This method is a :ref:`coroutine <coroutine>`.

715 716 717 718 719 720 721
   .. versionchanged:: 3.5.3
      :meth:`BaseEventLoop.run_in_executor` no longer configures the
      ``max_workers`` of the thread pool executor it creates, instead
      leaving it up to the thread pool executor
      (:class:`~concurrent.futures.ThreadPoolExecutor`) to set the
      default.

722
.. method:: AbstractEventLoop.set_default_executor(executor)
723 724 725 726

   Set the default executor used by :meth:`run_in_executor`.


727 728 729
Error Handling API
------------------

730
Allows customizing how exceptions are handled in the event loop.
731

732
.. method:: AbstractEventLoop.set_exception_handler(handler)
733 734 735 736 737 738 739 740 741 742 743 744

   Set *handler* as the new event loop exception handler.

   If *handler* is ``None``, the default exception handler will
   be set.

   If *handler* is a callable object, it should have a
   matching signature to ``(loop, context)``, where ``loop``
   will be a reference to the active event loop, ``context``
   will be a ``dict`` object (see :meth:`call_exception_handler`
   documentation for details about context).

745
.. method:: AbstractEventLoop.get_exception_handler()
746 747 748 749 750 751

   Return the exception handler, or ``None`` if the default one
   is in use.

   .. versionadded:: 3.5.2

752
.. method:: AbstractEventLoop.default_exception_handler(context)
753 754 755 756 757 758 759 760 761 762

   Default exception handler.

   This is called when an exception occurs and no exception
   handler is set, and can be called by a custom exception
   handler that wants to defer to the default behavior.

   *context* parameter has the same meaning as in
   :meth:`call_exception_handler`.

763
.. method:: AbstractEventLoop.call_exception_handler(context)
764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783

   Call the current event loop exception handler.

   *context* is a ``dict`` object containing the following keys
   (new keys may be introduced later):

   * 'message': Error message;
   * 'exception' (optional): Exception object;
   * 'future' (optional): :class:`asyncio.Future` instance;
   * 'handle' (optional): :class:`asyncio.Handle` instance;
   * 'protocol' (optional): :ref:`Protocol <asyncio-protocol>` instance;
   * 'transport' (optional): :ref:`Transport <asyncio-transport>` instance;
   * 'socket' (optional): :class:`socket.socket` instance.

   .. note::

       Note: this method should not be overloaded in subclassed
       event loops.  For any custom exception handling, use
       :meth:`set_exception_handler()` method.

784 785 786
Debug mode
----------

787
.. method:: AbstractEventLoop.get_debug()
788

789 790 791 792 793
   Get the debug mode (:class:`bool`) of the event loop.

   The default value is ``True`` if the environment variable
   :envvar:`PYTHONASYNCIODEBUG` is set to a non-empty string, ``False``
   otherwise.
794

795 796
   .. versionadded:: 3.4.2

797
.. method:: AbstractEventLoop.set_debug(enabled: bool)
798 799 800

   Set the debug mode of the event loop.

801 802
   .. versionadded:: 3.4.2

803 804
.. seealso::

805
   The :ref:`debug mode of asyncio <asyncio-debug-mode>`.
806

807 808 809
Server
------

810
.. class:: Server
811

812 813
   Server listening on sockets.

814
   Object created by the :meth:`AbstractEventLoop.create_server` method and the
R David Murray's avatar
R David Murray committed
815
   :func:`start_server` function. Don't instantiate the class directly.
816 817 818

   .. method:: close()

819 820 821
      Stop serving: close listening sockets and set the :attr:`sockets`
      attribute to ``None``.

822 823
      The sockets that represent existing incoming client connections are left
      open.
824

825 826
      The server is closed asynchronously, use the :meth:`wait_closed`
      coroutine to wait until the server is closed.
827

828
   .. coroutinemethod:: wait_closed()
829

830 831 832 833 834 835 836 837
      Wait until the :meth:`close` method completes.

      This method is a :ref:`coroutine <coroutine>`.

   .. attribute:: sockets

      List of :class:`socket.socket` objects the server is listening to, or
      ``None`` if the server is closed.
838 839


840 841 842 843 844
Handle
------

.. class:: Handle

845 846 847
   A callback wrapper object returned by :func:`AbstractEventLoop.call_soon`,
   :func:`AbstractEventLoop.call_soon_threadsafe`, :func:`AbstractEventLoop.call_later`,
   and :func:`AbstractEventLoop.call_at`.
848 849 850

   .. method:: cancel()

851 852
      Cancel the call.  If the callback is already canceled or executed,
      this method has no effect.
853

854

855
Event loop examples
856
-------------------
857

858
.. _asyncio-hello-world-callback:
859

860
Hello World with call_soon()
861
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
862

863
Example using the :meth:`AbstractEventLoop.call_soon` method to schedule a
864 865
callback. The callback displays ``"Hello World"`` and then stops the event
loop::
866 867 868

    import asyncio

869
    def hello_world(loop):
870
        print('Hello World')
871
        loop.stop()
872 873

    loop = asyncio.get_event_loop()
874 875 876 877 878 879 880

    # Schedule a call to hello_world()
    loop.call_soon(hello_world, loop)

    # Blocking call interrupted by loop.stop()
    loop.run_forever()
    loop.close()
881

882
.. seealso::
883

884 885
   The :ref:`Hello World coroutine <asyncio-hello-world-coroutine>` example
   uses a :ref:`coroutine <coroutine>`.
886

887

888 889 890
.. _asyncio-date-callback:

Display the current date with call_later()
891
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
892 893

Example of callback displaying the current date every second. The callback uses
894
the :meth:`AbstractEventLoop.call_later` method to reschedule itself during 5
895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923
seconds, and then stops the event loop::

    import asyncio
    import datetime

    def display_date(end_time, loop):
        print(datetime.datetime.now())
        if (loop.time() + 1.0) < end_time:
            loop.call_later(1, display_date, end_time, loop)
        else:
            loop.stop()

    loop = asyncio.get_event_loop()

    # Schedule the first call to display_date()
    end_time = loop.time() + 5.0
    loop.call_soon(display_date, end_time, loop)

    # Blocking call interrupted by loop.stop()
    loop.run_forever()
    loop.close()

.. seealso::

   The :ref:`coroutine displaying the current date
   <asyncio-date-coroutine>` example uses a :ref:`coroutine
   <coroutine>`.


924 925 926
.. _asyncio-watch-read-event:

Watch a file descriptor for read events
927
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
928 929

Wait until a file descriptor received some data using the
930
:meth:`AbstractEventLoop.add_reader` method and then close the event loop::
931 932

    import asyncio
933 934 935 936
    try:
        from socket import socketpair
    except ImportError:
        from asyncio.windows_utils import socketpair
937 938

    # Create a pair of connected file descriptors
939
    rsock, wsock = socketpair()
940 941 942 943 944
    loop = asyncio.get_event_loop()

    def reader():
        data = rsock.recv(100)
        print("Received:", data.decode())
945
        # We are done: unregister the file descriptor
946 947 948 949
        loop.remove_reader(rsock)
        # Stop the event loop
        loop.stop()

950
    # Register the file descriptor for read event
951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967
    loop.add_reader(rsock, reader)

    # Simulate the reception of data from the network
    loop.call_soon(wsock.send, 'abc'.encode())

    # Run the event loop
    loop.run_forever()

    # We are done, close sockets and the event loop
    rsock.close()
    wsock.close()
    loop.close()

.. seealso::

   The :ref:`register an open socket to wait for data using a protocol
   <asyncio-register-socket>` example uses a low-level protocol created by the
968
   :meth:`AbstractEventLoop.create_connection` method.
969 970 971 972 973

   The :ref:`register an open socket to wait for data using streams
   <asyncio-register-socket-streams>` example uses high-level streams
   created by the :func:`open_connection` function in a coroutine.

974

975
Set signal handlers for SIGINT and SIGTERM
976
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
977 978

Register handlers for signals :py:data:`SIGINT` and :py:data:`SIGTERM` using
979
the :meth:`AbstractEventLoop.add_signal_handler` method::
980 981 982 983 984 985 986 987 988 989 990 991 992 993 994

    import asyncio
    import functools
    import os
    import signal

    def ask_exit(signame):
        print("got signal %s: exit" % signame)
        loop.stop()

    loop = asyncio.get_event_loop()
    for signame in ('SIGINT', 'SIGTERM'):
        loop.add_signal_handler(getattr(signal, signame),
                                functools.partial(ask_exit, signame))

995
    print("Event loop running forever, press Ctrl+C to interrupt.")
996
    print("pid %s: send SIGINT or SIGTERM to exit." % os.getpid())
997 998 999 1000
    try:
        loop.run_forever()
    finally:
        loop.close()
1001 1002

This example only works on UNIX.