Skip to content

UDPSocket

[Source]

Creates a UDP socket that can be used for sending and receiving UDP messages.

The following examples create: an echo server that listens for connections and returns whatever message it receives a client that connects to the server, sends a message, and prints the message it receives in response

The server is implemented like this:

use "net"

class MyUDPNotify is UDPNotify
  fun ref received(
    sock: UDPSocket ref,
    data: Array[U8] iso,
    from: NetAddress)
  =>
    sock.write(consume data, from)

  fun ref not_listening(sock: UDPSocket ref) =>
    None

actor Main
  new create(env: Env) =>
    try
      UDPSocket(env.root as AmbientAuth,
        MyUDPNotify, "", "8989")
    end

The client is implemented like this:

use "net"

class MyUDPNotify is UDPNotify
  let _out: OutStream
  let _destination: NetAddress

  new create(
    out: OutStream,
    destination: NetAddress)
  =>
    _out = out
    _destination = destination

  fun ref listening(sock: UDPSocket ref) =>
    sock.write("hello world", _destination)

  fun ref received(
    sock: UDPSocket ref,
    data: Array[U8] iso,
    from: NetAddress)
  =>
    _out.print("GOT:" + String.from_array(consume data))
    sock.dispose()

  fun ref not_listening(sock: UDPSocket ref) =>
    None

actor Main
  new create(env: Env) =>
    try
      let destination =
        DNS.ip4(env.root as AmbientAuth, "localhost", "8989")(0)?
      UDPSocket(env.root as AmbientAuth,
        recover MyUDPNotify(env.out, consume destination) end)
    end
actor tag UDPSocket

Constructors

create

[Source]

Listens for both IPv4 and IPv6 datagrams.

new tag create(
  auth: (AmbientAuth val | NetAuth val | UDPAuth val),
  notify: UDPNotify iso,
  host: String val = seq,
  service: String val = seq,
  size: USize val = seq)
: UDPSocket tag^

Parameters

Returns


ip4

[Source]

Listens for IPv4 datagrams.

new tag ip4(
  auth: (AmbientAuth val | NetAuth val | UDPAuth val),
  notify: UDPNotify iso,
  host: String val = seq,
  service: String val = seq,
  size: USize val = seq)
: UDPSocket tag^

Parameters

Returns


ip6

[Source]

Listens for IPv6 datagrams.

new tag ip6(
  auth: (AmbientAuth val | NetAuth val | UDPAuth val),
  notify: UDPNotify iso,
  host: String val = seq,
  service: String val = seq,
  size: USize val = seq)
: UDPSocket tag^

Parameters

Returns


Public Behaviours

write

[Source]

Write a single sequence of bytes.

be write(
  data: (String val | Array[U8 val] val),
  to: NetAddress val)

Parameters


writev

[Source]

Write a sequence of sequences of bytes.

be writev(
  data: ByteSeqIter val,
  to: NetAddress val)

Parameters


set_notify

[Source]

Change the notifier.

be set_notify(
  notify: UDPNotify iso)

Parameters


set_broadcast

[Source]

Enable or disable broadcasting from this socket.

be set_broadcast(
  state: Bool val)

Parameters


set_multicast_interface

[Source]

By default, the OS will choose which address is used to send packets bound for multicast addresses. This can be used to force a specific interface. To revert to allowing the OS to choose, call with an empty string.

be set_multicast_interface(
  from: String val = seq)

Parameters


set_multicast_loopback

[Source]

By default, packets sent to a multicast address will be received by the sending system if it has subscribed to that address. Disabling loopback prevents this.

be set_multicast_loopback(
  loopback: Bool val)

Parameters

  • loopback: Bool val

set_multicast_ttl

[Source]

Set the TTL for multicast sends. Defaults to 1.

be set_multicast_ttl(
  ttl: U8 val)

Parameters

  • ttl: U8 val

multicast_join

[Source]

Add a multicast group. This can be limited to packets arriving on a specific interface.

be multicast_join(
  group: String val,
  to: String val = seq)

Parameters


multicast_leave

[Source]

Drop a multicast group. This can be limited to packets arriving on a specific interface. No attempt is made to check that this socket has previously added this group.

be multicast_leave(
  group: String val,
  to: String val = seq)

Parameters


dispose

[Source]

Stop listening.

be dispose()

Public Functions

local_address

[Source]

Return the bound IP address.

fun box local_address()
: NetAddress val

Returns


getsockopt

[Source]

General wrapper for UDP sockets to the getsockopt(2) system call.

The caller must provide an array that is pre-allocated to be at least as large as the largest data structure that the kernel may return for the requested option.

In case of system call success, this function returns the 2-tuple: 1. The integer 0. 2. An Array[U8] of data returned by the system call's void * 4th argument. Its size is specified by the kernel via the system call's sockopt_len_t * 5th argument.

In case of system call failure, this function returns the 2-tuple: 1. The value of errno. 2. An undefined value that must be ignored.

Usage example:

// listening() is a callback function for class UDPNotify
fun ref listening(sock: UDPSocket ref) =>
  match sock.getsockopt(OSSockOpt.sol_socket(), OSSockOpt.so_rcvbuf(), 4)
    | (0, let gbytes: Array[U8] iso) =>
      try
        let br = Reader.create().>append(consume gbytes)
        ifdef littleendian then
          let buffer_size = br.u32_le()?
        else
          let buffer_size = br.u32_be()?
        end
      end
    | (let errno: U32, _) =>
      // System call failed
  end
fun ref getsockopt(
  level: I32 val,
  option_name: I32 val,
  option_max_size: USize val = seq)
: (U32 val , Array[U8 val] iso^)

Parameters

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

Returns


getsockopt_u32

[Source]

Wrapper for UDP sockets to the getsockopt(2) system call where the kernel's returned option value is a C uint32_t type / Pony type U32.

In case of system call success, this function returns the 2-tuple: 1. The integer 0. 2. The *option_value returned by the kernel converted to a Pony U32.

In case of system call failure, this function returns the 2-tuple: 1. The value of errno. 2. An undefined value that must be ignored.

fun ref 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 wrapper for UDP sockets to the setsockopt(2) system call.

The caller is responsible for the correct size and byte contents of the option array for the requested level and option_name, including using the appropriate CPU endian byte order.

This function returns 0 on success, else the value of errno on failure.

Usage example:

// listening() is a callback function for class UDPNotify
fun ref listening(sock: UDPSocket ref) =>
  let sb = Writer

  sb.u32_le(7744)             // Our desired socket buffer size
  let sbytes = Array[U8]
  for bs in sb.done().values() do
    sbytes.append(bs)
  end
  match sock.setsockopt(OSSockOpt.sol_socket(), OSSockOpt.so_rcvbuf(), sbytes)
    | 0 =>
      // System call was successful
    | let errno: U32 =>
      // System call failed
  end
fun ref setsockopt(
  level: I32 val,
  option_name: I32 val,
  option: Array[U8 val] ref)
: U32 val

Parameters

Returns


setsockopt_u32

[Source]

Wrapper for UDP sockets to the setsockopt(2) system call where the kernel expects an option value of a C uint32_t type / Pony type U32.

This function returns 0 on success, else the value of errno on failure.

fun ref 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


get_so_error

[Source]

Wrapper for the FFI call getsockopt(fd, SOL_SOCKET, SO_ERROR, ...)

fun ref get_so_error()
: (U32 val , U32 val)

Returns


get_so_rcvbuf

[Source]

Wrapper for the FFI call getsockopt(fd, SOL_SOCKET, SO_RCVBUF, ...)

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

Returns


get_so_sndbuf

[Source]

Wrapper for the FFI call getsockopt(fd, SOL_SOCKET, SO_SNDBUF, ...)

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

Returns


set_ip_multicast_loop

[Source]

Wrapper for the FFI call setsockopt(fd, SOL_SOCKET, IP_MULTICAST_LOOP, ...)

fun ref set_ip_multicast_loop(
  loopback: Bool val)
: U32 val

Parameters

  • loopback: Bool val

Returns


set_ip_multicast_ttl

[Source]

Wrapper for the FFI call setsockopt(fd, SOL_SOCKET, IP_MULTICAST_TTL, ...)

fun ref set_ip_multicast_ttl(
  ttl: U8 val)
: U32 val

Parameters

  • ttl: U8 val

Returns


set_so_broadcast

[Source]

Wrapper for the FFI call setsockopt(fd, SOL_SOCKET, SO_BROADCAST, ...)

fun ref set_so_broadcast(
  state: Bool val)
: U32 val

Parameters

Returns


set_so_rcvbuf

[Source]

Wrapper for the FFI call setsockopt(fd, SOL_SOCKET, SO_RCVBUF, ...)

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

Parameters

  • bufsize: U32 val

Returns


set_so_sndbuf

[Source]

Wrapper for the FFI call setsockopt(fd, SOL_SOCKET, SO_SNDBUF, ...)

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

Parameters

  • bufsize: U32 val

Returns


Private Behaviours

_event_notify

[Source]

When we are readable, we accept new connections until none remain.

be _event_notify(
  event: Pointer[AsioEvent val] tag,
  flags: U32 val,
  arg: U32 val)

Parameters


_read_again

[Source]

Resume reading.

be _read_again()

Private Functions

_pending_reads

[Source]

Read while data is available, guessing the next packet length as we go. If we read 4 kb of data, send ourself a resume message and stop reading, to avoid starving other actors.

fun ref _pending_reads()
: None val

Returns


_complete_reads

[Source]

The OS has informed as that len bytes of pending reads have completed. This occurs only with IOCP on Windows.

fun ref _complete_reads(
  len: U32 val)
: None val

Parameters

Returns


_start_next_read

[Source]

Start our next receive. This is used only with IOCP on Windows.

fun ref _start_next_read()
: None val

Returns


_write

[Source]

Write the datagram to the socket.

fun ref _write(
  data: (String val | Array[U8 val] val),
  to: NetAddress val)
: None val

Parameters

Returns


_notify_listening

[Source]

Inform the notifier that we're listening.

fun ref _notify_listening()
: None val

Returns


_close

[Source]

Inform the notifier that we've closed.

fun ref _close()
: None val

Returns