# Module `selector` - IO selector

IO selector.

An IO selector is a server that waits in an efficient way for events on a set of file descriptors; it provides a process-oriented interface to the `poll(2)` system call (or an equivalent).

To start an IO selector, call `selector.start`; see `SELECTOR.CT` for the interface.

## Index

- Group `SELECT` - Events to select upon
  - Constant `SELECT.READ` - A read will not block
  - Constant `SELECT.WRITE` - A write will not block
- Channel type `SELECTOR.CT` - Interface to an IO selector
- Protocol `SELECTOR.REQ` - Requests to an IO selector
  - Tag `add` - Add a file descriptor to the set being waited upon
  - Tag `shutdown` - Shut down the selector
- Channel type `SELECTOR.SIGNAL` - Channel bundle used for the selector to signal back to the client
- Protocol `SELECTOR.SIGNAL.REQ` - Requests from an IO selector to a waiting process
  - Tag `ready` - The FD has become ready
  - Tag `shutdown` - The selector is shutting down
- Protocol `SELECTOR.SIGNAL.RESP` - Responses from a waiting process to an IO selector
  - Tag `again` - Wait for the FD again
  - Tag `remove` - Remove the FD from the waiting set
- Process `selector.add` - Register a file descriptor with a selector
- Process `selector.delayed.add` - Register a file descriptor with a selector, then send the new signal end down a shared channel
- Process `selector.make.nonblocking` - Make a file descriptor non-blocking
- Process `selector.start` - Start an IO selector

## Declarations

### `selector.occ`:34Process `selector.make.nonblocking`

`PROC selector.make.nonblocking (VAL INT fd)`

Make a file descriptor non-blocking. This just sets the `O.NONBLOCK` flag on the FD.

#### Parameters:

`VAL INT` | `fd` | File descriptor

### `selector.occ`:42Process `selector.add`

`PROC selector.add (SHARED SELECTOR.CT! sel, VAL INT fd, events, RESULT SELECTOR.SIGNAL? svr)`

Register a file descriptor with a selector.

### `selector.occ`:58Process `selector.delayed.add`

`PROC selector.delayed.add (SHARED SELECTOR.CT! sel, VAL INT fd, events, SHARED CHAN SELECTOR.SIGNAL? svr.out!)`

Register a file descriptor with a selector, then send the new signal end down a shared channel.

Why would you want to do this? It's to avoid a client-server loop if you've got a client that wants to change the set of FDs it selects on: rather than having it add the FD itself (which would mean switching the direction of the client-server relationship), have it fork off this process.

### `selector.occ`:68Process `selector.start`

`PROC selector.start (RESULT SHARED SELECTOR.CT! sel)`

Start an IO selector.

### `selector.inc`:31Group `SELECT`

``

Events to select upon.

### `selector.inc`:32Constant `SELECT.READ`

`VAL INT SELECT.READ`

A read will not block.

### `selector.inc`:33Constant `SELECT.WRITE`

`VAL INT SELECT.WRITE`

A write will not block.

### `selector.inc`:37Protocol `SELECTOR.SIGNAL.REQ`

`PROTOCOL SELECTOR.SIGNAL.REQ`

Requests from an IO selector to a waiting process.

### `selector.inc`:40Tag `ready`

`ready = 0`

The FD has become ready.

### `selector.inc`:42Tag `shutdown`

`shutdown = 1`

The selector is shutting down.

### `selector.inc`:46Protocol `SELECTOR.SIGNAL.RESP`

`PROTOCOL SELECTOR.SIGNAL.RESP`

Responses from a waiting process to an IO selector.

### `selector.inc`:49Tag `again`

`again = 0`

Wait for the FD again.

### `selector.inc`:51Tag `remove`

`remove = 1`

Remove the FD from the waiting set.

### `selector.inc`:58Channel type `SELECTOR.SIGNAL`

`CHAN TYPE SELECTOR.SIGNAL`

Channel bundle used for the selector to signal back to the client.

This may look dodgy from a C-S perspective, but it should be OK: at any given time, the client-server relationship is only going one way...

### `selector.inc`:65Protocol `SELECTOR.REQ`

`PROTOCOL SELECTOR.REQ`

Requests to an IO selector.

### `selector.inc`:71Tag `add`

`add = 0; INT; INT; SELECTOR.SIGNAL!`

Add a file descriptor to the set being waited upon.

#### Parameters:

`INT` | `fd` | File descriptor (usually non-blocking)
`INT` | `events` | Bitwise OR of events to wait for; see `SELECT`
`SELECTOR.SIGNAL!` | `signal` | Channel bundle to signal over when the event fires

### `selector.inc`:73Tag `shutdown`

`shutdown = 1`

Shut down the selector.

### `selector.inc`:77Channel type `SELECTOR.CT`

`CHAN TYPE SELECTOR.CT`

Interface to an IO selector.