toss

Work with UDP sockets on the Erlang target.

Types

ConnectedSender

A handle to a socket, which can be used to send datagrams without specifying a destination. This type works as a token of proof that connect has been successfully called at least once. It is still tied to the underlying socket, and is not unique.

pub type ConnectedSender

Error

</>

Errors that can occur when working with UDP sockets.

For more information on these errors see the Erlang documentation.

pub type Error {
  NotOwner
  Timeout
  Eaddrinuse
  Eaddrnotavail
  Eafnosupport
  Ealready
  Econnaborted
  Econnrefused
  Econnreset
  Edestaddrreq
  Ehostdown
  Ehostunreach
  Einprogress
  Eisconn
  Emsgsize
  Enetdown
  Enetunreach
  Enopkg
  Enoprotoopt
  Enotconn
  Enotty
  Enotsock
  Eproto
  Eprotonosupport
  Eprototype
  Esocktnosupport
  Etimedout
  Ewouldblock
  Exbadport
  Exbadseq
  Nxdomain
  Eacces
  Eagain
  Ebadf
  Ebadmsg
  Ebusy
  Edeadlk
  Edeadlock
  Edquot
  Eexist
  Efault
  Efbig
  Eftype
  Eintr
  Einval
  Eio
  Eisdir
  Eloop
  Emfile
  Emlink
  Emultihop
  Enametoolong
  Enfile
  Enobufs
  Enodev
  Enolck
  Enolink
  Enoent
  Enomem
  Enospc
  Enosr
  Enostr
  Enosys
  Enotblk
  Enotdir
  Enotsup
  Enxio
  Eopnotsupp
  Eoverflow
  Eperm
  Epipe
  Erange
  Erofs
  Espipe
  Esrch
  Estale
  Etxtbsy
  Exdev
}

Constructors

```
NotOwner
```
Socket not owned by the process trying to use it. This is documented as an error value in the gen_udp documentation, but it’s unclear how to trigger it.
```
Timeout
```
Operation timed out
```
Eaddrinuse
```
Address already in use
```
Eaddrnotavail
```
Cannot assign requested address
```
Eafnosupport
```
Address family not supported
```
Ealready
```
Operation already in progress
```
Econnaborted
```
Connection aborted
```
Econnrefused
```
Connection refused
```
Econnreset
```
Connection reset by peer
```
Edestaddrreq
```
Destination address required
```
Ehostdown
```
Host is down
```
Ehostunreach
```
No route to host
```
Einprogress
```
Operation now in progress
```
Eisconn
```
Socket is already connected
```
Emsgsize
```
Message too long
```
Enetdown
```
Network is down
```
Enetunreach
```
Network is unreachable
```
Enopkg
```
Package not installed
```
Enoprotoopt
```
Protocol not available
```
Enotconn
```
Socket is not connected
```
Enotty
```
Inappropriate ioctl for device
```
Enotsock
```
Socket operation on non-socket
```
Eproto
```
Protocol error
```
Eprotonosupport
```
Protocol not supported
```
Eprototype
```
Protocol wrong type for socket
```
Esocktnosupport
```
Socket type not supported
```
Etimedout
```
Connection timed out
```
Ewouldblock
```
Operation would block
```
Exbadport
```
Bad port number
```
Exbadseq
```
Bad sequence number
```
Nxdomain
```
Non-existent domain
```
Eacces
```
Permission denied
```
Eagain
```
Resource temporarily unavailable
```
Ebadf
```
Bad file descriptor
```
Ebadmsg
```
Bad message
```
Ebusy
```
Device or resource busy
```
Edeadlk
```
Resource deadlock avoided
```
Edeadlock
```
Resource deadlock avoided
```
Edquot
```
Disk quota exceeded
```
Eexist
```
File exists
```
Efault
```
Bad address
```
Efbig
```
File too large
```
Eftype
```
Inappropriate file type or format
```
Eintr
```
Interrupted system call
```
Einval
```
Invalid argument
```
Eio
```
Input/output error
```
Eisdir
```
Is a directory
```
Eloop
```
Too many levels of symbolic links
```
Emfile
```
Too many open files
```
Emlink
```
Too many links
```
Emultihop
```
Multihop attempted
```
Enametoolong
```
File name too long
```
Enfile
```
Too many open files in system
```
Enobufs
```
No buffer space available
```
Enodev
```
No such device
```
Enolck
```
No locks available
```
Enolink
```
Link has been severed
```
Enoent
```
No such file or directory
```
Enomem
```
Out of memory
```
Enospc
```
No space left on device
```
Enosr
```
Out of streams resources
```
Enostr
```
Device not a stream
```
Enosys
```
Function not implemented
```
Enotblk
```
Block device required
```
Enotdir
```
Not a directory
```
Enotsup
```
Operation not supported
```
Enxio
```
No such device or address
```
Eopnotsupp
```
Operation not supported on socket
```
Eoverflow
```
Value too large for defined data type
```
Eperm
```
Operation not permitted
```
Epipe
```
Broken pipe
```
Erange
```
Result too large
```
Erofs
```
Read-only file system
```
Espipe
```
Illegal seek
```
Esrch
```
No such process
```
Estale
```
Stale file handle
```
Etxtbsy
```
Text file busy
```
Exdev
```
Cross-device link

