Skip to content

UDPSocket[optional UDP: UDPBackend ref]

[Source]

A UDP socket: bind, send datagrams, receive datagrams, and close. A UDPSocketActor owns one and delegates to it.

Create with UDPSocket(auth, host, port, enclosing, ler), using UDPSocket.none() as the field initializer before that. See the package documentation for the full lifecycle.

class ref UDPSocket[optional UDP: UDPBackend ref]

Constructors

create

[Source]

Bind a UDP socket to host:port. Port "0" lets the OS assign an ephemeral port.

new ref create(
  auth: UDPAuth val,
  host: String val,
  port: String val,
  enclosing: UDPSocketActor[UDP] ref,
  ler: UDPLifecycleEventReceiver[UDP] ref,
  read_buffer_size: ReadBufferSize = DefaultReadBufferSize(),
  ip_version: IPVersion = DualStack,
  max_datagrams_per_turn: USize val = 256)
: UDPSocket[UDP] ref^

Parameters

Returns

none

[Source]

Placeholder for field initialization before the real constructor runs.

new ref none()
: UDPSocket[UDP] ref^

Returns

Public Functions

send_to

[Source]

Send one datagram to to. Returns SendToOk when the datagram was handed to the OS. UDP sends are synchronous and all-or-nothing: the entire datagram goes out or nothing does.

fun ref send_to(
  data: ByteSeq,
  to: NetAddress box)
: SendToResult

Parameters

Returns

close

[Source]

Close the socket. No graceful shutdown: the fd is closed immediately.

fun ref close()
: None val

Returns

local_address

[Source]

Return the local IP address. If the socket is closed the address returned is invalid.

fun ref local_address()
: NetAddress val

Returns

read_again

[Source]

Re-enter the read loop. Called internally after yielding or exhausting the per-turn budget; applications do not call this directly.

fun ref read_again()
: None val

Returns

is_open

[Source]

True when the socket is bound and has not been closed.

fun box is_open()
: Bool val

Returns

is_closed

[Source]

True when the socket has been closed.

fun box is_closed()
: Bool val

Returns

get_so_rcvbuf

[Source]

Get the OS receive buffer size for this socket. Returns (errno, value). On success errno is 0.

fun box get_so_rcvbuf()
: (U32 val , U32 val)

Returns

set_so_rcvbuf

[Source]

Set the OS receive buffer size for this socket. Returns 0 on success, or a non-zero errno.

fun box set_so_rcvbuf(
  bufsize: U32 val)
: U32 val

Parameters

  • bufsize: U32 val

Returns

get_so_sndbuf

[Source]

Get the OS send buffer size for this socket. Returns (errno, value). On success errno is 0.

fun box get_so_sndbuf()
: (U32 val , U32 val)

Returns

set_so_sndbuf

[Source]

Set the OS send buffer size for this socket. Returns 0 on success, or a non-zero errno.

fun box set_so_sndbuf(
  bufsize: U32 val)
: U32 val

Parameters

  • bufsize: U32 val

Returns

join_multicast_group_v4

[Source]

Join an IPv4 multicast group. group is a dotted-decimal multicast address (e.g. "239.1.2.3"). interface_addr selects the local interface; "0.0.0.0" lets the OS choose. Returns 0 on success, or a non-zero errno.

fun box join_multicast_group_v4(
  group: String val,
  interface_addr: String val = "0.0.0.0")
: U32 val

Parameters

Returns

leave_multicast_group_v4

[Source]

Leave an IPv4 multicast group previously joined with join_multicast_group_v4. Returns 0 on success, or a non-zero errno.

fun box leave_multicast_group_v4(
  group: String val,
  interface_addr: String val = "0.0.0.0")
: U32 val

Parameters

Returns

join_multicast_group_v6

[Source]

Join an IPv6 multicast group. group is an IPv6 multicast address (e.g. "ff12::1"). interface_index selects the local interface by its OS index; 0 lets the OS choose. Returns 0 on success, or a non-zero errno.

fun box join_multicast_group_v6(
  group: String val,
  interface_index: U32 val = 0)
: U32 val

Parameters

  • group: String val
  • interface_index: U32 val = 0

