GIO Reference Manual: GPollableOutputStream

## GPollableOutputStream GPollableOutputStream — Interface for pollable output streams |

## Synopsis

    #include <gio/gio.h>

                        GPollableOutputStream;
    struct              GPollableOutputStreamInterface;

    gboolean            g_pollable_output_stream_can_poll   (GPollableOutputStream *stream);
    gboolean            g_pollable_output_stream_is_writable
                                                            (GPollableOutputStream *stream);
    GSource *           g_pollable_output_stream_create_source
                                                            (GPollableOutputStream *stream,
                                                             GCancellable *cancellable);
    gssize              g_pollable_output_stream_write_nonblocking
                                                            (GPollableOutputStream *stream,
                                                             const void *buffer,
                                                             gsize count,
                                                             GCancellable *cancellable,
                                                             GError **error);

## Object Hierarchy

      GInterface
       +----GPollableOutputStream

## Prerequisites

GPollableOutputStream requires GOutputStream.

## Known Implementations

GPollableOutputStream is implemented by GConverterOutputStream, GMemoryOutputStream and GUnixOutputStream.

## 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.

## Details

### 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.

GTypeInterface `g_iface`; | The parent interface.
`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

### 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.

`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.

`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.

`stream` : | a GPollableOutputStream.
`cancellable` : | a GCancellable, or `NULL`. [allow-none]
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.

Virtual: write_nonblocking

`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`. [allow-none]
`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`).

## See Also

GOutputStream, GFileDescriptorBased, GPollableInputStream