gpollableutils

## gpollableutils gpollableutils — Utilities for pollable streams |

## Synopsis

    #include <gio/gio.h>

    gboolean            (*GPollableSourceFunc)              (GObject *pollable_stream,
                                                             gpointer user_data);
    GSource *           g_pollable_source_new               (GObject *pollable_stream);
    GSource *           g_pollable_source_new_full          (gpointer pollable_stream,
                                                             GSource *child_source,
                                                             GCancellable *cancellable);

    gssize              g_pollable_stream_read              (GInputStream *stream,
                                                             void *buffer,
                                                             gsize count,
                                                             gboolean blocking,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gssize              g_pollable_stream_write             (GOutputStream *stream,
                                                             const void *buffer,
                                                             gsize count,
                                                             gboolean blocking,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            g_pollable_stream_write_all         (GOutputStream *stream,
                                                             const void *buffer,
                                                             gsize count,
                                                             gboolean blocking,
                                                             gsize *bytes_written,
                                                             GCancellable *cancellable,
                                                             GError **error);

## Description

Utility functions for GPollableInputStream and GPollableOutputStream implementations.

## Details

### GPollableSourceFunc ()

    gboolean            (*GPollableSourceFunc)              (GObject *pollable_stream,
                                                             gpointer user_data);

This is the function type of the callback used for the GSource returned by `g_pollable_input_stream_create_source()` and `g_pollable_output_stream_create_source()`.

`pollable_stream` : | the GPollableInputStream or GPollableOutputStream
`user_data` : | data passed in by the user.
Returns : | it should return `FALSE` if the source should be removed.

Since 2.28

### g_pollable_source_new ()

    GSource *           g_pollable_source_new               (GObject *pollable_stream);

Utility method for GPollableInputStream and GPollableOutputStream implementations. Creates a new GSource that expects a callback of type GPollableSourceFunc. The new source does not actually do anything on its own; use `g_source_add_child_source()` to add other sources to it to cause it to trigger.

`pollable_stream` : | the stream associated with the new source
Returns : | the new GSource. [transfer full]

Since 2.28

### g_pollable_source_new_full ()

    GSource *           g_pollable_source_new_full          (gpointer pollable_stream,
                                                             GSource *child_source,
                                                             GCancellable *cancellable);

Utility method for GPollableInputStream and GPollableOutputStream implementations. Creates a new GSource, as with `g_pollable_source_new()`, but also attaching `child_source` (with a dummy callback), and `cancellable`, if they are non-`NULL`.

`pollable_stream` : | the stream associated with the new source. [type GObject]
`child_source` : | optional child source to attach. [allow-none]
`cancellable` : | optional GCancellable to attach. [allow-none]
Returns : | the new GSource. [transfer full]

Since 2.34

### g_pollable_stream_read ()

    gssize              g_pollable_stream_read              (GInputStream *stream,
                                                             void *buffer,
                                                             gsize count,
                                                             gboolean blocking,
                                                             GCancellable *cancellable,
                                                             GError **error);

Tries to read from `stream`, as with `g_input_stream_read()` (if `blocking` is `TRUE`) or `g_pollable_input_stream_read_nonblocking()` (if `blocking` is `FALSE`). This can be used to more easily share code between blocking and non-blocking implementations of a method.

If `blocking` is `FALSE`, then `stream` must be a GPollableInputStream for which `g_pollable_input_stream_can_poll()` returns `TRUE`, or else the behavior is undefined. If `blocking` is `TRUE`, then `stream` does not need to be a GPollableInputStream.

`stream` : | a GInputStream
`buffer` : | a buffer to read data into
`count` : | the number of bytes to read
`blocking` : | whether to do blocking I/O
`cancellable` : | optional GCancellable object, `NULL` to ignore. [allow-none]
`error` : | location to store the error occurring, or `NULL` to ignore
Returns : | the number of bytes read, or -1 on error.

Since 2.34

### g_pollable_stream_write ()

    gssize              g_pollable_stream_write             (GOutputStream *stream,
                                                             const void *buffer,
                                                             gsize count,
                                                             gboolean blocking,
                                                             GCancellable *cancellable,
                                                             GError **error);

Tries to write to `stream`, as with `g_output_stream_write()` (if `blocking` is `TRUE`) or `g_pollable_output_stream_write_nonblocking()` (if `blocking` is `FALSE`). This can be used to more easily share code between blocking and non-blocking implementations of a method.

If `blocking` is `FALSE`, then `stream` must be a GPollableOutputStream for which `g_pollable_output_stream_can_poll()` returns `TRUE` or else the behavior is undefined. If `blocking` is `TRUE`, then `stream` does not need to be a GPollableOutputStream.

`stream` : | a GOutputStream.
`buffer` : | the buffer containing the data to write. [array length=count][element-type guint8]
`count` : | the number of bytes to write
`blocking` : | whether to do blocking I/O
`cancellable` : | optional GCancellable object, `NULL` to ignore. [allow-none]
`error` : | location to store the error occurring, or `NULL` to ignore
Returns : | the number of bytes written, or -1 on error.

Since 2.34

### g_pollable_stream_write_all ()

    gboolean            g_pollable_stream_write_all         (GOutputStream *stream,
                                                             const void *buffer,
                                                             gsize count,
                                                             gboolean blocking,
                                                             gsize *bytes_written,
                                                             GCancellable *cancellable,
                                                             GError **error);

Tries to write `count` bytes to `stream`, as with `g_output_stream_write_all()`, but using `g_pollable_stream_write()` rather than `g_output_stream_write()`.

On a successful write of `count` bytes, `TRUE` is returned, and `bytes_written` is set to `count`.

If there is an error during the operation (including `G_IO_ERROR_WOULD_BLOCK` in the non-blocking case), `FALSE` is returned and `error` is set to indicate the error status, `bytes_written` is updated to contain the number of bytes written into the stream before the error occurred.

As with `g_pollable_stream_write()`, if `blocking` is `FALSE`, then `stream` must be a GPollableOutputStream for which `g_pollable_output_stream_can_poll()` returns `TRUE` or else the behavior is undefined. If `blocking` is `TRUE`, then `stream` does not need to be a GPollableOutputStream.

`stream` : | a GOutputStream.
`buffer` : | the buffer containing the data to write. [array length=count][element-type guint8]
`count` : | the number of bytes to write
`blocking` : | whether to do blocking I/O
`bytes_written` : | location to store the number of bytes that was written to the stream. [out]
`cancellable` : | optional GCancellable object, `NULL` to ignore. [allow-none]
`error` : | location to store the error occurring, or `NULL` to ignore
Returns : | `TRUE` on success, `FALSE` if there was an error

Since 2.34