# `./fio-stl/102 poll api.h`

16 public symbols.

### Macros

#### `FIO_POLL_POSSIBLE_FLAGS`

```c
#define FIO_POLL_POSSIBLE_FLAGS (POLLIN | POLLOUT | POLLPRI)
```

The user flags IO events recognize

_Symbol type:_ `macro`

#### `FIO_POLL_MAX_EVENTS`

```c
#define FIO_POLL_MAX_EVENTS 256
```

relevant only for epoll and kqueue - maximum number of events per review

_Symbol type:_ `macro`

#### `FIO_POLL_ENGINE_EPOLL`

```c
#define FIO_POLL_ENGINE_EPOLL
```



_Symbol type:_ `macro`

#### `FIO_POLL_ENGINE_KQUEUE`

```c
#define FIO_POLL_ENGINE_KQUEUE
```



_Symbol type:_ `macro`

#### `FIO_POLL_ENGINE_POLL`

```c
#define FIO_POLL_ENGINE_POLL
```



_Symbol type:_ `macro`

#### `FIO_POLL_ENGINE_STR`

```c
#define FIO_POLL_ENGINE_STR "epoll"
```



_Symbol type:_ `macro`

#### `FIO_POLL_VALIDATE`

```c
#define FIO_POLL_VALIDATE(settings_dest)   \
  if (!(settings_dest).on_data)   \
    (settings_dest).on_data = fio___poll_ev_mock;   \
  if (!(settings_dest).on_ready)   \
    (settings_dest).on_ready = fio___poll_ev_mock;   \
  if (!(settings_dest).on_close)   \
    (settings_dest).on_close = fio___poll_ev_mock;
```



_Symbol type:_ `macro`

### Types

#### `fio_poll_s`

```c
struct fio_poll_s
```

the `fio_poll_s` type should be considered opaque.

_Symbol type:_ `type`

#### `fio_poll_settings_s`

```c
typedef struct {
/** callback for when data is available in the incoming buffer. */
void (*on_data)(void *udata);
/** callback for when the outgoing buffer allows a call to `write`. */
void (*on_ready)(void *udata);
/** callback for closed connections and / or connections with errors. */
void (*on_close)(void *udata);
} fio_poll_settings_s
```



_Symbol type:_ `type`

### Functions

#### `fio_poll_init`

```c
inline void fio_poll_init(fio_poll_s *p, fio_poll_settings_s)
```

Initializes the polling object, allocating its resources.

_Symbol type:_ `function`

#### `fio_poll_init`

```c
#define fio_poll_init(p, ...)   \
  fio_poll_init((p), (fio_poll_settings_s){__VA_ARGS__})
```

Initializes the polling object, allocating its resources.

_Note:_ this may be a macro only / macro wrapper for a function.

_Symbol type:_ `macro`

#### `fio_poll_destroy`

```c
inline void fio_poll_destroy(fio_poll_s *p)
```

Destroys the polling object, freeing its resources.

_Symbol type:_ `function`

#### `fio_poll_engine`

```c
inline const char *fio_poll_engine(void)
```

returns the system call used for polling as a constant string.

_Symbol type:_ `function`

#### `fio_poll_monitor`

```c
int fio_poll_monitor(fio_poll_s *p, fio_socket_i fd, void *udata, unsigned short flags)
```

Adds a file descriptor to be monitored, adds events to be monitored or
updates the monitored file's `udata`.

Possible flags are: `POLLIN` and `POLLOUT`. Other flags may be set but might
be ignored.

Monitoring mode is always one-shot. If an event if fired, it is removed from
the monitoring state.

Returns -1 on error.

_Symbol type:_ `function`

#### `fio_poll_review`

```c
int fio_poll_review(fio_poll_s *p, size_t timeout)
```

Reviews if any of the monitored file descriptors has any events.

`timeout` is in milliseconds.

Returns the number of events called.

Polling is thread safe, but has different effects on different threads.

Adding a new file descriptor from one thread while polling in a different
thread will not poll that IO until `fio_poll_review` is called again.

_Symbol type:_ `function`

#### `fio_poll_forget`

```c
int fio_poll_forget(fio_poll_s *p, fio_socket_i fd)
```

Stops monitoring the specified file descriptor (if monitoring).

_Symbol type:_ `function`

-----------------------------------------------------