 |
 |
| Python 3.6.5 Documentation > Base Event Loop
Base Event Loop **Source code:** Lib/asyncio/events.py The event loop is the central execution device provided by "asyncio". * Registering, executing and cancelling delayed calls (timeouts). * Creating client and server transports for various kinds of * Launching subprocesses and the associated transports for * Delegating costly function calls to a pool of threads. class asyncio.BaseEventLoop This class is an implementation detail. It is a subclass of class asyncio.AbstractEventLoop Abstract base class of event loops. This class is not thread safe.
AbstractEventLoop.run_forever() Run until "stop()" is called. If "stop()" is called before Changed in version 3.5.1. AbstractEventLoop.run_until_complete(future) Run until the "Future" is done. If the argument is a coroutine object, it is wrapped by Return the Future’s result, or raise its exception. AbstractEventLoop.is_running() Returns running status of event loop. AbstractEventLoop.stop() Stop running the event loop. This causes "run_forever()" to exit at the next suitable Changed in version 3.5.1. AbstractEventLoop.is_closed() Returns "True" if the event loop was closed. New in version 3.4.2. AbstractEventLoop.close() Close the event loop. The loop must not be running. Pending This clears the queues and shuts down the executor, but does not This is idempotent and irreversible. No other methods should be coroutine AbstractEventLoop.shutdown_asyncgens() Schedule all currently open *asynchronous generator* objects to try: New in version 3.6.
Most "asyncio" functions don’t accept keywords. If you want to pass Note: "functools.partial()" is better than "lambda" functions, AbstractEventLoop.call_soon(callback, *args) Arrange for a callback to be called as soon as possible. The This operates as a FIFO (first-in, first-out) queue, callbacks are Any positional arguments after the callback will be passed to the An instance of "asyncio.Handle" is returned, which can be used to Use functools.partial to pass keywords to the callback. AbstractEventLoop.call_soon_threadsafe(callback, *args) Like "call_soon()", but thread safe. See the concurrency and multithreading section of the
The event loop has its own internal clock for computing timeouts. Note: Timeouts (relative *delay* or absolute *when*) should not AbstractEventLoop.call_later(delay, callback, *args) Arrange for the *callback* to be called after the given *delay* An instance of "asyncio.Handle" is returned, which can be used to *callback* will be called exactly once per call to "call_later()". The optional positional *args* will be passed to the callback when Use functools.partial to pass keywords to the callback. AbstractEventLoop.call_at(when, callback, *args) Arrange for the *callback* to be called at the given absolute This method’s behavior is the same as "call_later()". An instance of "asyncio.Handle" is returned, which can be used to Use functools.partial to pass keywords to the callback. AbstractEventLoop.time() Return the current time, as a "float" value, according to the event See also: The "asyncio.sleep()" function.
AbstractEventLoop.create_future() Create an "asyncio.Future" object attached to the loop. This is a preferred way to create futures in asyncio, as event loop New in version 3.5.2.
AbstractEventLoop.create_task(coro) Schedule the execution of a coroutine object: wrap it in a future. Third-party event loops can use their own subclass of "Task" for This method was added in Python 3.4.2. Use the "async()" function New in version 3.4.2. AbstractEventLoop.set_task_factory(factory) Set a task factory that will be used by If *factory* is "None" the default task factory will be set. If *factory* is a *callable*, it should have a signature matching New in version 3.4.4. AbstractEventLoop.get_task_factory() Return a task factory, or "None" if the default one is in use. New in version 3.4.4.
coroutine 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) Create a streaming transport connection to a given Internet *host* This method is a coroutine which will try to establish the The chronological synopsis of the underlying operation is as 1. The connection is established, and a transport is created to 2. *protocol_factory* is called without arguments and must 3. The protocol instance is tied to the transport, and its 4. The coroutine returns successfully with the "(transport, The created transport is an implementation-dependent bidirectional Note: *protocol_factory* can be any kind of callable, not Options that change how the connection is created: * *ssl*: if given and not false, a SSL/TLS transport is created See also: SSL/TLS security considerations * *server_hostname*, is only for use together with *ssl*, and * *family*, *proto*, *flags* are the optional address family, * *sock*, if given, should be an existing, already connected * *local_addr*, if given, is a "(local_host, local_port)" tuple Changed in version 3.5: On Windows with "ProactorEventLoop", See also: The "open_connection()" function can be used to get a coroutine 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) Create datagram connection: socket family "AF_INET" or "AF_INET6" This method is a coroutine which will try to establish the Options changing how the connection is created: * *local_addr*, if given, is a "(local_host, local_port)" tuple * *remote_addr*, if given, is a "(remote_host, remote_port)" * *family*, *proto*, *flags* are the optional address family, * *reuse_address* tells the kernel to reuse a local socket in * *reuse_port* tells the kernel to allow this endpoint to be * *allow_broadcast* tells the kernel to allow this endpoint to * *sock* can optionally be specified in order to use a On Windows with "ProactorEventLoop", this method is not supported. See UDP echo client protocol and UDP echo server protocol examples. coroutine AbstractEventLoop.create_unix_connection(protocol_factory, path, *, ssl=None, sock=None, server_hostname=None) Create UNIX connection: socket family "AF_UNIX", socket type This method is a coroutine which will try to establish the *path* is the name of a UNIX domain socket, and is required unless See the "AbstractEventLoop.create_connection()" method for Availability: UNIX.
coroutine 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) Create a TCP server (socket type "SOCK_STREAM") bound to *host* and Return a "Server" object, its "sockets" attribute contains created Parameters: * The *host* parameter can be a string, in that case the TCP * *family* can be set to either "socket.AF_INET" or "AF_INET6" to * *flags* is a bitmask for "getaddrinfo()". * *sock* can optionally be specified in order to use a * *backlog* is the maximum number of queued connections passed to * *ssl* can be set to an "SSLContext" to enable SSL over the * *reuse_address* tells the kernel to reuse a local socket in * *reuse_port* tells the kernel to allow this endpoint to be This method is a coroutine. Changed in version 3.5: On Windows with "ProactorEventLoop", See also: The function "start_server()" creates a Changed in version 3.5.1: The *host* parameter can now be a coroutine AbstractEventLoop.create_unix_server(protocol_factory, path=None, *, sock=None, backlog=100, ssl=None) Similar to "AbstractEventLoop.create_server()", but specific to the This method is a coroutine. Availability: UNIX. coroutine BaseEventLoop.connect_accepted_socket(protocol_factory, sock, *, ssl=None) Handle an accepted connection. This is used by servers that accept connections outside of asyncio Parameters: * *sock* is a preexisting socket object returned from an "accept" * *ssl* can be set to an "SSLContext" to enable SSL over the This method is a coroutine. When completed, the coroutine returns New in version 3.5.3.
On Windows with "SelectorEventLoop", only socket handles are supported On Windows with "ProactorEventLoop", these methods are not supported. AbstractEventLoop.add_reader(fd, callback, *args) Start watching the file descriptor for read availability and then Use functools.partial to pass keywords to the callback. AbstractEventLoop.remove_reader(fd) Stop watching the file descriptor for read availability. AbstractEventLoop.add_writer(fd, callback, *args) Start watching the file descriptor for write availability and then Use functools.partial to pass keywords to the callback. AbstractEventLoop.remove_writer(fd) Stop watching the file descriptor for write availability. The watch a file descriptor for read events example uses the low-level
coroutine AbstractEventLoop.sock_recv(sock, nbytes) Receive data from the socket. Modeled after blocking The return value is a bytes object representing the data received. With "SelectorEventLoop" event loop, the socket *sock* must be non- This method is a coroutine. coroutine AbstractEventLoop.sock_sendall(sock, data) Send data to the socket. Modeled after blocking The socket must be connected to a remote socket. This method With "SelectorEventLoop" event loop, the socket *sock* must be non- This method is a coroutine. coroutine AbstractEventLoop.sock_connect(sock, address) Connect to a remote socket at *address*. Modeled after blocking With "SelectorEventLoop" event loop, the socket *sock* must be non- This method is a coroutine. Changed in version 3.5.2: "address" no longer needs to be resolved. See also: "AbstractEventLoop.create_connection()" and coroutine AbstractEventLoop.sock_accept(sock) Accept a connection. Modeled after blocking The socket must be bound to an address and listening for The socket *sock* must be non-blocking. This method is a coroutine. See also: "AbstractEventLoop.create_server()" and
coroutine AbstractEventLoop.getaddrinfo(host, port, *, family=0, type=0, proto=0, flags=0) This method is a coroutine, similar to "socket.getaddrinfo()" coroutine AbstractEventLoop.getnameinfo(sockaddr, flags=0) This method is a coroutine, similar to "socket.getnameinfo()"
On Windows with "SelectorEventLoop", these methods are not supported. coroutine AbstractEventLoop.connect_read_pipe(protocol_factory, pipe) Register read pipe in eventloop. *protocol_factory* should instantiate object with "Protocol" With "SelectorEventLoop" event loop, the *pipe* is set to non- This method is a coroutine. coroutine AbstractEventLoop.connect_write_pipe(protocol_factory, pipe) Register write pipe in eventloop. *protocol_factory* should instantiate object with "BaseProtocol" With "SelectorEventLoop" event loop, the *pipe* is set to non- This method is a coroutine. See also: The "AbstractEventLoop.subprocess_exec()" and
Availability: UNIX only. AbstractEventLoop.add_signal_handler(signum, callback, *args) Add a handler for a signal. Raise "ValueError" if the signal number is invalid or uncatchable. Use functools.partial to pass keywords to the callback. AbstractEventLoop.remove_signal_handler(sig) Remove a handler for a signal. Return "True" if a signal handler was removed, "False" if not. See also: The "signal" module.
Call a function in an "Executor" (pool of threads or pool of coroutine AbstractEventLoop.run_in_executor(executor, func, *args) Arrange for a *func* to be called in the specified executor. The *executor* argument should be an "Executor" instance. The Use functools.partial to pass keywords to the *func*. This method is a coroutine. Changed in version 3.5.3: "BaseEventLoop.run_in_executor()" no AbstractEventLoop.set_default_executor(executor) Set the default executor used by "run_in_executor()".
Allows customizing how exceptions are handled in the event loop. AbstractEventLoop.set_exception_handler(handler) 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 AbstractEventLoop.get_exception_handler() Return the exception handler, or "None" if the default one is in New in version 3.5.2. AbstractEventLoop.default_exception_handler(context) Default exception handler. This is called when an exception occurs and no exception handler is *context* parameter has the same meaning as in AbstractEventLoop.call_exception_handler(context) Call the current event loop exception handler. *context* is a "dict" object containing the following keys (new * ‘message’: Error message; * ‘exception’ (optional): Exception object; * ‘future’ (optional): "asyncio.Future" instance; * ‘handle’ (optional): "asyncio.Handle" instance; * ‘protocol’ (optional): Protocol instance; * ‘transport’ (optional): Transport instance; * ‘socket’ (optional): "socket.socket" instance. Note: Note: this method should not be overloaded in subclassed
AbstractEventLoop.get_debug() Get the debug mode ("bool") of the event loop. The default value is "True" if the environment variable New in version 3.4.2. AbstractEventLoop.set_debug(enabled: bool) Set the debug mode of the event loop. New in version 3.4.2. See also: The debug mode of asyncio.
class asyncio.Server Server listening on sockets. Object created by the "AbstractEventLoop.create_server()" method close() Stop serving: close listening sockets and set the "sockets" The sockets that represent existing incoming client connections The server is closed asynchronously, use the "wait_closed()" coroutine wait_closed() Wait until the "close()" method completes. This method is a coroutine. sockets List of "socket.socket" objects the server is listening to, or
class asyncio.Handle A callback wrapper object returned by cancel() Cancel the call. If the callback is already canceled or
Example using the "AbstractEventLoop.call_soon()" method to schedule a import asyncio def hello_world(loop): loop = asyncio.get_event_loop() # Schedule a call to hello_world() # Blocking call interrupted by loop.stop() See also: The Hello World coroutine example uses a coroutine.
Example of callback displaying the current date every second. The import asyncio def display_date(end_time, loop): loop = asyncio.get_event_loop() # Schedule the first call to display_date() # Blocking call interrupted by loop.stop() See also: The coroutine displaying the current date example uses a
Wait until a file descriptor received some data using the import asyncio # Create a pair of connected file descriptors def reader(): # Register the file descriptor for read event # Simulate the reception of data from the network # Run the event loop # We are done, close sockets and the event loop See also: The register an open socket to wait for data using a The register an open socket to wait for data using streams example
Register handlers for signals "SIGINT" and "SIGTERM" using the import asyncio def ask_exit(signame): loop = asyncio.get_event_loop() print("Event loop running forever, press Ctrl+C to interrupt.") This example only works on UNIX. |
|