GPollableOutputStream: GIO Reference Manual

## GPollableOutputStream GPollableOutputStream — Interface for pollable output streams |

## Functions

gboolean | g_pollable_output_stream_can_poll ()
gboolean | g_pollable_output_stream_is_writable ()
GSource * | g_pollable_output_stream_create_source ()
gssize | g_pollable_output_stream_write_nonblocking ()

## Types and Values

| GPollableOutputStream
struct | GPollableOutputStreamInterface

## Object Hierarchy

        GInterface
        ╰── GPollableOutputStream

## Prerequisites

GPollableOutputStream requires GOutputStream.

## Known Implementations

GPollableOutputStream is implemented by GConverterOutputStream, GMemoryOutputStream and GUnixOutputStream.

## Includes

    #include <gio/gio.h>

## Description

GPollableOutputStream is implemented by GOutputStreams 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.

## Functions

### g_pollable_output_stream_can_poll ()

    gboolean
    g_pollable_output_stream_can_poll (GPollableOutputStream *stream);

Checks if `stream` is actually pollable. Some classes may implement GPollableOutputStream but have only certain instances of that class be pollable. If this method returns `FALSE`, then the behavior of other GPollableOutputStream 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.

#### Parameters

stream | a GPollableOutputStream. |

#### Returns

`TRUE` if `stream` is pollable, `FALSE` if not.

Since: 2.28

### g_pollable_output_stream_is_writable ()

    gboolean
    g_pollable_output_stream_is_writable (GPollableOutputStream *stream);

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 `g_output_stream_write()` after this returns `TRUE` would still block. To guarantee non-blocking behavior, you should always use `g_pollable_output_stream_write_nonblocking()`, which will return a `G_IO_ERROR_WOULD_BLOCK` error rather than blocking.

#### Parameters

stream | a GPollableOutputStream. |

#### Returns

`TRUE` if `stream` is writable, `FALSE` if not. If an error has occurred on `stream` , this will result in `g_pollable_output_stream_is_writable()` returning `TRUE`, and the next attempt to write will return the error.

Since: 2.28

### g_pollable_output_stream_create_source ()

    GSource *
    g_pollable_output_stream_create_source
                                   (GPollableOutputStream *stream,
                                    GCancellable *cancellable);

Creates a GSource 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 `g_pollable_output_stream_is_writable()`, it is possible that the stream may not actually be writable even after the source triggers, so you should use `g_pollable_output_stream_write_nonblocking()` rather than `g_output_stream_write()` from the callback.

#### Parameters

stream | a GPollableOutputStream. |
cancellable | a GCancellable, or `NULL`. | [nullable]

#### Returns

a new GSource.

[transfer full]

Since: 2.28

### g_pollable_output_stream_write_nonblocking ()

    gssize
    g_pollable_output_stream_write_nonblocking
                                   (GPollableOutputStream *stream,
                                    const void *buffer,
                                    gsize count,
                                    GCancellable *cancellable,
                                    GError **error);

Attempts to write up to `count` bytes from `buffer` to `stream` , as with `g_output_stream_write()`. If `stream` is not currently writable, this will immediately return `G_IO_ERROR_WOULD_BLOCK`, and you can use `g_pollable_output_stream_create_source()` to create a GSource 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 `G_IO_ERROR_WOULD_BLOCK` is returned some underlying transports like D/TLS require that you send the same `buffer` and `count` .

Virtual: write_nonblocking

#### Parameters

stream | a GPollableOutputStream |
buffer | a buffer to write data from. | [array length=count][element-type guint8]
count | the number of bytes you want to write |
cancellable | a GCancellable, or `NULL`. | [nullable]
error | GError for error reporting, or `NULL` to ignore. |

#### Returns

the number of bytes written, or -1 on error (including `G_IO_ERROR_WOULD_BLOCK`).

## Types and Values

### GPollableOutputStream

    typedef struct _GPollableOutputStream GPollableOutputStream;

An interface for a GOutputStream that can be polled for readability.

Since: 2.28

### struct GPollableOutputStreamInterface

    struct GPollableOutputStreamInterface {
      GTypeInterface g_iface;

      /* Virtual Table */
      gboolean     (*can_poll)          (GPollableOutputStream  *stream);

      gboolean     (*is_writable)       (GPollableOutputStream  *stream);
      GSource *    (*create_source)     (GPollableOutputStream  *stream,
    				     GCancellable           *cancellable);
      gssize       (*write_nonblocking) (GPollableOutputStream  *stream,
    				     const void             *buffer,
    				     gsize                   count,
    				     GError                **error);
    };

The interface for pollable output streams.

The default implementation of `can_poll` always returns `TRUE`.

The default implementation of `write_nonblocking` calls `g_pollable_output_stream_is_writable()`, and then calls `g_output_stream_write()` if it returns `TRUE`. This means you only need to override it if it is possible that your `is_writable` implementation may return `TRUE` when the stream is not actually writable.

#### Members

`can_poll` () | Checks if the GPollableOutputStream instance is actually pollable |
`is_writable` () | Checks if the stream is writable |
`create_source` () | Creates a GSource to poll the stream |
`write_nonblocking` () | Does a non-blocking write or returns `G_IO_ERROR_WOULD_BLOCK` |

Since: 2.28

## See Also

GOutputStream, GFileDescriptorBased, GPollableInputStream