Gst.Poll

Fields

None

Methods

add_fd (fd)

fd_can_read (fd)

fd_can_write (fd)

fd_ctl_pri (fd, active)

fd_ctl_read (fd, active)

fd_ctl_write (fd, active)

fd_has_closed (fd)

fd_has_error (fd)

fd_has_pri (fd)

fd_ignored (fd)

free ()

get_read_gpollfd (fd)

read_control ()

remove_fd (fd)

restart ()

set_controllable (controllable)

set_flushing (flushing)

wait (timeout)

write_control ()

Details

class Gst.Poll

A Gst.Poll 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(), Gst.Poll.fd_ctl_write() and Gst.Poll.fd_ctl_pri().

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.

add_fd(fd)[source]
Parameters:

fd (Gst.PollFD) – a file descriptor.

Returns:

True if the file descriptor was successfully added to the set.

Return type:

bool

Add a file descriptor to the file descriptor set.

fd_can_read(fd)[source]
Parameters:

fd (Gst.PollFD) – a file descriptor.

Returns:

True if the descriptor has data to be read.

Return type:

bool

Check if fd in self has data to be read.

fd_can_write(fd)[source]
Parameters:

fd (Gst.PollFD) – a file descriptor.

Returns:

True if the descriptor can be used for writing.

Return type:

bool

Check if fd in self can be used for writing.

fd_ctl_pri(fd, active)[source]
Parameters:
  • fd (Gst.PollFD) – a file descriptor.

  • active (bool) – a new status.

Returns:

True if the descriptor was successfully updated.

Return type:

bool

Control whether the descriptor fd in self will be monitored for exceptional conditions (POLLPRI).

Not implemented on Windows (will just return False there).

New in version 1.16.

fd_ctl_read(fd, active)[source]
Parameters:
  • fd (Gst.PollFD) – a file descriptor.

  • active (bool) – a new status.

Returns:

True if the descriptor was successfully updated.

Return type:

bool

Control whether the descriptor fd in self will be monitored for readability.

fd_ctl_write(fd, active)[source]
Parameters:
  • fd (Gst.PollFD) – a file descriptor.

  • active (bool) – a new status.

Returns:

True if the descriptor was successfully updated.

Return type:

bool

Control whether the descriptor fd in self will be monitored for writability.

fd_has_closed(fd)[source]
Parameters:

fd (Gst.PollFD) – a file descriptor.

Returns:

True if the connection was closed.

Return type:

bool

Check if fd in self has closed the connection.

fd_has_error(fd)[source]
Parameters:

fd (Gst.PollFD) – a file descriptor.

Returns:

True if the descriptor has an error.

Return type:

bool

Check if fd in self has an error.

fd_has_pri(fd)[source]
Parameters:

fd (Gst.PollFD) – a file descriptor.

Returns:

True if the descriptor has an exceptional condition.

Return type:

bool

Check if fd in self has an exceptional condition (POLLPRI).

Not implemented on Windows (will just return False there).

New in version 1.16.

fd_ignored(fd)[source]
Parameters:

fd (Gst.PollFD) – a file descriptor.

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.

free()[source]

Free a file descriptor set.

get_read_gpollfd(fd)[source]
Parameters:

fd (GLib.PollFD) – a GLib.PollFD

Get a GLib.PollFD for the reading part of the control socket. This is useful when integrating with a GLib.Source and GLib.MainLoop.

read_control()[source]
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.

Return type:

bool

Read a byte from the control socket of the controllable self.

This function only works for timer Gst.Poll objects created with gst_poll_new_timer().

remove_fd(fd)[source]
Parameters:

fd (Gst.PollFD) – a file descriptor.

Returns:

True if the file descriptor was successfully removed from the set.

Return type:

bool

Remove a file descriptor from the file descriptor set.

restart()[source]

Restart any Gst.Poll.wait() that is in progress. This function is typically used after adding or removing descriptors to self.

If self is not controllable, then this call will have no effect.

This function only works for non-timer Gst.Poll objects created with gst_poll_new().

set_controllable(controllable)[source]
Parameters:

controllable (bool) – new controllable state.

Returns:

True if the controllability of self could be updated.

Return type:

bool

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 Gst.Poll objects created with gst_poll_new().

set_flushing(flushing)[source]
Parameters:

flushing (bool) – new flushing state.

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

This function only works for non-timer Gst.Poll objects created with gst_poll_new().

wait(timeout)[source]
Parameters:

timeout (int) – a timeout in nanoseconds.

Returns:

The number of Gst.PollFD in self that have activity or 0 when no activity was detected after timeout. If an error occurs, -1 is returned and errno is set.

Return type:

int

Wait for activity on the file descriptors in self. This function waits up to the specified timeout. A timeout of Gst.CLOCK_TIME_NONE waits forever.

For Gst.Poll 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 Gst.Poll objects created with gst_poll_new_timer(), where it is allowed to have multiple threads waiting simultaneously.

write_control()[source]
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.

Return type:

bool

Write a byte to the control socket of the controllable self. This function is mostly useful for timer Gst.Poll 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 Gst.Poll objects created with gst_poll_new_timer().