![]() |
![]() |
![]() |
GStreamer 1.0 Core Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
GstPollGstPoll — Keep track of file descriptors and make it possible to wait on them in a cancellable 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][nullable]
|
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][nullable]
|
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.
|
a GstPoll |
|
a GPollFD |
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.
This function only works for non-timer GstPoll objects created with
gst_poll_new()
.
|
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()
.
This function only works for non-timer GstPoll objects created with
gst_poll_new()
.
|
a GstPoll. |
|
new controllable state. |
Returns : |
TRUE if the controllability of set could be updated. |
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()
.
|
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 only works for timer GstPoll objects created with
gst_poll_new_timer()
.
|
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. |
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()
.
|
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. |