:right-sidebar: True PollableOutputStream =================================================================== .. currentmodule:: gi.repository.Gio .. versionadded:: 2.28 .. class:: PollableOutputStream(*args, **kwargs) :no-contents-entry: Implementations: :class:`~gi.repository.Gio.ConverterOutputStream`, :class:`~gi.repository.Gio.MemoryOutputStream`, :class:`~gi.repository.Gio.UnixOutputStream` ``GPollableOutputStream`` is implemented by :obj:`~gi.repository.Gio.OutputStream`'s that can be polled for readiness to write. 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 ``GPollableOutputStream`` but have only certain instances of that class be pollable. If :obj:`~gi.repository.Gio.PollableOutputStream.can_poll` returns false, then the behavior of other ``GPollableOutputStream`` methods is undefined. Methods ------- .. rst-class:: interim-class .. class:: PollableOutputStream :no-index: .. method:: can_poll() -> bool Checks if ``stream`` is actually pollable. Some classes may implement :obj:`~gi.repository.Gio.PollableOutputStream` 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.PollableOutputStream` 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 written, or ``cancellable`` is triggered or an error occurs. The callback on the source is of the ``GPollableSourceFunc`` type. As with :func:`~gi.repository.Gio.PollableOutputStream.is_writable`, it is possible that the stream may not actually be writable even after the source triggers, so you should use :func:`~gi.repository.Gio.PollableOutputStream.write_nonblocking` rather than :func:`~gi.repository.Gio.OutputStream.write` from the callback. The behaviour of this method is undefined if :func:`~gi.repository.Gio.PollableOutputStream.can_poll` returns :const:`False` for ``stream``. .. versionadded:: 2.28 :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`, or :const:`None` .. method:: is_writable() -> bool Checks if ``stream`` can be written. 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.OutputStream.write` after this returns :const:`True` would still block. To guarantee non-blocking behavior, you should always use :func:`~gi.repository.Gio.PollableOutputStream.write_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.PollableOutputStream.can_poll` returns :const:`False` for ``stream``. .. versionadded:: 2.28 .. method:: write_nonblocking(buffer: list[int], cancellable: ~gi.repository.Gio.Cancellable | None = None) -> int Attempts to write up to ``count`` bytes from ``buffer`` to ``stream``, as with :func:`~gi.repository.Gio.OutputStream.write`. If ``stream`` is not currently writable, this will immediately return :const:`~gi.repository.Gio.IOErrorEnum.WOULD_BLOCK`, and you can use :func:`~gi.repository.Gio.PollableOutputStream.create_source` to create a :obj:`~gi.repository.GLib.Source` that will be triggered when ``stream`` is writable. 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. Also note that if :const:`~gi.repository.Gio.IOErrorEnum.WOULD_BLOCK` is returned some underlying transports like D/TLS require that you re-send the same ``buffer`` and ``count`` in the next write call. The behaviour of this method is undefined if :func:`~gi.repository.Gio.PollableOutputStream.can_poll` returns :const:`False` for ``stream``. :param buffer: a buffer to write data from :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`, or :const:`None` .. method:: writev_nonblocking(vectors: list[~gi.repository.Gio.OutputVector], cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~typing.Tuple[~gi.repository.Gio.PollableReturn, int] Attempts to write the bytes contained in the ``n_vectors`` ``vectors`` to ``stream``, as with :func:`~gi.repository.Gio.OutputStream.writev`. If ``stream`` is not currently writable, this will immediately return %``G_POLLABLE_RETURN_WOULD_BLOCK``, and you can use :func:`~gi.repository.Gio.PollableOutputStream.create_source` to create a :obj:`~gi.repository.GLib.Source` that will be triggered when ``stream`` is writable. ``error`` will *not* be set in that case. 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. Also note that if :const:`~gi.repository.Gio.PollableReturn.WOULD_BLOCK` is returned some underlying transports like D/TLS require that you re-send the same ``vectors`` and ``n_vectors`` in the next write call. The behaviour of this method is undefined if :func:`~gi.repository.Gio.PollableOutputStream.can_poll` returns :const:`False` for ``stream``. .. versionadded:: 2.60 :param vectors: the buffer containing the :obj:`~gi.repository.Gio.OutputVector` to write. :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`, or :const:`None` Virtual Methods --------------- .. rst-class:: interim-class .. class:: PollableOutputStream :no-index: .. method:: do_can_poll(type, self) -> bool Checks if ``stream`` is actually pollable. Some classes may implement :obj:`~gi.repository.Gio.PollableOutputStream` 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.PollableOutputStream` 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 :param type: :param self: .. method:: do_create_source(type, self, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.GLib.Source Creates a :obj:`~gi.repository.GLib.Source` that triggers when ``stream`` can be written, or ``cancellable`` is triggered or an error occurs. The callback on the source is of the ``GPollableSourceFunc`` type. As with :func:`~gi.repository.Gio.PollableOutputStream.is_writable`, it is possible that the stream may not actually be writable even after the source triggers, so you should use :func:`~gi.repository.Gio.PollableOutputStream.write_nonblocking` rather than :func:`~gi.repository.Gio.OutputStream.write` from the callback. The behaviour of this method is undefined if :func:`~gi.repository.Gio.PollableOutputStream.can_poll` returns :const:`False` for ``stream``. .. versionadded:: 2.28 :param type: :param self: :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`, or :const:`None` .. method:: do_is_writable(type, self) -> bool Checks if ``stream`` can be written. 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.OutputStream.write` after this returns :const:`True` would still block. To guarantee non-blocking behavior, you should always use :func:`~gi.repository.Gio.PollableOutputStream.write_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.PollableOutputStream.can_poll` returns :const:`False` for ``stream``. .. versionadded:: 2.28 :param type: :param self: .. method:: do_write_nonblocking(type, self, buffer: list[int] | None = None) -> int Attempts to write up to ``count`` bytes from ``buffer`` to ``stream``, as with :func:`~gi.repository.Gio.OutputStream.write`. If ``stream`` is not currently writable, this will immediately return :const:`~gi.repository.Gio.IOErrorEnum.WOULD_BLOCK`, and you can use :func:`~gi.repository.Gio.PollableOutputStream.create_source` to create a :obj:`~gi.repository.GLib.Source` that will be triggered when ``stream`` is writable. 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. Also note that if :const:`~gi.repository.Gio.IOErrorEnum.WOULD_BLOCK` is returned some underlying transports like D/TLS require that you re-send the same ``buffer`` and ``count`` in the next write call. The behaviour of this method is undefined if :func:`~gi.repository.Gio.PollableOutputStream.can_poll` returns :const:`False` for ``stream``. :param type: :param self: :param buffer: a buffer to write data from .. method:: do_writev_nonblocking(type, self, vectors: list[~gi.repository.Gio.OutputVector]) -> ~typing.Tuple[~gi.repository.Gio.PollableReturn, int] Attempts to write the bytes contained in the ``n_vectors`` ``vectors`` to ``stream``, as with :func:`~gi.repository.Gio.OutputStream.writev`. If ``stream`` is not currently writable, this will immediately return %``G_POLLABLE_RETURN_WOULD_BLOCK``, and you can use :func:`~gi.repository.Gio.PollableOutputStream.create_source` to create a :obj:`~gi.repository.GLib.Source` that will be triggered when ``stream`` is writable. ``error`` will *not* be set in that case. 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. Also note that if :const:`~gi.repository.Gio.PollableReturn.WOULD_BLOCK` is returned some underlying transports like D/TLS require that you re-send the same ``vectors`` and ``n_vectors`` in the next write call. The behaviour of this method is undefined if :func:`~gi.repository.Gio.PollableOutputStream.can_poll` returns :const:`False` for ``stream``. .. versionadded:: 2.60 :param type: :param self: :param vectors: the buffer containing the :obj:`~gi.repository.Gio.OutputVector` to write.