| GStreamer 1.0 Core Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | ||||
GstPollGstPoll — Keep track of file descriptors and make it possible to wait on them in a cancelable way |
#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);
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.
#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().
gboolean gst_poll_add_fd (GstPoll *set,GstPollFD *fd);
Add a file descriptor to the file descriptor set.
|
a file descriptor set. |
|
a file descriptor. |
Returns : |
TRUE if the file descriptor was successfully added to the set. |
gboolean gst_poll_fd_can_read (const GstPoll *set,GstPollFD *fd);
Check if fd in set has data to be read.
|
a file descriptor set. |
|
a file descriptor. |
Returns : |
TRUE if the descriptor has data to be read. |
gboolean gst_poll_fd_can_write (const GstPoll *set,GstPollFD *fd);
Check if fd in set can be used for writing.
|
a file descriptor set. |
|
a file descriptor. |
Returns : |
TRUE if the descriptor can be used for writing. |
gboolean gst_poll_fd_ctl_read (GstPoll *set,GstPollFD *fd,gboolean active);
Control whether the descriptor fd in set will be monitored for
readability.
|
a file descriptor set. |
|
a file descriptor. |
|
a new status. |
Returns : |
TRUE if the descriptor was successfully updated. |
gboolean gst_poll_fd_ctl_write (GstPoll *set,GstPollFD *fd,gboolean active);
Control whether the descriptor fd in set will be monitored for
writability.
|
a file descriptor set. |
|
a file descriptor. |
|
a new status. |
Returns : |
TRUE if the descriptor was successfully updated. |
gboolean gst_poll_fd_has_closed (const GstPoll *set,GstPollFD *fd);
Check if fd in set has closed the connection.
|
a file descriptor set. |
|
a file descriptor. |
Returns : |
TRUE if the connection was closed. |
gboolean gst_poll_fd_has_error (const GstPoll *set,GstPollFD *fd);
Check if fd in set has an error.
|
a file descriptor set. |
|
a file descriptor. |
Returns : |
TRUE if the descriptor has an error. |
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.
|
a file descriptor set. |
|
a file descriptor. |
void gst_poll_fd_init (GstPollFD *fd);
Initializes fd. Alternatively you can initialize it with
GST_POLL_FD_INIT.
|
a GstPollFD |
void gst_poll_free (GstPoll *set);
Free a file descriptor set.
|
a file descriptor set. [transfer full] |
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
|
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]
|
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]
|
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.
gboolean gst_poll_remove_fd (GstPoll *set,GstPollFD *fd);
Remove a file descriptor from the file descriptor set.
|
a file descriptor set. |
|
a file descriptor. |
Returns : |
TRUE if the file descriptor was successfully removed from the set. |
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.
|
a GstPoll. |
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().
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.
|
a GstPoll. |
|
new flushing state. |
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.
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().
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.