GitHub

datagram

API reference for datagram.

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.payload

make_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

TypeDefinitionDescription
OnErrortype OnError = Callable[[DatagramSocketError], None]
DatagramSocketErrorReasontype DatagramSocketErrorReason = DatagramSocketOpenError | DatagramSocketReadError | DatagramSocketWriteError | DatagramSocketClosedError | DatagramSocketUnsupportedError
IoErrorKindtype IoErrorKind = Literal['MessageTooLarge', 'Unreachable', 'ConnectionRefused', 'PermissionDenied', 'Unknown']
OpenErrorKindtype OpenErrorKind = Literal['AddressInUse', 'AddressNotAvailable', 'PermissionDenied', 'Unknown']
Endpointtype Endpoint = HostPort | InetAddress
Familytype Family = Literal['ipv4', 'ipv6']
Leavetype Leave = Callable[[], Effect[None]]
Outgoingtype Outgoing = OutgoingDatagram | Datagram

What a write takes: a packet, or a received one to echo.

SendDonetype SendDone = Callable[[DatagramSocketError | None], None]
SendManyDonetype 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.

ParameterTypeDescription
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.

ParameterTypeDescription
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.

ParameterTypeDescription
optionsOptions | 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.

ParameterTypeDescription
optionsOptions | 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
ParameterTypeDescription
readerEffect[Reader, DatagramSocketError, Scope]
writerEffect[Writer, Never, Scope]

Returns DatagramSocketService

def make(
    reader: Effect[Reader, DatagramSocketError, Scope], writer: Effect[Writer, Never, Scope]
) -> DatagramSocketService:
    return DatagramSocketService(reader, writer)