:right-sidebar: True Poll =================================================================== .. currentmodule:: gi.repository.Gst .. class:: Poll(*args, **kwargs) :no-contents-entry: A :obj:`~gi.repository.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 :func:`~gi.repository.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 :const:`True` for the ``controllable`` flag when creating the set (or later calling :func:`~gi.repository.Gst.Poll.set_controllable`). New file descriptors are added to the set using :func:`~gi.repository.Gst.Poll.add_fd`, and removed using :func:`~gi.repository.Gst.Poll.remove_fd`. Controlling which file descriptors should be waited for to become readable and/or writable are done using :func:`~gi.repository.Gst.Poll.fd_ctl_read`, :func:`~gi.repository.Gst.Poll.fd_ctl_write` and :func:`~gi.repository.Gst.Poll.fd_ctl_pri`. Use :func:`~gi.repository.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 :func:`~gi.repository.Gst.Poll.restart` and :func:`~gi.repository.Gst.Poll.set_flushing`. Once the file descriptor set has been waited for, one can use :func:`~gi.repository.Gst.Poll.fd_has_closed` to see if the file descriptor has been closed, :func:`~gi.repository.Gst.Poll.fd_has_error` to see if it has generated an error, :func:`~gi.repository.Gst.Poll.fd_can_read` to see if it is possible to read from the file descriptor, and :func:`~gi.repository.Gst.Poll.fd_can_write` to see if it is possible to write to it. Methods ------- .. rst-class:: interim-class .. class:: Poll :no-index: .. method:: add_fd(fd: ~gi.repository.Gst.PollFD) -> bool Add a file descriptor to the file descriptor set. :param fd: a file descriptor. .. method:: fd_can_read(fd: ~gi.repository.Gst.PollFD) -> bool Check if ``fd`` in ``set`` has data to be read. :param fd: a file descriptor. .. method:: fd_can_write(fd: ~gi.repository.Gst.PollFD) -> bool Check if ``fd`` in ``set`` can be used for writing. :param fd: a file descriptor. .. method:: fd_ctl_pri(fd: ~gi.repository.Gst.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 :const:`False` there). .. versionadded:: 1.16 :param fd: a file descriptor. :param active: a new status. .. method:: fd_ctl_read(fd: ~gi.repository.Gst.PollFD, active: bool) -> bool Control whether the descriptor ``fd`` in ``set`` will be monitored for readability. :param fd: a file descriptor. :param active: a new status. .. method:: fd_ctl_write(fd: ~gi.repository.Gst.PollFD, active: bool) -> bool Control whether the descriptor ``fd`` in ``set`` will be monitored for writability. :param fd: a file descriptor. :param active: a new status. .. method:: fd_has_closed(fd: ~gi.repository.Gst.PollFD) -> bool Check if ``fd`` in ``set`` has closed the connection. :param fd: a file descriptor. .. method:: fd_has_error(fd: ~gi.repository.Gst.PollFD) -> bool Check if ``fd`` in ``set`` has an error. :param fd: a file descriptor. .. method:: fd_has_pri(fd: ~gi.repository.Gst.PollFD) -> bool Check if ``fd`` in ``set`` has an exceptional condition (POLLPRI). Not implemented on Windows (will just return :const:`False` there). .. versionadded:: 1.16 :param fd: a file descriptor. .. method:: fd_ignored(fd: ~gi.repository.Gst.PollFD) -> None Mark ``fd`` as ignored so that the next call to :func:`~gi.repository.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 :func:`~gi.repository.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. :param fd: a file descriptor. .. method:: free() -> None Free a file descriptor set. .. method:: get_read_gpollfd(fd: ~gi.repository.GLib.PollFD) -> None Get a GPollFD for the reading part of the control socket. This is useful when integrating with a GSource and GMainLoop. :param fd: a :obj:`~gi.repository.GLib.PollFD` .. method:: read_control() -> bool Read a byte from the control socket of the controllable ``set``\. This function only works for timer :obj:`~gi.repository.Gst.Poll` objects created with :func:`~gi.repository.Gst.Poll.new_timer`. .. method:: remove_fd(fd: ~gi.repository.Gst.PollFD) -> bool Remove a file descriptor from the file descriptor set. :param fd: a file descriptor. .. method:: restart() -> None Restart any :func:`~gi.repository.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 :obj:`~gi.repository.Gst.Poll` objects created with :func:`~gi.repository.Gst.Poll.new`. .. method:: set_controllable(controllable: bool) -> bool When ``controllable`` is :const:`True`, this function ensures that future calls to :func:`~gi.repository.Gst.Poll.wait` will be affected by :func:`~gi.repository.Gst.Poll.restart` and :func:`~gi.repository.Gst.Poll.set_flushing`. This function only works for non-timer :obj:`~gi.repository.Gst.Poll` objects created with :func:`~gi.repository.Gst.Poll.new`. :param controllable: new controllable state. .. method:: set_flushing(flushing: bool) -> None When ``flushing`` is :const:`True`, this function ensures that current and future calls to :func:`~gi.repository.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 :obj:`~gi.repository.Gst.Poll` objects created with :func:`~gi.repository.Gst.Poll.new`. :param flushing: new flushing state. .. method:: 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 :obj:`~gi.repository.Gst.Poll` objects created with :func:`~gi.repository.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 :obj:`~gi.repository.Gst.Poll` objects created with :func:`~gi.repository.Gst.Poll.new_timer`, where it is allowed to have multiple threads waiting simultaneously. :param timeout: a timeout in nanoseconds. .. method:: write_control() -> bool Write a byte to the control socket of the controllable ``set``\. This function is mostly useful for timer :obj:`~gi.repository.Gst.Poll` objects created with :func:`~gi.repository.Gst.Poll.new_timer`. It will make any current and future :func:`~gi.repository.Gst.Poll.wait` function return with 1, meaning the control socket is set. After an equal amount of calls to :func:`~gi.repository.Gst.Poll.read_control` have been performed, calls to :func:`~gi.repository.Gst.Poll.wait` will block again until their timeout expired. This function only works for timer :obj:`~gi.repository.Gst.Poll` objects created with :func:`~gi.repository.Gst.Poll.new_timer`.