:right-sidebar: True PollableInputStream =================================================================== .. currentmodule:: gi.repository.Gio .. versionadded:: 2.28 .. class:: PollableInputStream(*args, **kwargs) :no-contents-entry: Implementations: :class:`~gi.repository.Gio.ConverterInputStream`, :class:`~gi.repository.Gio.MemoryInputStream`, :class:`~gi.repository.Gio.UnixInputStream` ``GPollableInputStream`` is implemented by :obj:`~gi.repository.Gio.InputStream`\s that can be polled for readiness to read. This can be used when interfacing with a non-GIO API that expects UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. Some classes may implement ``GPollableInputStream`` but have only certain instances of that class be pollable. If :obj:`~gi.repository.Gio.PollableInputStream.can_poll` returns false, then the behavior of other ``GPollableInputStream`` methods is undefined. Methods ------- .. rst-class:: interim-class .. class:: PollableInputStream :no-index: .. method:: can_poll() -> bool Checks if ``stream`` is actually pollable. Some classes may implement :obj:`~gi.repository.Gio.PollableInputStream` but have only certain instances of that class be pollable. If this method returns :const:`False`, then the behavior of other :obj:`~gi.repository.Gio.PollableInputStream` methods is undefined. For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa. .. versionadded:: 2.28 .. method:: create_source(cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.GLib.Source Creates a :obj:`~gi.repository.GLib.Source` that triggers when ``stream`` can be read, or ``cancellable`` is triggered or an error occurs. The callback on the source is of the ``GPollableSourceFunc`` type. As with :func:`~gi.repository.Gio.PollableInputStream.is_readable`, it is possible that the stream may not actually be readable even after the source triggers, so you should use :func:`~gi.repository.Gio.PollableInputStream.read_nonblocking` rather than :func:`~gi.repository.Gio.InputStream.read` from the callback. The behaviour of this method is undefined if :func:`~gi.repository.Gio.PollableInputStream.can_poll` returns :const:`False` for ``stream``\. .. versionadded:: 2.28 :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`\, or :const:`None` .. method:: is_readable() -> bool Checks if ``stream`` can be read. Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to :func:`~gi.repository.Gio.InputStream.read` after this returns :const:`True` would still block. To guarantee non-blocking behavior, you should always use :func:`~gi.repository.Gio.PollableInputStream.read_nonblocking`, which will return a :const:`~gi.repository.Gio.IOErrorEnum.WOULD_BLOCK` error rather than blocking. The behaviour of this method is undefined if :func:`~gi.repository.Gio.PollableInputStream.can_poll` returns :const:`False` for ``stream``\. .. versionadded:: 2.28 .. method:: read_nonblocking(cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~typing.Tuple[int, list[int]] Attempts to read up to ``count`` bytes from ``stream`` into ``buffer``\, as with :func:`~gi.repository.Gio.InputStream.read`. If ``stream`` is not currently readable, this will immediately return :const:`~gi.repository.Gio.IOErrorEnum.WOULD_BLOCK`, and you can use :func:`~gi.repository.Gio.PollableInputStream.create_source` to create a :obj:`~gi.repository.GLib.Source` that will be triggered when ``stream`` is readable. Note that since this method never blocks, you cannot actually use ``cancellable`` to cancel it. However, it will return an error if ``cancellable`` has already been cancelled when you call, which may happen if you call this method after a source triggers due to having been cancelled. The behaviour of this method is undefined if :func:`~gi.repository.Gio.PollableInputStream.can_poll` returns :const:`False` for ``stream``\. :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`\, or :const:`None` Virtual Methods --------------- .. rst-class:: interim-class .. class:: PollableInputStream :no-index: .. method:: do_can_poll() -> bool Checks if ``stream`` is actually pollable. Some classes may implement :obj:`~gi.repository.Gio.PollableInputStream` but have only certain instances of that class be pollable. If this method returns :const:`False`, then the behavior of other :obj:`~gi.repository.Gio.PollableInputStream` methods is undefined. For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa. .. versionadded:: 2.28 .. method:: do_create_source(cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.GLib.Source Creates a :obj:`~gi.repository.GLib.Source` that triggers when ``stream`` can be read, or ``cancellable`` is triggered or an error occurs. The callback on the source is of the ``GPollableSourceFunc`` type. As with :func:`~gi.repository.Gio.PollableInputStream.is_readable`, it is possible that the stream may not actually be readable even after the source triggers, so you should use :func:`~gi.repository.Gio.PollableInputStream.read_nonblocking` rather than :func:`~gi.repository.Gio.InputStream.read` from the callback. The behaviour of this method is undefined if :func:`~gi.repository.Gio.PollableInputStream.can_poll` returns :const:`False` for ``stream``\. .. versionadded:: 2.28 :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`\, or :const:`None` .. method:: do_is_readable() -> bool Checks if ``stream`` can be read. Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to :func:`~gi.repository.Gio.InputStream.read` after this returns :const:`True` would still block. To guarantee non-blocking behavior, you should always use :func:`~gi.repository.Gio.PollableInputStream.read_nonblocking`, which will return a :const:`~gi.repository.Gio.IOErrorEnum.WOULD_BLOCK` error rather than blocking. The behaviour of this method is undefined if :func:`~gi.repository.Gio.PollableInputStream.can_poll` returns :const:`False` for ``stream``\. .. versionadded:: 2.28 .. method:: do_read_nonblocking() -> ~typing.Tuple[int, list[int] | None] Attempts to read up to ``count`` bytes from ``stream`` into ``buffer``\, as with :func:`~gi.repository.Gio.InputStream.read`. If ``stream`` is not currently readable, this will immediately return :const:`~gi.repository.Gio.IOErrorEnum.WOULD_BLOCK`, and you can use :func:`~gi.repository.Gio.PollableInputStream.create_source` to create a :obj:`~gi.repository.GLib.Source` that will be triggered when ``stream`` is readable. Note that since this method never blocks, you cannot actually use ``cancellable`` to cancel it. However, it will return an error if ``cancellable`` has already been cancelled when you call, which may happen if you call this method after a source triggers due to having been cancelled. The behaviour of this method is undefined if :func:`~gi.repository.Gio.PollableInputStream.can_poll` returns :const:`False` for ``stream``\.