asyncio.unix_events

Selector event loop for Unix with signal handling.

Classes

AbstractChildWatcher

Abstract base class for monitoring child processes.

    Objects derived from this class monitor a collection of subprocesses and
    report their termination or interruption by a signal.

    New callbacks are registered with .add_child_handler(). Starting a new
    process must be done within a 'with' block to allow the watcher to suspend
    its activity until the new process if fully registered (this is needed to
    prevent a race condition in some implementations).

    Example:
        with watcher:
            proc = subprocess.Popen("sleep 1")
            watcher.add_child_handler(proc.pid, callback)

    Notes:
        Implementations of this class must be thread-safe.

        Since child watcher objects may catch the SIGCHLD signal and call
        waitpid(-1), there should be only one active object per process.

add_child_handler(self, pid, callback, *args)

  Register a new child handler.

          Arrange for callback(pid, returncode, *args) to be called when
          process 'pid' terminates. Specifying another callback for the same
          process replaces the previous handler.

          Note: callback() must be thread-safe.

attach_loop(self, loop)

  Attach the watcher to an event loop.

          If the watcher was previously attached to an event loop, then it is
          first detached before attaching to the new loop.

          Note: loop may be None.

close(self)

  Close the watcher.

          This must be called to make sure that any underlying resource is freed.

is_active(self)

  Return ``True`` if the watcher is active and is used by the event loop.

          Return True if the watcher is installed and ready to handle process exit
          notifications.

remove_child_handler(self, pid)

  Removes the handler for process 'pid'.

          The function returns True if the handler was successfully removed,
          False if there was nothing to remove.

BaseChildWatcher

add_child_handler(self, pid, callback, *args)

  Register a new child handler.

          Arrange for callback(pid, returncode, *args) to be called when
          process 'pid' terminates. Specifying another callback for the same
          process replaces the previous handler.

          Note: callback() must be thread-safe.

attach_loop(self, loop)

close(self)

is_active(self)

remove_child_handler(self, pid)

  Removes the handler for process 'pid'.

          The function returns True if the handler was successfully removed,
          False if there was nothing to remove.

_UnixDefaultEventLoopPolicy

UNIX event loop policy with a watcher for child processes.

get_child_watcher(self)

  Get the watcher for child processes.

          If not yet set, a ThreadedChildWatcher object is automatically created.

get_event_loop(self)

  Get the event loop for the current context.

          Returns an instance of EventLoop or raises an exception.

new_event_loop(self)

  Create a new event loop.

          You must call set_event_loop() to make this the current event
          loop.

set_child_watcher(self, watcher)

  Set the watcher for child processes.

set_event_loop(self, loop)

  Set the event loop.

          As a side effect, if a child watcher was set before, then calling
          .set_event_loop() from the main thread will call .attach_loop(loop) on
          the child watcher.

FastChildWatcher

'Fast' child watcher implementation.

    This implementation reaps every terminated processes by calling
    os.waitpid(-1) directly, possibly breaking other code spawning processes
    and waiting for their termination.

    There is no noticeable overhead when handling a big number of children
    (O(1) each time a child terminates).

add_child_handler(self, pid, callback, *args)

attach_loop(self, loop)

close(self)

is_active(self)

remove_child_handler(self, pid)

MultiLoopChildWatcher

A watcher that doesn't require running loop in the main thread.

    This implementation registers a SIGCHLD signal handler on
    instantiation (which may conflict with other code that
    install own handler for this signal).

    The solution is safe but it has a significant overhead when
    handling a big number of processes (*O(n)* each time a
    SIGCHLD is received).

add_child_handler(self, pid, callback, *args)

attach_loop(self, loop)

close(self)

is_active(self)

remove_child_handler(self, pid)

PidfdChildWatcher

Child watcher implementation using Linux's pid file descriptors.

    This child watcher polls process file descriptors (pidfds) to await child
    process termination. In some respects, PidfdChildWatcher is a "Goldilocks"
    child watcher implementation. It doesn't require signals or threads, doesn't
    interfere with any processes launched outside the event loop, and scales
    linearly with the number of subprocesses launched by the event loop. The
    main disadvantage is that pidfds are specific to Linux, and only work on
    recent (5.3+) kernels.

add_child_handler(self, pid, callback, *args)

attach_loop(self, loop)

close(self)

is_active(self)

remove_child_handler(self, pid)

SafeChildWatcher

