5.95. kink/socket/UDP

5.95.1. type udp

A `udp` is a socket of a message based protocol.

Currently, UDP on IPv4 and IPv6 are supported. The following features are not supported:

• Unix domain datagram socket

• Multicast

• IP_PKTINFO and IPV6_PKTINFO on Linux, and corresponding features on other OSes

5.95.1.1. Udp.connect(Remote ...[$config_fun={}])

`connect` method sets the remote address to the socket.

If the address is successfully set, `connect` tail-calls the success cont with no arg.

If an IO error occurs, `connect` tail-calls the error cont with a str as an error message.

Preconditions

• `Remote` must be a socket_address, whose protocol family matches one of the socket.

• $config_fun must be a fun which takes a config val.

Config val methods

• C.on_success($success): specifies the success cont. If `on_success` is not called, a NOP fun like `{}` is used as the default success cont.

• C.on_error($error): specifies the error cont. If `on_error` is not called, a fun which raises an exception is used as the default error cont.

5.95.1.2. Udp.bind(Local ...[$config_fun={}])

`bind` method binds a local address to the socket.

If the address is successfully bound, `bind` tail-calls the success cont with no arg.

If an IO error occurs, `bind` tail-calls the error cont with a str as an error message.

Preconditions

• `Local` must be a `socket_address`, whose protocol family matches one of the socket.

• $config_fun must be a fun which takes a config val.

Config val methods

• C.on_success($success): specifies the success cont. If `on_success` is not called, a NOP fun like `{}` is used as the default success cont.

• C.on_error($error): specifies the error cont. If `on_error` is not called, a fun which raises an exception is used as the default error cont.

5.95.1.3. Udp.close(...[$config_fun={}])

`close` method closes the socket.

If the socket is successfully closed, `close` tail-calls the success cont with no arg.

If an IO error occurs, `close` tail-calls the error cont with a str as the error message.

Precondition

• $config_fun must be a fun which takes a config val.

Config val methods

• C.on_success($success): specifies the success cont. If on_success is not called, a NOP fun like `{}` is used as the default success cont.

• C.on_error($error): specifies the error cont. If on_error is not called, a fun which raises an exception is used as the default error cont.

5.95.1.4. Udp.receive(Max_size ...[$config_fun={}])

`receive` method receives a datagram on the socket.

Max_size is the maximum byte count of the datagram to receive. If the datagram is longer than the specified length, it is shortened to Max_size.

`receive` method waits until a datagram is available. If a datagram becomes available, `receive` tail-calls the success cont with a `datagram` val. If an IO error occurs, `receive` tail-calls the error cont with a `str` val as the error message.

Preconditions

• Max_size must be a non-negative int num

• $config_fun must be a fun which takes a config val

Config val methods

• C.on_success($success): specifies the success cont. $success must be a fun which taks a `datagram` val. If on_success is not called, VAL.identity is used as the default success cont.

• C.on_error($error): specifies the error cont. $error must be a fun which takes a `str` val as the error message. If on_error is not called, a fun which raises an exception is used as the default error cont.

5.95.1.5. Udp.send(Datagram ...[$config_fun={}])

`send` method sends a datagram to the specified destination.

`send` waits until write buffer is available. If the datagram is written to the write buffer, `send` method tail-calls the success cont with no arg. If an IO error occurs, `send` method tail-calls the error cont with a str as the error message.

Preconditions

• `Datagram` must be a val of `datagram` type.

• $config_fun must be a fun which takes a config val.

Config val methods

• C.on_success($success): specifies the success cont. $success must be a fun which takes no arg. If on_success method is not called, a NOP fun like `{}` is used as the default success cont.

• C.on_error($error): specifies the error cont. $error must be a fun which takes a str. If on_error method is not called, a fun which raises an exception is used as the default error cont.

5.95.1.6. Udp.input

`input` makes an `input` of the socket.

Closing the input will close the socket.

5.95.1.7. Udp.output

`output` method makes an `output` of the socket.

Closing the output will close the socket.

5.95.1.8. Udp.local_address(...[$config_fun={}])

local_address method retrieves a socket_address val of the local address of the socket.

If the local address is available, local_address tail-calls the present cont with the socket_address val.

If the local address is not available, local_address tail-calls the absent cont with no arg.

If an IO error occurs, local_address tail-calls the error cont with a str as an error message.

Config val method

• C.on_present($present): specifies the present cont.

• C.on_absent($absent): specifies the absent cont.

• C.on_error($error): specifies the error cont.

5.95.1.9. Udp.remote_address(...[$config_fun={}])

remote_address method retrieves a socket_address val of the remote address of the socket.

If the remote address is available, remote_address tail-calls the present cont with the socket_address val.

If the remote address is not available, remote_address tail-calls the absent cont with no arg.

If an IO error occurs, remote_address tail-calls the error cont with a str as an error message.

Config val method

• C.on_present($present): specifies the present cont.

• C.on_absent($absent): specifies the absent cont.

• C.on_error($error): specifies the error cont.

5.95.1.10. Udp.so_sndbuf

so_sndbuf method returns the int num of SO_SNDBUF option.

5.95.1.11. Udp.set_so_sndbuf(Buf_size)

set_so_sndbuf method sets Buf_size as SO_SNDBUF option.

Precondition: `Buf_size` must be a non-negative int num.

5.95.1.12. Udp.so_rcvbuf

so_rcvbuf method returns the int num of SO_RCVBUF option.

5.95.1.13. Udp.set_so_rcvbuf(Buf_size)

set_so_rcvbuf method sets Buf_size as SO_RCVBUF option.

Precondition: Buf_size must be a non-negative int num.

5.95.1.14. Udp.so_reuseaddr?

so_reuseaddr? method returns a bool val of SO_REUSEADDR option.

5.95.1.15. Udp.set_so_reuseaddr

set_so_reuseaddr method turns on SO_REUSEADDR option.

5.95.1.16. Udp.unset_so_reuseaddr

unset_so_reuseaddr method turns off SO_REUSEADDR option.

5.95.1.17. Udp.so_broadcast?

so_broadcast? method returns a bool val of SO_BROADCAST option.

5.95.1.18. Udp.set_so_broadcast

set_so_broadcast method turns on SO_BROADCAST option.

5.95.1.19. Udp.unset_so_broadcast

unset_so_broadcast method turns off SO_BROADCAST option.

5.95.2. UDP.open(...[Protocol_family=PROTOCOL_FAMILY.ipv6 $config_fun={}])

`open` method makes a new message oriented socket. The newly created listening socket is in blocking mode.

If a socket is created, `open` tail-calls the success cont with the `udp` val.

If an IO error occurs, `open` tail-calls the error cont with a str as the error message.

If Protocol_family is not supported, `open` tail-calls the unsupported cont with no arg.

Preconditions

• Protocol_family must be a protocol_family val.

• $config_fun must be a fun which takes a config val.

Config val methods

• C.on_success($success): specifies $success as the success cont. $success must be a fun which takes a `udp` val. If on_success method is not called, VAL.identity is used as the default success cont.

• C.on_error($error): specifies $error as the error cont. $error must be a fun which takes a str as the error message. If on_error method is not called, a fun which raises an exception is used as the default error cont.

• C.on_unsupported($unsupported): specifies $unsupported as the unsupported cont. $unsupported must be a thunk. If on_unsupported method is not called, a fun which tail-calls the error cont is used as the default unsupported cont.

5.95.3. UDP.is?(Val)

`is?` method returns whether `Val` is a `udp` val.