![]() |
![]() |
![]() |
GStreamer 0.10 Core Reference Manual | ![]() |
---|---|---|---|---|
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); 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 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.
#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
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
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
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
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
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
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
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
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
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
void gst_poll_free (GstPoll *set);
Free a file descriptor set.
set : |
a file descriptor set. |
Since 0.10.18
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.
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() .
|
Since 0.10.18
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.
Returns : | a new GstPoll, or NULL in case of an error. Free with
gst_poll_free() .
|
Since 0.10.23
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
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
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
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
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
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
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