4.91. kink/socket/UDP_SOCKET

4.91.1. type udp_socket

udp_socket type 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

4.91.1.1. Sock.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.

4.91.1.2. Sock.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.

4.91.1.3. Sock.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.

4.91.1.4. Sock.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.

In blocking mode

If the socket is in blocking mode, `receive` method waits until a datagram is available.

If a datagram becomes available, `receive` tail-calls the present cont with a `datagram` val.

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

In non-blocking mode

If the socket is in non-blocking mode, `receive` method does not wait until a datagram is available.

If a datagram is immediately available, `receive` tail-calls the present cont with a `datagram` val.

If a datagram is not immediately available, `receive` tail-calls the absent cont with no arg.

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_present($present): specifies the present cont. $present must be a fun which taks a `datagram` val. If on_present is not called, VAL.identity is used as the default present cont.

• C.on_absent($absent): specifies the absent cont. $absent must be a thunk. If on_absent is not called, a fun which raises an exception is used as the default absent 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.

4.91.1.5. Sock.send(Datagram ...[$config_fun={}])

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

In blocking mode

If the socket is in blocking mode, `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.

In non-blocking mode

If the socket is in blocking mode, `send` method does not wait until there is sufficient room in the write buffer.

If the whole datagram is immediately written to the write buffer, `send` method tail-calls the success cont with no arg.

If not the whole datagram is written, `send` method tail-calls the partial cont with an int num as the number of written bytes.

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_partial($partial): specifies the partial cont. $partial must be a fun which takes an int num. If on_partial method is not called, a fun which raises an exception is used as the default partial 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.

4.91.1.6. Sock.input

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

Closing the input will close the socket.

4.91.1.7. Sock.output

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

Closing the output will close the socket.

4.91.1.8. Sock.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.

4.91.1.9. Sock.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.

4.91.1.10. Sock.blocking?

blocking? method returns whether the socket is in blocking mode.

4.91.1.11. Sock.set_blocking

set_blocking method turns on blocking mode.

4.91.1.12. Sock.unset_blocking

unset_blocking method turns off blocking mode.

4.91.1.13. Sock.so_sndbuf

so_sndbuf method returns the int num of SO_SNDBUF option.

4.91.1.14. Sock.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.

4.91.1.15. Sock.so_rcvbuf

so_rcvbuf method returns the int num of SO_RCVBUF option.

4.91.1.16. Sock.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.

4.91.1.17. Sock.so_reuseaddr?

so_reuseaddr? method returns a bool val of SO_REUSEADDR option.

4.91.1.18. Sock.set_so_reuseaddr

set_so_reuseaddr method turns on SO_REUSEADDR option.

4.91.1.19. Sock.unset_so_reuseaddr

unset_so_reuseaddr method turns off SO_REUSEADDR option.

4.91.1.20. Sock.so_broadcast?

so_broadcast? method returns a bool val of SO_BROADCAST option.

4.91.1.21. Sock.set_so_broadcast

set_so_broadcast method turns on SO_BROADCAST option.

4.91.1.22. Sock.unset_so_broadcast

unset_so_broadcast method turns off SO_BROADCAST option.

4.91.2. UDP_SOCKET.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_socket 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_socket 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.

4.91.3. UDP_SOCKET.is?(Val)

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