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 writeable. 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 writeable 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 writeable, 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().

Since 0.10.18


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.

Since 0.10.18


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.

Since 0.10.18


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.

Since 0.10.18


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.

Since 0.10.18


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.

Since 0.10.18


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.

Since 0.10.18


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.

Since 0.10.18


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.

Since 0.10.18


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

Since 0.10.18


gst_poll_free ()

void                gst_poll_free                       (GstPoll *set);

Free a file descriptor set.

set :

a file descriptor set. [transfer full]

Since 0.10.18


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]

Since 0.10.18


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]

Since 0.10.23


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

Since 0.10.32


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.

Since 0.10.18


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.

Since 0.10.18


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.

Since 0.10.18


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.

Since 0.10.18


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.

Since 0.10.18


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.

Since 0.10.23


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.

Since 0.10.23