IpAddress

</>

IP address of a peer

pub type IpAddress {
  Ipv4Address(Int, Int, Int, Int)
  Ipv6Address(Int, Int, Int, Int, Int, Int, Int, Int)
}

Constructors

```
Ipv4Address(Int, Int, Int, Int)
```

Ipv6Address(Int, Int, Int, Int, Int, Int, Int, Int)

Socket

</>

A UDP socket, used to send and receive UDP datagrams.

pub type Socket

SocketOptions

opaque </>

The set of options used to open a socket.

pub opaque type SocketOptions

UdpMessage

</>

Messages that can be sent by the socket to the process that controls it.

pub type UdpMessage {
  Datagram(
    socket: Socket,
    host: Result(IpAddress, Nil),
    peer_port: Int,
    data: BitArray,
  )
  UdpError(Socket, Error)
}

Constructors

Datagram(
  socket: Socket,
  host: Result(IpAddress, Nil),
  peer_port: Int,
  data: BitArray,
)

An incoming UDP datagram

```
UdpError(Socket, Error)
```

Values

close

</>

pub fn close(socket: Socket) -> Nil

Closes the socket, freeing up any resources it uses. The socket and any associated senders can no longer be used after this.

connect_to

</>

pub fn connect_to(
  socket: Socket,
  host: IpAddress,
  port port: Int,
) -> Result(ConnectedSender, Error)

Modifies the socket to only receive data from the specified source. Other messages are discarded on arrival by the OS protocol stack. Returns a handle to the socket, which can be used to send data without specifying the destination every time. Note that multiple calls to connect_to will override any previous calls - all previously returned senders will also change behaviour.

connect_to_host

</>

pub fn connect_to_host(
  socket: Socket,
  host: String,
  port port: Int,
) -> Result(ConnectedSender, Error)

Like connect_to, but uses a host name instead of an IP address. If you have an IP address as a string, convert it first using parse_ip, and use connect_to.

describe_error

</>

pub fn describe_error(error: Error) -> String

Convert an error into a human-readable description

ip_to_string

</>

pub fn ip_to_string(ip: IpAddress) -> String

Converts an IP address to a string.

join_multicast_group

</>

pub fn join_multicast_group(
  socket: Socket,
  multicast_address: IpAddress,
  interface_address: IpAddress,
) -> Result(Nil, Error)

Joins a multicast group on the given local interface.

leave_multicast_group

</>

pub fn leave_multicast_group(
  socket: Socket,
  multicast_address: IpAddress,
  interface_address: IpAddress,
) -> Result(Nil, Error)

Leaves a multicast group on the given local interface.

local_port

</>

pub fn local_port(socket: Socket) -> Result(Int, Nil)

Returns the local port, useful if the socket was opened with port 0

loop_mutlicast

</>

