4.90. kink/socket/SELECTOR

4.90.1. type selector

Restriction of the current implementation

In the current implementation, when you unregister a socket from a selector, then call register_xxx method for the same socket and the selector before calling `select` method, it will result in an IO error. This is due to behavior of Java's SelectedChannel.register method.

4.90.1.1. Sel.close(...[$config_fun={}])

`close` method closes the selector.

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

If an IO error occurs, `close` tail-calls the error cont.

Precondition

• $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 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` 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.90.1.2. Sel.register_read(Sock ...[$config_fun={}])

register_read method sets Sock registered to the selector, as waiting for only read-like operations.

Read-like operations include:

• `accept` of tcp_server

• `read` of the input of tcp_connection and udp_socket

Sock is registered to the selector with an attached val specified by C.attach. If C.attach is not called, Sock itself is used as the attached val.

If Sock is successfully registered, register_read tail-calls the success cont with no arg.

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

Preconditions

• Sock must be a val of tcp_server, tcp_connection, or udp_socket type.

• Sock must be in non-blocking mode.

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

Config val methods

• C.attach(Attached): Attached will be returned as a part of the result of `select` method, instead of Sock.

• C.on_success($success): specifies the success cont. $success must be a fun which does not take an argument. 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. $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.90.1.3. Sel.register_write(Sock ...[$config_fun={}])

register_write method sets Sock registered to the selector, as waiting for only write-like operations.

Write-like operations include:

• finish_connect of tcp_connection

• `write` of the output of tcp_connection and udp_socket

Sock is registered to the selector with an attached val specified by C.attach. If C.attach is not called, Sock itself is used as the attached val.

If Sock is successfully registered, register_write tail-calls the success cont with no arg.

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

Preconditions

• Sock must be a val of tcp_connection or udp_socket type.

• Sock must be in non-blocking mode.

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

Config val methods

• C.attach(Attached): Attached will be returned as a part of the result of `select` method, instead of Sock.

• C.on_success($success): specifies the success cont. $success must be a fun which does not take an argument. 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. $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.90.1.4. Sel.register_read_write(Sock ...[$config_fun={}])

register_read_write method set Sock registered to the selector, as waiting for both read-like and write-like operations.

For read-like operations, see `register_read`. For write-like operations, see `register_write`.

Sock is registered to the selector with an attached val specified by C.attach. If C.attach is not called, Sock itself is used as the attached val.

If Sock is successfully registered, register_read_write tail-calls the success cont with no arg.

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

Preconditions

• Sock must be a val of tcp_connection or udp_socket type.

• Sock must be in non-blocking mode.

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

Config val methods

• C.attach(Attached): Attached will be returned as a part of the result of `select` method, instead of Sock.

• C.on_success($success): specifies the success cont. $success must be a fun which does not take an argument. 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. $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.90.1.5. Sel.unregister(Sock)

`unregister` method sets Sock not registered in the selector.

It is acceptable that Sock is not currently registered to the selector.

Precondition

• Sock must be a val of tcp_server, tcp_connection, or udp_socket type.

4.90.1.6. Sel.select(...[$config_fun={}])

`select` method selects sockets which are ready for IO operations.

`select` method blocks until:

• (a) one or more operations for registered sockets become ready,

• (b) the timeout passed,

• (c) Sel.unblock is called in a different thread,

• (d) or an IO error occurs.

In cases (a), (b), or (c), `select` tail-calls the success cont with a vec [Reads Writes], where Reads is a vec of the attached vals of the registered sockets for which a read-like operation is ready, and Writes is a vec of the attached vals of the registered sockets for which a write-like operation is ready.

In the case (d), that is, when an IO error occurs, `select` tail-calls the error cont with a `str` val as the error message.

Precondition

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

Config val methods

• C.timeout(Seconds): specifies the timeout in the unit of seconds. Seconds must be a non-negative num, with an arbitrary scale. If Seconds is zero, the invocation of `select` method will return immediately. If Seconds is too big, like over 24 hours, it might be curtailed to a decent val.

• C.on_success($success): specifies the success cont. $success must be a fun. If C.on_success is not called, a fun like `{([:R :W]) [R W] }` is used as the default success cont.

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

4.90.1.7. Sel.unblock

`unblock` method unblocks invocation of `select` method.

If there is an ongoing invocation of `select`, it is unblocked immediately.

If there is no invocation of `select` which is in progress, the next invocation of `select` will return immediately.

4.90.2. SELECTOR.open(...[$config_fun={}])

`open` fun opens a new `selector` val.

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

If an IO error occurs, `open` tail-calls the error cont with a `str` val 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. $success must be a fun which takes a `selector` 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` as the error message. If on_error is not called, a fun which raises an exception is used as the default error cont.

4.90.3. SELECTOR.is?(Val)

`is?` method returns whether `Val` is a val of `selector` type.