UDP sockets (Effect's DatagramSocket and NodeDatagramSocket).
Acquiring a socket's reader in a scope opens and binds a socket owned
by that scope; only one reader is open at a time. pull returns every
packet queued since the last pull, or waits for the next. Writes wait while
no reader is open, so a send-only client still acquires a reader::
server = InetAddressV4(IPv4Address("127.0.0.1"), 5353)
def request(payload: str):
socket = yield from DatagramSocket
reader = yield from socket.reader
writer = yield from socket.writer
yield from writer.write(OutgoingDatagram(payload, server))
(response, *_) = yield from reader.pull
return response.payloadmake_udp / layer_udp open sockets with Python's socket module (read on
the socket loop's thread, so they work under run_blocking too);
from_socket adopts a bound one; make_from_backing_socket is the
contract other transports implement.
Types#
| Type | Definition | Description |
|---|---|---|
OnError | type OnError = Callable[[DatagramSocketError], None] | |
DatagramSocketErrorReason | type DatagramSocketErrorReason = DatagramSocketOpenError | DatagramSocketReadError | DatagramSocketWriteError | DatagramSocketClosedError | DatagramSocketUnsupportedError | |
IoErrorKind | type IoErrorKind = Literal['MessageTooLarge', 'Unreachable', 'ConnectionRefused', 'PermissionDenied', 'Unknown'] | |
OpenErrorKind | type OpenErrorKind = Literal['AddressInUse', 'AddressNotAvailable', 'PermissionDenied', 'Unknown'] | |
Endpoint | type Endpoint = HostPort | InetAddress | |
Family | type Family = Literal['ipv4', 'ipv6'] | |
Leave | type Leave = Callable[[], Effect[None]] | |
Outgoing | type Outgoing = OutgoingDatagram | Datagram | What a write takes: a packet, or a received one to echo. |
SendDone | type SendDone = Callable[[DatagramSocketError | None], None] | |
SendManyDone | type SendManyDone = Callable[[DatagramSocketError | None, int | None], None] |
Classes#
Functions#
make_from_backing_socket#
make_from_backing_socket(open: Open[Scope], *, receive_buffer: ReceiveBuffer | None = None, on_error: OnError | None = None) -> Effect[DatagramSocketService]
make_from_backing_socket[R](open: Open[R | Scope], *, receive_buffer: ReceiveBuffer | None = None, on_error: OnError | None = None) -> Effect[DatagramSocketService, Never, R]A DatagramSocket that calls open for each reader acquisition.
open gets the event callbacks before the socket exists and runs in
the reader's scope, with the services of the fiber that built the
socket (the acquiring fiber's own take precedence). If the acquisition
is interrupted while open runs, the interruption returns at once,
open is left to finish and the socket it gives is closed; the next
reader waits until it has settled, so two sockets never exist at once.
on_error gets errors no write is left to fail; what it raises is
ignored.
| Parameter | Type | Description |
|---|---|---|
open | ||
receive_buffer | = None | |
on_error | = None |
@overload
def make_from_backing_socket(
open: Open[Scope],
*,
receive_buffer: ReceiveBuffer | None = None,
on_error: OnError | None = None,
) -> Effect[DatagramSocketService]: ...
@overload
def make_from_backing_socket[R](
open: Open[R | Scope],
*,
receive_buffer: ReceiveBuffer | None = None,
on_error: OnError | None = None,
) -> Effect[DatagramSocketService, Never, R]: ...
def make_from_backing_socket(
open: Open[Any],
*,
receive_buffer: ReceiveBuffer | None = None,
on_error: OnError | None = None,
) -> Effect[DatagramSocketService, Never, Any]:
"""A ``DatagramSocket`` that calls ``open`` for each reader acquisition.
``open`` gets the event callbacks before the socket exists and runs in
the reader's scope, with the services of the fiber that built the
socket (the acquiring fiber's own take precedence). If the acquisition
is interrupted while ``open`` runs, the interruption returns at once,
``open`` is left to finish and the socket it gives is closed; the next
reader waits until it has settled, so two sockets never exist at once.
``on_error`` gets errors no write is left to fail; what it raises is
ignored."""
buffer = receive_buffer or ReceiveBuffer()
if buffer.capacity < 1:
return die(
ValueError(
"DatagramSocket receive buffer capacity must be a positive integer, "
f"received {buffer.capacity}"
)
)
return context().map(lambda services: _build(open, services, buffer, on_error))from_socket#
from_socket(acquire: Effect[socket.socket, DatagramSocketError, Scope], *, peer: Endpoint | None = None, receive_buffer: ReceiveBuffer | None = None, on_error: OnError | None = None) -> Effect[DatagramSocketService]
from_socket[R](acquire: Effect[socket.socket, DatagramSocketError, R | Scope], *, peer: Endpoint | None = None, receive_buffer: ReceiveBuffer | None = None, on_error: OnError | None = None) -> Effect[DatagramSocketService, Never, R]Adopt a bound UDP socket.socket: acquire runs for each
reader acquisition, in the reader's scope, and the socket is closed
with it. A connected socket sends to its remote address.
| Parameter | Type | Description |
|---|---|---|
acquire | ||
peer | = None | |
receive_buffer | = None | |
on_error | = None |
@overload
def from_socket(
acquire: Effect[socket.socket, DatagramSocketError, Scope],
*,
peer: Endpoint | None = None,
receive_buffer: ReceiveBuffer | None = None,
on_error: OnError | None = None,
) -> Effect[DatagramSocketService]: ...
@overload
def from_socket[R](
acquire: Effect[socket.socket, DatagramSocketError, R | Scope],
*,
peer: Endpoint | None = None,
receive_buffer: ReceiveBuffer | None = None,
on_error: OnError | None = None,
) -> Effect[DatagramSocketService, Never, R]: ...
def from_socket(
acquire: Effect[socket.socket, DatagramSocketError, object],
*,
peer: Endpoint | None = None,
receive_buffer: ReceiveBuffer | None = None,
on_error: OnError | None = None,
) -> Effect[DatagramSocketService, Never, object]:
"""Adopt a bound UDP ``socket.socket``: ``acquire`` runs for each
reader acquisition, in the reader's scope, and the socket is closed
with it. A connected socket sends to its remote address."""
require_effect(acquire, "acquire")
return make_from_backing_socket(
lambda events: acquire.flat_map(lambda sock: _adopt(sock, peer, events)),
receive_buffer=receive_buffer,
on_error=on_error,
)layer_udp#
layer_udp(options=None) -> Layer[DatagramSocket]Provide a DatagramSocket built with make_udp.
| Parameter | Type | Description |
|---|---|---|
options | Options | None = None |
Returns Layer[DatagramSocket]
def layer_udp(options: Options | None = None) -> Layer[DatagramSocket]:
"""Provide a ``DatagramSocket`` built with ``make_udp``."""
return layer_effect(DatagramSocket, make_udp(options))make_udp#
make_udp(options=None) -> Effect[DatagramSocketService]A DatagramSocket that opens and binds a new socket for each reader
acquisition. Making it never fails; binding, options and name
resolution fail the acquisition.
| Parameter | Type | Description |
|---|---|---|
options | Options | None = None |
Returns Effect[DatagramSocketService]
def make_udp(options: Options | None = None) -> Effect[DatagramSocketService]:
"""A ``DatagramSocket`` that opens and binds a new socket for each reader
acquisition. Making it never fails; binding, options and name
resolution fail the acquisition."""
opts = options or Options()
return make_from_backing_socket(
lambda events: _open(opts, events),
receive_buffer=opts.receive_buffer,
on_error=opts.on_error,
)make#
make(reader, writer) -> DatagramSocketService| Parameter | Type | Description |
|---|---|---|
reader | Effect[Reader, DatagramSocketError, Scope] | |
writer | Effect[Writer, Never, Scope] |
Returns DatagramSocketService
def make(
reader: Effect[Reader, DatagramSocketError, Scope], writer: Effect[Writer, Never, Scope]
) -> DatagramSocketService:
return DatagramSocketService(reader, writer)