## GstPoll GstPoll — Keep track of file descriptors and make it possible to wait on them in a cancelable way |

## Synopsis

    #include <gst/gst.h>

                        GstPoll;
                        GstPollFD;
    #define             GST_POLL_FD_INIT
    gboolean            gst_poll_add_fd                     (GstPoll *set,
                                                             GstPollFD *fd);
    gboolean            gst_poll_fd_can_read                (const GstPoll *set,
                                                             GstPollFD *fd);
    gboolean            gst_poll_fd_can_write               (const GstPoll *set,
                                                             GstPollFD *fd);
    gboolean            gst_poll_fd_ctl_read                (GstPoll *set,
                                                             GstPollFD *fd,
                                                             gboolean active);
    gboolean            gst_poll_fd_ctl_write               (GstPoll *set,
                                                             GstPollFD *fd,
                                                             gboolean active);
    gboolean            gst_poll_fd_has_closed              (const GstPoll *set,
                                                             GstPollFD *fd);
    gboolean            gst_poll_fd_has_error               (const GstPoll *set,
                                                             GstPollFD *fd);
    void                gst_poll_fd_ignored                 (GstPoll *set,
                                                             GstPollFD *fd);
    void                gst_poll_fd_init                    (GstPollFD *fd);
    void                gst_poll_free                       (GstPoll *set);
    GstPoll *           gst_poll_new                        (gboolean controllable);
    GstPoll *           gst_poll_new_timer                  (void);
    void                gst_poll_get_read_gpollfd           (GstPoll *set,
                                                             GPollFD *fd);
    gboolean            gst_poll_remove_fd                  (GstPoll *set,
                                                             GstPollFD *fd);
    void                gst_poll_restart                    (GstPoll *set);
    gboolean            gst_poll_set_controllable           (GstPoll *set,
                                                             gboolean controllable);
    void                gst_poll_set_flushing               (GstPoll *set,
                                                             gboolean flushing);
    gint                gst_poll_wait                       (GstPoll *set,
                                                             GstClockTime timeout);
    gboolean            gst_poll_read_control               (GstPoll *set);
    gboolean            gst_poll_write_control              (GstPoll *set);

## Description

A GstPoll keeps track of file descriptors much like fd_set (used with `select()`) or a struct pollfd array (used with `poll()`). Once created with `gst_poll_new()`, the set can be used to wait for file descriptors to be readable and/or writable. It is possible to make this wait be controlled by specifying `TRUE` for the `controllable` flag when creating the set (or later calling `gst_poll_set_controllable()`).

New file descriptors are added to the set using `gst_poll_add_fd()`, and removed using `gst_poll_remove_fd()`. Controlling which file descriptors should be waited for to become readable and/or writable are done using `gst_poll_fd_ctl_read()` and `gst_poll_fd_ctl_write()`.

Use `gst_poll_wait()` to wait for the file descriptors to actually become readable and/or writable, or to timeout if no file descriptor is available in time. The wait can be controlled by calling `gst_poll_restart()` and `gst_poll_set_flushing()`.

Once the file descriptor set has been waited for, one can use `gst_poll_fd_has_closed()` to see if the file descriptor has been closed, `gst_poll_fd_has_error()` to see if it has generated an error, `gst_poll_fd_can_read()` to see if it is possible to read from the file descriptor, and `gst_poll_fd_can_write()` to see if it is possible to write to it.

## Details

### GstPoll

    typedef struct _GstPoll GstPoll;

A set of file/network descriptors.

### GstPollFD

    typedef struct {
      int fd;
    } GstPollFD;

A file descriptor object.

int `fd`; | a file descriptor

### GST_POLL_FD_INIT

    #define GST_POLL_FD_INIT  { -1, -1 }

A GstPollFD must be initialized with this macro, before it can be used. This macro can used be to initialize a variable, but it cannot be assigned to a variable. In that case you have to use `gst_poll_fd_init()`.

