4.89. kink/socket/TCP_CONNECTION

Provides `tcp_connection` type.

4.89.1. type tcp_connection

`tcp_connection` is a stream-based connecting socket. The protocol can be either TCP/IP, or stream based Unix domain socket.

4.89.1.1. Conn.connect(Remote ...[$config_fun={}])

`connect` method tries to connect this socket to the remote address specified by `Remote`.

In blocking mode

If the socket is in blocking mode, `connect` waits until connection is established, or an IO error occurs.

If connection is established, `connect` tail-calls the success cont with no arg. The client can read data from, or write data to the socket.

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

In non-blocking mode

If the socket is in non-blocking mode, `connect` does not wait for establishment of connection.

If connection is established immediately, `connect` tail-calls the success cont with no arg. The client can read data from, or write data to the socket.

If connection is not yet established, `connect` tail-calls the partial cont with no arg. In that case, the client must call `finish_connect` until connection is established, before reading data from, or writing data to the socket.

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`. It must match th protocol family of the socket.

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

Config val

A config val has the following methods:

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

• C.on_partial($partial): specifies the partial cont. A partial cont must be a fun which takes no arg. If `on_partial` is not called, a fun which raises an exception is used as the default partial cont.

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

4.89.1.2. Conn.finish_connect(...[$config_fun={}])

`finish_connect` method tries to finish connection attempt started by `connect` method.

In blocking mode

If the socket is in blocking mode, `finish_connect` waits until connection is established, or an IO error occurs.

If connection is established, `finish_connect` tail-calls the success cont with no arg. The client can read data from, or write data to the socket.

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

In non-blocking mode

If the socket is in non-blocking mode, `finish_connect` does not wait for establishment of connection.

If connection is established immediately, `finish_connect` tail-calls the success cont with no arg. The client can read data from, or write data to the socket.

If connection is not yet established, `finish_connect` tail-calls the partial cont with no arg. In that case, the client must call `finish_connect` until connection is established, before reading data from, or writing data to the socket.

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

Preconditions

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

Config val

A config val has the following methods:

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

• C.on_partial($partial): specifies the partial cont. A partial cont must be a fun which takes no arg. If `on_partial` is not called, a fun which raises an exception is used as the default partial cont.

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

4.89.1.3. Conn.bind(Local ...[$config_fun])

`bind` methods binds a local address specified by `Local` to the socekt.

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 wit 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.89.1.4. Conn.close(...[$config_fun={}])

`close` 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 an 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.89.1.5. Conn.input(...[$config_fun={}])

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

Config val method

• C.buffer(...[Buf_size]): turns on buffering of the input, and specifies `Buf_size` as the buffer size if provided. `Buf_size` must be a positive int num.

4.89.1.6. Conn.output(...[$config_fun={}])

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

Config val method

• C.buffer(...[Buf_size]): turns on buffering of the output, and specifies `Buf_size` as the buffer size if provided. `Buf_size` must be a positive int num.

4.89.1.7. Conn.local_address(...[$config_fun={}])

`local_address` method retrieves a socket_address val of the local address of the connecting 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.89.1.8. Conn.remote_address(...[$config_fun={}])

`remote_address` method retrieves a socket_address val of the remote address of the connecting 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.89.1.9. Conn.blocking?

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

4.89.1.10. Conn.set_blocking

`set_blocking` method turns on blocking mode.

4.89.1.11. Conn.unset_blocking

`unset_blocking` method turns off blocking mode. It sets the connecting socket in non-blocking mode.

4.89.1.12. Conn.tcp_nodelay?

`tcp_nodelay?` method returns a bool val of TCP_NODELAY option.

Precondition: The protocol family must be ipv4 or ipv6.

4.89.1.13. Conn.set_tcp_nodelay

`set_tcp_nodelay` method turns on TCP_NODELAY option.

Precondition: The protocol family must be ipv4 or ipv6.

4.89.1.14. Conn.unset_tcp_nodelay

`unset_tcp_nodelay` method turns off TCP_NODELAY option.

Precondition: The protocol family must be ipv4 or ipv6.

4.89.1.15. Conn.so_keepalive?

`so_keepalive?` method returns a bool val of SO_KEEPALIVE option.

Precondition: The protocol family must be ipv4 or ipv6.

4.89.1.16. Conn.set_so_keepalive

`set_so_keepalive` method turns on SO_KEEPALIVE option.

Precondition: The protocol family must be ipv4 or ipv6.

4.89.1.17. Conn.unset_so_keepalive

`unset_so_keepalive` method turns off SO_KEEPALIVE option.

Precondition: The protocol family must be ipv4 or ipv6.

4.89.1.18. Conn.so_reuseaddr?

`so_reuseaddr?` method returns a bool val of SO_REUSEADDR option.

Precondition: The protocol family must be ipv4 or ipv6.

4.89.1.19. Conn.set_so_reuseaddr

`set_so_reuseaddr` method turns on SO_REUSEADDR option.

Precondition: The protocol family must be ipv4 or ipv6.

4.89.1.20. Conn.unset_so_reuseaddr

`unset_so_reuseaddr` method turns off SO_REUSEADDR option.

Precondition: The protocol family must be ipv4 or ipv6.

4.89.1.21. Conn.so_linger

`so_linger` method returns SO_LINGER option.

If SO_LINGER option is turned on, `so_linger` returns a singleton vec of the int num of the option value.

If SO_LINGER option is turned off, `so_linger` returns an empty vec.

Precondition: The protocol family must be ipv4 or ipv6.

4.89.1.22. Conn.set_so_linger(Seconds)

`set_so_linger` method turns on SO_LINGER option, and sets `Seconds` as the value.

Preconditions

• The protocol family must be ipv4 or ipv6.

• `Seconds` must be a non-negative int num.

4.89.1.23. Conn.unset_so_linger

`unset_so_linger` method turns off SO_LINGER option.

Precondition: The protocol family must be ipv4 or ipv6.

4.89.1.24. Conn.so_sndbuf

`so_sndbuf` method returns the int num of SO_SNDBUF option.

4.89.1.25. Conn.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.89.1.26. Conn.so_rcvbuf

`so_rcvbuf` method returns the int num of SO_RCVBUF option.

4.89.1.27. Conn.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.89.2. TCP_CONNECTION.open(Protocol_family ...[$config_fun={}])

`open` makes a new connecting socket. The newly created connecting socket is in blocking mode.

Preconditions

• Protocol_family must be a `protocol_family`.

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

Config val

A config val supports the following methods.

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

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

• C.on_unsupported($unsupported): specifies the unsupported cont. An unsupported cont must be a fun which takes no argument. If `on_unsupported` is not called, a fun which tail-calls the error cont with an error message is used as the default.

Result

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

If the specified protocol family is not supported by the runtime, `open` tail-calls the unsupported cont.

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

4.89.3. TCP_CONNECTION.is?(Val)

`is?` returns whether `Val` is a tcp_connection val.