'Safe' child watcher implementation.

    This implementation avoids disrupting other code spawning processes by
    polling explicitly each process in the SIGCHLD handler instead of calling
    os.waitpid(-1).

    This is a safe solution but it has a significant overhead when handling a
    big number of children (O(n) each time SIGCHLD is raised)

add_child_handler(self, pid, callback, *args)

attach_loop(self, loop)

close(self)

is_active(self)

remove_child_handler(self, pid)

_UnixSelectorEventLoop

Unix event loop.

    Adds signal handling and UNIX Domain Socket support to SelectorEventLoop.

add_reader(self, fd, callback, *args)

  Add a reader callback.

add_signal_handler(self, sig, callback, *args)

  Add a handler for a signal.  UNIX only.

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

add_writer(self, fd, callback, *args)

  Add a writer callback..

call_at(self, when, callback, *args, context=None)

  Like call_later(), but uses an absolute time.

          Absolute time corresponds to the event loop's time() method.

call_exception_handler(self, context)

  Call the current event loop's exception handler.

          The context argument is a dict containing the following keys:

          - 'message': Error message;
          - 'exception' (optional): Exception object;
          - 'future' (optional): Future instance;
          - 'task' (optional): Task instance;
          - 'handle' (optional): Handle instance;
          - 'protocol' (optional): Protocol instance;
          - 'transport' (optional): Transport instance;
          - 'socket' (optional): Socket instance;
          - 'asyncgen' (optional): Asynchronous generator that caused
                                   the exception.

          New keys maybe introduced in the future.

          Note: do not overload this method in an event loop subclass.
          For custom exception handling, use the
          `set_exception_handler()` method.

call_later(self, delay, callback, *args, context=None)

  Arrange for a callback to be called at a given time.

          Return a Handle: an opaque object with a cancel() method that
          can be used to cancel the call.

          The delay can be an int or float, expressed in seconds.  It is
          always relative to the current time.

          Each callback will be called exactly once.  If two callbacks
          are scheduled for exactly the same time, it undefined which
          will be called first.

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

call_soon(self, callback, *args, context=None)

  Arrange for a callback to be called as soon as possible.

          This operates as a FIFO queue: callbacks are called in the
          order in which they are registered.  Each callback will be
          called exactly once.

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

call_soon_threadsafe(self, callback, *args, context=None)

  Like call_soon(), but thread-safe.

close(self)

connect_accepted_socket(self, protocol_factory, sock, *, ssl=None, ssl_handshake_timeout=None)

  Handle an accepted connection.

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

          This method is a coroutine.  When completed, the coroutine
          returns a (transport, protocol) pair.

connect_read_pipe(self, protocol_factory, pipe)

connect_write_pipe(self, protocol_factory, pipe)

create_connection(self, protocol_factory, host=None, port=None, *, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None, happy_eyeballs_delay=None, interleave=None)

  Connect to a TCP server.

          Create a streaming transport connection to a given Internet host and
          port: socket family AF_INET or socket.AF_INET6 depending on host (or
          family if specified), socket type SOCK_STREAM. protocol_factory must be
          a callable returning a protocol instance.

          This method is a coroutine which will try to establish the connection
          in the background.  When successful, the coroutine returns a
          (transport, protocol) pair.

create_datagram_endpoint(self, protocol_factory, local_addr=None, remote_addr=None, *, family=0, proto=0, flags=0, reuse_address=<object object at 0x7f0227c3cb40>, reuse_port=None, allow_broadcast=None, sock=None)

  Create datagram connection.

create_future(self)

  Create a Future object attached to the loop.

create_server(self, protocol_factory, host=None, port=None, *, family=<AddressFamily.AF_UNSPEC: 0>, flags=<AddressInfo.AI_PASSIVE: 1>, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, ssl_handshake_timeout=None, start_serving=True)

  Create a TCP server.

          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 a host
          appears multiple times (possibly indirectly e.g. when hostnames
          resolve to the same IP address), the server is only bound once to that
          host.

          Return a Server object which can be used to stop the service.

          This method is a coroutine.

create_task(self, coro, *, name=None)

  Schedule a coroutine object.

          Return a task object.

create_unix_connection(self, protocol_factory, path=None, *, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None)

create_unix_server(self, protocol_factory, path=None, *, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, start_serving=True)

default_exception_handler(self, context)

  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.

          This default handler logs the error message and other
          context-dependent information.  In debug mode, a truncated
          stack trace is also appended showing where the given object
          (e.g. a handle or future or task) was created, if any.

          The context parameter has the same meaning as in
          `call_exception_handler()`.