### gst_poll_add_fd ()

    gboolean            gst_poll_add_fd                     (GstPoll *set,
                                                             GstPollFD *fd);

Add a file descriptor to the file descriptor set.

`set` : | a file descriptor set.
`fd` : | a file descriptor.
Returns : | `TRUE` if the file descriptor was successfully added to the set.

### gst_poll_fd_can_read ()

    gboolean            gst_poll_fd_can_read                (const GstPoll *set,
                                                             GstPollFD *fd);

Check if `fd` in `set` has data to be read.

`set` : | a file descriptor set.
`fd` : | a file descriptor.
Returns : | `TRUE` if the descriptor has data to be read.

### gst_poll_fd_can_write ()

    gboolean            gst_poll_fd_can_write               (const GstPoll *set,
                                                             GstPollFD *fd);

Check if `fd` in `set` can be used for writing.

`set` : | a file descriptor set.
`fd` : | a file descriptor.
Returns : | `TRUE` if the descriptor can be used for writing.

### gst_poll_fd_ctl_read ()

    gboolean            gst_poll_fd_ctl_read                (GstPoll *set,
                                                             GstPollFD *fd,
                                                             gboolean active);

Control whether the descriptor `fd` in `set` will be monitored for readability.

`set` : | a file descriptor set.
`fd` : | a file descriptor.
`active` : | a new status.
Returns : | `TRUE` if the descriptor was successfully updated.

### gst_poll_fd_ctl_write ()

    gboolean            gst_poll_fd_ctl_write               (GstPoll *set,
                                                             GstPollFD *fd,
                                                             gboolean active);

Control whether the descriptor `fd` in `set` will be monitored for writability.

`set` : | a file descriptor set.
`fd` : | a file descriptor.
`active` : | a new status.
Returns : | `TRUE` if the descriptor was successfully updated.

### gst_poll_fd_has_closed ()

    gboolean            gst_poll_fd_has_closed              (const GstPoll *set,
                                                             GstPollFD *fd);

Check if `fd` in `set` has closed the connection.

`set` : | a file descriptor set.
`fd` : | a file descriptor.
Returns : | `TRUE` if the connection was closed.

### gst_poll_fd_has_error ()

    gboolean            gst_poll_fd_has_error               (const GstPoll *set,
                                                             GstPollFD *fd);

Check if `fd` in `set` has an error.

`set` : | a file descriptor set.
`fd` : | a file descriptor.
Returns : | `TRUE` if the descriptor has an error.

### gst_poll_fd_ignored ()

    void                gst_poll_fd_ignored                 (GstPoll *set,
                                                             GstPollFD *fd);

Mark `fd` as ignored so that the next call to `gst_poll_wait()` will yield the same result for `fd` as last time. This function must be called if no operation (read/write/recv/send/etc.) will be performed on `fd` before the next call to `gst_poll_wait()`.

The reason why this is needed is because the underlying implementation might not allow querying the fd more than once between calls to one of the re-enabling operations.

`set` : | a file descriptor set.
`fd` : | a file descriptor.

### gst_poll_fd_init ()

    void                gst_poll_fd_init                    (GstPollFD *fd);

Initializes `fd`. Alternatively you can initialize it with GST_POLL_FD_INIT.

`fd` : | a GstPollFD

### gst_poll_free ()

    void                gst_poll_free                       (GstPoll *set);

Free a file descriptor set.

`set` : | a file descriptor set. [transfer full]

### gst_poll_new ()

    GstPoll *           gst_poll_new                        (gboolean controllable);

Create a new file descriptor set. If `controllable`, it is possible to restart or flush a call to `gst_poll_wait()` with `gst_poll_restart()` and `gst_poll_set_flushing()` respectively.

Free-function: gst_poll_free

`controllable` : | whether it should be possible to control a wait.
Returns : | a new GstPoll, or `NULL` in case of an error. Free with `gst_poll_free()`. [transfer full]