Returns

leave_multicast_group_v6

[Source]

Leave an IPv6 multicast group previously joined with join_multicast_group_v6. Returns 0 on success, or a non-zero errno.

fun box leave_multicast_group_v6(
  group: String val,
  interface_index: U32 val = 0)
: U32 val

Parameters

  • group: String val
  • interface_index: U32 val = 0

Returns

set_multicast_ttl

[Source]

Set the IPv4 multicast time-to-live. The IPv6 counterpart is set_multicast_hops. Returns 0 on success, or a non-zero errno.

fun box set_multicast_ttl(
  ttl: U8 val)
: U32 val

Parameters

  • ttl: U8 val

Returns

set_multicast_hops

[Source]

Set the IPv6 multicast hop limit. The IPv4 counterpart is set_multicast_ttl. Returns 0 on success, or a non-zero errno.

fun box set_multicast_hops(
  hops: U32 val)
: U32 val

Parameters

  • hops: U32 val

Returns

set_multicast_loopback_v4

[Source]

Enable or disable IPv4 multicast loopback. When enabled, datagrams sent to a joined group are delivered back to this socket. Returns 0 on success, or a non-zero errno.

fun box set_multicast_loopback_v4(
  loopback: Bool val)
: U32 val

Parameters

  • loopback: Bool val

Returns

set_multicast_loopback_v6

[Source]

Enable or disable IPv6 multicast loopback. When enabled, datagrams sent to a joined group are delivered back to this socket. Returns 0 on success, or a non-zero errno.

fun box set_multicast_loopback_v6(
  loopback: Bool val)
: U32 val

Parameters

  • loopback: Bool val

Returns

set_multicast_interface_v4

[Source]

Set the default IPv4 interface for outgoing multicast datagrams. interface_addr is a dotted-decimal address of the local interface. Returns 0 on success, or a non-zero errno.

fun box set_multicast_interface_v4(
  interface_addr: String val)
: U32 val

Parameters

Returns

set_multicast_interface_v6

[Source]

Set the default IPv6 interface for outgoing multicast datagrams. interface_index is the OS interface index (0 means the default route on Linux but is rejected on macOS/BSD). Returns 0 on success, or a non-zero errno.

fun box set_multicast_interface_v6(
  interface_index: U32 val)
: U32 val

Parameters

  • interface_index: U32 val

Returns

getsockopt

[Source]

General interface to getsockopt(2). Returns (0, data) on success or (errno, undefined) on failure. Returns (1, empty) when the socket is not open. For commonly-tuned options, prefer get_so_rcvbuf and get_so_sndbuf.

fun box getsockopt(
  level: I32 val,
  option_name: I32 val,
  option_max_size: USize val = 4)
: (U32 val , Array[U8 val] iso^)

Parameters

  • level: I32 val
  • option_name: I32 val
  • option_max_size: USize val = 4

Returns

getsockopt_u32

[Source]

Wrapper for getsockopt(2) where the kernel returns a C uint32_t. Returns (0, value) on success or (errno, undefined) on failure. Returns (1, 0) when the socket is not open.

fun box getsockopt_u32(
  level: I32 val,
  option_name: I32 val)
: (U32 val , U32 val)

Parameters

  • level: I32 val
  • option_name: I32 val

Returns

setsockopt

[Source]

General interface to setsockopt(2). The caller is responsible for the correct size, byte contents, and byte order of option. Returns 0 on success, or a non-zero errno. Returns non-zero when the socket is not open. For commonly-tuned options, prefer set_so_rcvbuf and set_so_sndbuf.

fun box setsockopt(
  level: I32 val,
  option_name: I32 val,
  option: Array[U8 val] ref)
: U32 val

Parameters

Returns

setsockopt_u32

[Source]

Wrapper for setsockopt(2) where the kernel expects a C uint32_t. Returns 0 on success, or a non-zero errno. Returns non-zero when the socket is not open.

fun box setsockopt_u32(
  level: I32 val,
  option_name: I32 val,
  option: U32 val)
: U32 val

Parameters

  • level: I32 val
  • option_name: I32 val
  • option: U32 val

Returns