pub fn loop_mutlicast(
  socket: Socket,
  loop: Bool,
) -> Result(Nil, Error)

Sets whether sent multicast packets are looped back to the socket.

new

</>

pub fn new(port port: Int) -> SocketOptions

Constructs the default options to open a socket with, binding it to the given local port. 0 can be used to let the OS automatically choose a free port.

open

</>

pub fn open(options: SocketOptions) -> Result(Socket, Error)

Opens a UDP socket. When freshly opened, the socket will receive data from any source.

prase_ip

</>

pub fn prase_ip(address: String) -> Result(IpAddress, Nil)

Tries to parse an IP address from a string.

receive

</>

pub fn receive(
  socket: Socket,
  max_length max_length: Int,
  timeout_milliseconds timeout: Int,
) -> Result(#(Result(IpAddress, Nil), Int, BitArray), Error)

Receives a UDP datagram from the socket. The source address, port, and the datagram are returned on success. The maximum length will affect memory allocation, so it should be selected conservatively. The address will be an error if the sender does not have a socket address, or the Erlang VM doesn’t recognise the address (toss does currently not support local Unix domain sockets).

receive_forever

</>

pub fn receive_forever(
  socket: Socket,
  max_length max_length: Int,
) -> Result(#(Result(IpAddress, Nil), Int, BitArray), Error)

Receives a UDP datagram from the socket, without a timeout. See receive for details.

receive_next_datagram_as_message

</>

pub fn receive_next_datagram_as_message(
  socket: Socket,
) -> Result(Nil, Error)

Switch the socket to active (once) mode, meaning that the next datagram received on the socket will be sent as an Erlang message to the socket owner’s inbox.

This is useful for when you wish to have an OTP actor handle incoming messages, as using the receive function would result in the actor being blocked and unable to handle other messages while waiting for the next packet.

Messages will be sent to the process that controls the socket, which is the process that established the socket with the open function.

In order to continue receiving messages, you will need to call this function again after receiving a message. This is intended to provide backpressure to the OS socket, instead of flooding the inbox on the Erlang side, which could happen if switching to full active mode.

reuse_address

</>

pub fn reuse_address(options: SocketOptions) -> SocketOptions

Allows reusing an already open local address and port Otherwise, an error will be returned from open, if a socket on the port is already open.

select_udp_messages

</>

pub fn select_udp_messages(
  selector: process.Selector(a),
  mapper: fn(UdpMessage) -> a,
) -> process.Selector(a)

Configure a selector to receive messages from UDP sockets. You will also need to call receive_next_datagram_as_message to use the selector successfully - once initially, and again after receiving each message.

Note that this will receive messages from all UDP sockets that the process controls, rather than any specific one. If you wish to only handle messages from one socket then use one process per socket.

send

</>

pub fn send(
  sender: ConnectedSender,
  data: BitArray,
) -> Result(Nil, Error)

Sends a UDP datagram to the peer of a connected socket.

send_to

</>

pub fn send_to(
  socket: Socket,
  host: IpAddress,
  port: Int,
  data: BitArray,
) -> Result(Nil, Error)

Sends a UDP datagram to the specified destination by IP address.

send_to_host

</>

pub fn send_to_host(
  socket: Socket,
  host: String,
  port: Int,
  data: BitArray,
) -> Result(Nil, Error)

Sends a UDP datagram to the specified destination by hostname.

use_ipv4

</>

pub fn use_ipv4(options: SocketOptions) -> SocketOptions

Specifies to open the socket in IPv4 mode. You can not send to IPv6 addresses when opening a socket with this option.

use_ipv6

</>

pub fn use_ipv6(options: SocketOptions) -> SocketOptions

Specifies to open the socket in IPv6 mode. On dual stack systems, you can send to IPv4-mapped IPv6 addresses, and respectively datagrams received from IPv4 addresses will have an address in the IPv4-mapped format.

using_interface

</>

pub fn using_interface(
  options: SocketOptions,
  ip: IpAddress,
) -> SocketOptions

If the local host has multiple interfaces, specifies which one to use by IP address.