💾 Archived View for tris.fyi › pydoc › asyncio.unix_events captured on 2022-04-28 at 17:42:19. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2022-03-01)
-=-=-=-=-=-=-
Selector event loop for Unix with signal handling.
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.
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.
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.
'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)
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)
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)
'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)
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 0x7ff3609c6b40>, 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.
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)
logger = <Logger asyncio (INFO)>