get_debug(self)

get_exception_handler(self)

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

get_task_factory(self)

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

getaddrinfo(self, host, port, *, family=0, type=0, proto=0, flags=0)

getnameinfo(self, sockaddr, flags=0)

is_closed(self)

  Returns True if the event loop was closed.

is_running(self)

  Returns True if the event loop is running.

remove_reader(self, fd)

  Remove a reader callback.

remove_signal_handler(self, sig)

  Remove a handler for a signal.  UNIX only.

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

remove_writer(self, fd)

  Remove a writer callback.

run_forever(self)

  Run until stop() is called.

run_in_executor(self, executor, func, *args)

run_until_complete(self, future)

  Run until the Future is done.

          If the argument is a coroutine, it is wrapped in a Task.

          WARNING: It would be disastrous to call run_until_complete()
          with the same coroutine twice -- it would wrap it in two
          different Tasks and that can't be good.

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

sendfile(self, transport, file, offset=0, count=None, *, fallback=True)

  Send a file to transport.

          Return the total number of bytes which were sent.

          The method uses high-performance os.sendfile if available.

          file must be a regular file object opened in binary mode.

          offset tells from where to start reading the file. If specified,
          count is the total number of bytes to transmit as opposed to
          sending the file until EOF is reached. File position is updated on
          return or also in case of error in which case file.tell()
          can be used to figure out the number of bytes
          which were sent.

          fallback set to True makes asyncio to manually read and send
          the file when the platform does not support the sendfile syscall
          (e.g. Windows or SSL socket on Unix).

          Raise SendfileNotAvailableError if the system does not support
          sendfile syscall and fallback is False.

set_debug(self, enabled)

set_default_executor(self, executor)

set_exception_handler(self, 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
          signature matching '(loop, context)', where 'loop'
          will be a reference to the active event loop, 'context'
          will be a dict object (see `call_exception_handler()`
          documentation for details about context).

set_task_factory(self, factory)

  Set a task factory that will be used by loop.create_task().

          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 a Future.

shutdown_asyncgens(self)

  Shutdown all active asynchronous generators.

shutdown_default_executor(self)

  Schedule the shutdown of the default executor.

sock_accept(self, sock)

  Accept a connection.

          The socket must be bound to an address and listening 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.

sock_connect(self, sock, address)

  Connect to a remote socket at address.

          This method is a coroutine.

sock_recv(self, sock, n)

  Receive data from the socket.

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

sock_recv_into(self, sock, buf)

  Receive data from the socket.

          The received data is written into *buf* (a writable buffer).
          The return value is the number of bytes written.

sock_sendall(self, sock, data)

  Send data to the socket.

          The socket must be connected to a remote socket. 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 any, was
          successfully processed by the receiving end of the connection.

sock_sendfile(self, sock, file, offset=0, count=None, *, fallback=True)

start_tls(self, transport, protocol, sslcontext, *, server_side=False, server_hostname=None, ssl_handshake_timeout=None)

  Upgrade transport to TLS.

          Return a new transport that *protocol* should start using
          immediately.

stop(self)

  Stop running the event loop.

          Every callback already scheduled will still run.  This simply informs
          run_forever to stop looping after a complete iteration.

subprocess_exec(self, protocol_factory, program, *args, stdin=-1, stdout=-1, stderr=-1, universal_newlines=False, shell=False, bufsize=0, encoding=None, errors=None, text=None, **kwargs)

subprocess_shell(self, protocol_factory, cmd, *, stdin=-1, stdout=-1, stderr=-1, universal_newlines=False, shell=True, bufsize=0, encoding=None, errors=None, text=None, **kwargs)

time(self)

  Return the time according to the event loop's clock.

          This is a float expressed in seconds since an epoch, but the
          epoch, precision, accuracy and drift are unspecified and may
          differ per event loop.

ThreadedChildWatcher

Threaded child watcher implementation.

    The watcher uses a thread per process
    for waiting for the process finish.

    It doesn't require subscription on POSIX signal
    but a thread creation is not free.

    The watcher has O(1) complexity, its performance doesn't depend
    on amount of spawn processes.

add_child_handler(self, pid, callback, *args)

attach_loop(self, loop)

close(self)

is_active(self)

remove_child_handler(self, pid)

Other members

logger = <Logger asyncio (INFO)>

Modules