Poll#

class Poll(*args, **kwargs)#

A Poll keeps track of file descriptors much like fd_set (used with select ()) or a struct pollfd array (used with poll ()). Once created with 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 set_controllable()).

New file descriptors are added to the set using add_fd(), and removed using remove_fd(). Controlling which file descriptors should be waited for to become readable and/or writable are done using fd_ctl_read(), fd_ctl_write() and fd_ctl_pri().

Use 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 restart() and set_flushing().

Once the file descriptor set has been waited for, one can use fd_has_closed() to see if the file descriptor has been closed, fd_has_error() to see if it has generated an error, fd_can_read() to see if it is possible to read from the file descriptor, and fd_can_write() to see if it is possible to write to it.

Methods#

class Poll
add_fd(fd: PollFD) → bool#

Add a file descriptor to the file descriptor set.

Parameters:

fd – a file descriptor.

fd_can_read(fd: PollFD) → bool#

Check if fd in set has data to be read.

Parameters:

fd – a file descriptor.

fd_can_write(fd: PollFD) → bool#

Check if fd in set can be used for writing.

Parameters:

fd – a file descriptor.

fd_ctl_pri(fd: PollFD, active: bool) → bool#

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

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

Added in version 1.16.

Parameters:

  • fd – a file descriptor.

  • active – a new status.

fd_ctl_read(fd: PollFD, active: bool) → bool#

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

Parameters:

  • fd – a file descriptor.

  • active – a new status.

fd_ctl_write(fd: PollFD, active: bool) → bool#

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

Parameters:

  • fd – a file descriptor.

  • active – a new status.

fd_has_closed(fd: PollFD) → bool#

Check if fd in set has closed the connection.

Parameters:

fd – a file descriptor.

fd_has_error(fd: PollFD) → bool#

Check if fd in set has an error.

Parameters:

fd – a file descriptor.

fd_has_pri(fd: PollFD) → bool#

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

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

Added in version 1.16.

Parameters:

fd – a file descriptor.

fd_ignored(fd: PollFD) → None#

Mark fd as ignored so that the next call to 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 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.

Parameters:

fd – a file descriptor.

free() → None#

Free a file descriptor set.

get_read_gpollfd(fd: PollFD) → None#

Get a GPollFD for the reading part of the control socket. This is useful when integrating with a GSource and GMainLoop.

Parameters:

fd – a PollFD

read_control() → bool#

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

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

remove_fd(fd: PollFD) → bool#

Remove a file descriptor from the file descriptor set.

Parameters:

fd – a file descriptor.

restart() → None#

Restart any 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 Poll objects created with new().

set_controllable(controllable: bool) → bool#

When controllable is True, this function ensures that future calls to wait() will be affected by restart() and set_flushing().

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

Parameters:

controllable – new controllable state.

set_flushing(flushing: bool) → None#

When flushing is True, this function ensures that current and future calls to 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 Poll objects created with new().

Parameters:

flushing – new flushing state.

wait(timeout: int) → int#

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

Parameters:

timeout – a timeout in nanoseconds.

write_control() → bool#

Write a byte to the control socket of the controllable set. This function is mostly useful for timer Poll objects created with new_timer().

It will make any current and future wait() function return with 1, meaning the control socket is set. After an equal amount of calls to read_control() have been performed, calls to wait() will block again until their timeout expired.

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