### gst_poll_new_timer ()

    GstPoll *           gst_poll_new_timer                  (void);

Create a new poll object that can be used for scheduling cancellable timeouts.

A timeout is performed with `gst_poll_wait()`. Multiple timeouts can be performed from different threads.

Free-function: gst_poll_free

Returns : | a new GstPoll, or `NULL` in case of an error. Free with `gst_poll_free()`. [transfer full]

### gst_poll_get_read_gpollfd ()

    void                gst_poll_get_read_gpollfd           (GstPoll *set,
                                                             GPollFD *fd);

Get a GPollFD for the reading part of the control socket. This is useful when integrating with a GSource and GMainLoop.

`set` : | a GstPoll
`fd` : | a GPollFD

### gst_poll_remove_fd ()

    gboolean            gst_poll_remove_fd                  (GstPoll *set,
                                                             GstPollFD *fd);

Remove a file descriptor from the file descriptor set.

`set` : | a file descriptor set.
`fd` : | a file descriptor.
Returns : | `TRUE` if the file descriptor was successfully removed from the set.

### gst_poll_restart ()

    void                gst_poll_restart                    (GstPoll *set);

Restart any `gst_poll_wait()` that is in progress. This function is typically used after adding or removing descriptors to `set`.

If `set` is not controllable, then this call will have no effect.

`set` : | a GstPoll.

### gst_poll_set_controllable ()

    gboolean            gst_poll_set_controllable           (GstPoll *set,
                                                             gboolean controllable);

When `controllable` is `TRUE`, this function ensures that future calls to `gst_poll_wait()` will be affected by `gst_poll_restart()` and `gst_poll_set_flushing()`.

`set` : | a GstPoll.
`controllable` : | new controllable state.
Returns : | `TRUE` if the controllability of `set` could be updated.

### gst_poll_set_flushing ()

    void                gst_poll_set_flushing               (GstPoll *set,
                                                             gboolean flushing);

When `flushing` is `TRUE`, this function ensures that current and future calls to `gst_poll_wait()` will return -1, with errno set to EBUSY.

Unsetting the flushing state will restore normal operation of `set`.

`set` : | a GstPoll.
`flushing` : | new flushing state.

### gst_poll_wait ()

    gint                gst_poll_wait                       (GstPoll *set,
                                                             GstClockTime timeout);

Wait for activity on the file descriptors in `set`. This function waits up to the specified `timeout`. A timeout of GST_CLOCK_TIME_NONE waits forever.

For GstPoll objects created with `gst_poll_new()`, this function can only be called from a single thread at a time. If called from multiple threads, -1 will be returned with errno set to EPERM.

This is not true for timer GstPoll objects created with `gst_poll_new_timer()`, where it is allowed to have multiple threads waiting simultaneously.

`set` : | a GstPoll.
`timeout` : | a timeout in nanoseconds.
Returns : | The number of GstPollFD in `set` that have activity or 0 when no activity was detected after `timeout`. If an error occurs, -1 is returned and errno is set.

### gst_poll_read_control ()

    gboolean            gst_poll_read_control               (GstPoll *set);

Read a byte from the control socket of the controllable `set`. This function is mostly useful for timer GstPoll objects created with `gst_poll_new_timer()`.

`set` : | a GstPoll.
Returns : | `TRUE` on success. `FALSE` when `set` is not controllable or when there was no byte to read.

### gst_poll_write_control ()

    gboolean            gst_poll_write_control              (GstPoll *set);

Write a byte to the control socket of the controllable `set`. This function is mostly useful for timer GstPoll objects created with `gst_poll_new_timer()`.

It will make any current and future `gst_poll_wait()` function return with 1, meaning the control socket is set. After an equal amount of calls to `gst_poll_read_control()` have been performed, calls to `gst_poll_wait()` will block again until their timeout expired.

`set` : | a GstPoll.
Returns : | `TRUE` on success. `FALSE` when `set` is not controllable or when the byte could not be written.