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={}])¶
`connect` sets the remote address to the socket.
Config methods:
• C.on_success($success): default = {}
• C.on_error($error): default = {(:Exc) Exc.raise }
If the address is successfully set, `connect` tail-calls $success with no arg.
If an IO error occurs, `connect` tail-calls $error with an `exception`.
Preconditions
• `Remote` must be a socket_address, whose protocol family is acceptable by the socket.
• $success must be a fun which takes no arg.
• $error must be a fun which takes an `exception`.
5.95.1.2. Udp.bind(Local ...[$config={}])¶
`bind` binds a local address to the socket.
Config methods:
• C.on_success($success): default = {}
• C.on_error($error): default = {(:Exc) Exc.raise }
If the address is successfully bound, `bind` tail-calls $success with no arg.
If an IO error occurs, `bind` tail-calls $error with an `exception`.
Preconditions
• `Local` must be a `socket_address`, whose protocol family matches one of the socket.
• $success must be a fun which takes no arg
• $error must be a fun which takes an `exception`
5.95.1.3. Udp.close(...[$config={}])¶
`close` closes the socket.
Config methods:
• C.on_success($success): default = {}
• C.on_error($error): default = {(:Exc) Exc.raise }
If the socket is closed successfully, `close` tail-calls $success with no arg.
If an IO error occurs, `close` tail-calls $error with an `exception`.
Preconditions
• $success must be a fun which takes no arg
• $error must be a fun which takes an `exception`
5.95.1.4. Udp.receive(Max_size ...[$config={}])¶
`receive` method receives a datagram on the socket.
Config methods:
• C.on_success($success): default = VAL.identity
• C.on_error($error): default = {(:Exc) Exc.raise }
`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, or an IO error occurs. `receive` tail-calls $success with a `datagram`. If an IO error occurs, `receive` tail-calls $error with an `exception`.
Preconditions
• `Max_size` must be a non-negative int num
• $success must be a fun which takes an `datagram`.
• $error must be a fun which takes an `exception`.
5.95.1.5. Udp.send(Datagram ...[$config={}])¶
`send` sends a datagram to the specified destination.
Config methods:
• C.on_success($success): default = {}
• C.on_error($error): default = {(:Exc) Exc.raise }
`send` waits until write buffer is available, or an IO error occurs.
If the datagram is written to the write buffer, `send` tail-calls $success with no arg.
If an IO error occurs, `send` tail-calls $error with an `exception`.
Preconditions
• `Datagram` must be a val of `datagram` type.
• The protocol family of the remote address of `Datagram` must be accepted by the socket.
• $success must be a fun which takes no arg.
• $error must be a fun which takes an `exception`.
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={}])¶
`local_address` retrieves a `socket_address` of the local address of the socket.
Config methods:
• C.on_success($success): default = VAL.identity
• C.on_error($error): default = {(:Exc) Exc.raise }
If the local address is available, `local_address` tail-calls $success with the `socket_address`.
If an IO error occurs, `local_address` tail-calls $error with an `exception`.
Preconditions
• $success must be a fun which takes a `socket_address`.
• $error must be a fun which takes an `exception`.
5.95.1.9. Udp.remote_address(...[$config={}])¶
`remote_address` retrieves a `socket_address` of the remote address of the socket.
Config methods:
• C.on_success($success): default = VAL.identity
• C.on_error($error): default = {(:Exc) Exc.raise }
If the remote address is available, `remote_address` tail-calls $success with the `socket_address`.
If an IO error occurs, `remote_address` tail-calls $error with an `exception`.
Preconditions
• $success must be a fun which takes a `socket_address`.
• $error must be a fun which takes an `exception`.
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={}])¶
`open` makes a new datagram socket. The newly created socket is in blocking mode.
Config methods:
• C.on_success($success): default = VAL.identity
• C.on_error($error): default = {(:Exc) Exc.raise }
• C.on_unsupported($unsupported): default = a fun which tail-calls $error
If a socket is created, `open` tail-calls $success with the `udp` val.
If an IO error occurs, `open` tail-calls $error with an `exception`.
If `Protocol_family` is not supported by the runtime, `open` tail-calls $unsupported with no arg.
Preconditions
• Protocol_family must be a protocol_family val.
• $success must be a fun which takes a `udp`.
• $error must be a fun which takes an `exception`.
• $unsupported must be a fun which takes no arg.
5.95.3. UDP.is?(Val)¶
`is?` method returns whether `Val` is a `udp` val.