## gpollableutils gpollableutils — Utilities for pollable streams |

## Functions

gboolean | (*GPollableSourceFunc) ()
GSource * | g_pollable_source_new ()
GSource * | g_pollable_source_new_full ()
gssize | g_pollable_stream_read ()
gssize | g_pollable_stream_write ()
gboolean | g_pollable_stream_write_all ()

## Types and Values

enum | GPollableReturn

## Object Hierarchy

        GEnum
        ╰── GPollableReturn

## Includes

    #include <gio/gio.h>

## Description

Utility functions for GPollableInputStream and GPollableOutputStream implementations.

## Functions

### GPollableSourceFunc ()

    gboolean
    (*GPollableSourceFunc) (GObject *pollable_stream,
                            gpointer 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()`.

#### Parameters

pollable_stream | the GPollableInputStream or GPollableOutputStream |
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.

#### Parameters

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

#### Parameters

pollable_stream | the stream associated with the new source. | [type GObject]
child_source | optional child source to attach. | [nullable]
cancellable | optional GCancellable to attach. | [nullable]

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

#### Parameters

stream | a GInputStream |
buffer | a buffer to read data into. | [array length=count][element-type guint8]
count | the number of bytes to read |
blocking | whether to do blocking I/O |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
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.

#### Parameters

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. | [nullable]
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.

#### Parameters

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. | [nullable]
error | location to store the error occurring, or `NULL` to ignore |

#### Returns

`TRUE` on success, `FALSE` if there was an error

Since: 2.34

## Types and Values

### enum GPollableReturn

Return value for various IO operations that signal errors via the return value and not necessarily via a GError.

This enum exists to be able to return errors to callers without having to allocate a GError. Allocating GErrors can be quite expensive for regularly happening errors like `G_IO_ERROR_WOULD_BLOCK`.

In case of `G_POLLABLE_RETURN_FAILED` a GError should be set for the operation to give details about the error that happened.

#### Members

G_POLLABLE_RETURN_FAILED | Generic error condition for when an operation fails. |
G_POLLABLE_RETURN_OK | The operation was successfully finished. |
G_POLLABLE_RETURN_WOULD_BLOCK | The operation would block. |

Since: 2.60