## GstPoll

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

## Functions

gboolean | gst_poll_add_fd ()
gboolean | gst_poll_fd_can_read ()
gboolean | gst_poll_fd_can_write ()
gboolean | gst_poll_fd_ctl_read ()
gboolean | gst_poll_fd_ctl_write ()
gboolean | gst_poll_fd_has_closed ()
gboolean | gst_poll_fd_has_error ()
void | gst_poll_fd_ignored ()
void | gst_poll_fd_init ()
void | gst_poll_free ()
GstPoll * | gst_poll_new ()
GstPoll * | gst_poll_new_timer ()
void | gst_poll_get_read_gpollfd ()
gboolean | gst_poll_remove_fd ()
void | gst_poll_restart ()
gboolean | gst_poll_set_controllable ()
void | gst_poll_set_flushing ()
gint | gst_poll_wait ()
gboolean | gst_poll_read_control ()
gboolean | gst_poll_write_control ()

## Types and Values

| GstPoll
| GstPollFD
#define | GST_POLL_FD_INIT

## Includes

    #include <gst/gst.h>

## 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.

## Functions

### gst_poll_add_fd ()

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

Add a file descriptor to the file descriptor set.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

fd | a GstPollFD |

### gst_poll_free ()

    void
    gst_poll_free (GstPoll *set);

Free a file descriptor set.

#### Parameters

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

[skip]

#### Parameters

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][nullable]

### 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

[skip]

#### Returns

a new GstPoll, or `NULL` in case of an error. Free with `gst_poll_free()`.

[transfer full][nullable]

### 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.

#### Parameters

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.

#### Parameters

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.

This function only works for non-timer GstPoll objects created with `gst_poll_new()`.

#### Parameters

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()`.

This function only works for non-timer GstPoll objects created with `gst_poll_new()`.

#### Parameters

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` .

This function only works for non-timer GstPoll objects created with `gst_poll_new()`.

#### Parameters

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.

#### Parameters

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 only works for timer GstPoll objects created with `gst_poll_new_timer()`.

#### Parameters

set | a GstPoll. |

#### Returns

`TRUE` on success. `FALSE` when when there was no byte to read or reading the byte failed. If there was no byte to read, and only then, errno will contain EWOULDBLOCK or EAGAIN. For all other values of errno this always signals a critical error.

### 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.

This function only works for timer GstPoll objects created with `gst_poll_new_timer()`.

#### Parameters

set | a GstPoll. |

#### Returns

`TRUE` on success. `FALSE` when when the byte could not be written. errno contains the detailed error code but will never be EAGAIN, EINTR or EWOULDBLOCK. `FALSE` always signals a critical error.

## Types and Values

### GstPoll

    typedef struct _GstPoll GstPoll;

A set of file/network descriptors.

### GstPollFD

    typedef struct {
      int fd;
    } GstPollFD;

A file descriptor object.

#### Members

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()`.