## GPollableInputStream

GPollableInputStream — Interface for pollable input streams

## Synopsis

    #include <gio/gio.h>

                        GPollableInputStream;
    struct              GPollableInputStreamInterface;

    gboolean            g_pollable_input_stream_can_poll    (GPollableInputStream *stream);
    gboolean            g_pollable_input_stream_is_readable (GPollableInputStream *stream);
    GSource *           g_pollable_input_stream_create_source
                                                            (GPollableInputStream *stream,
                                                             GCancellable *cancellable);
    gssize              g_pollable_input_stream_read_nonblocking
                                                            (GPollableInputStream *stream,
                                                             void *buffer,
                                                             gsize size,
                                                             GCancellable *cancellable,
                                                             GError **error);

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

## Object Hierarchy

      GInterface
       +----GPollableInputStream

## Prerequisites

GPollableInputStream requires GInputStream.

## Known Implementations

GPollableInputStream is implemented by GUnixInputStream.

## Description

GPollableInputStream is implemented by GInputStreams that can be polled for readiness to read. 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

### GPollableInputStream

    typedef struct _GPollableInputStream GPollableInputStream;

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

Since 2.28

### struct GPollableInputStreamInterface

    struct GPollableInputStreamInterface {
      GTypeInterface g_iface;

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

      gboolean     (*is_readable)      (GPollableInputStream  *stream);
      GSource *    (*create_source)    (GPollableInputStream  *stream,
    				    GCancellable          *cancellable);
      gssize       (*read_nonblocking) (GPollableInputStream  *stream,
    				    void                  *buffer,
    				    gsize                  size,
    				    GError               **error);
    };

The interface for pollable input streams.

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

The default implementation of `read_nonblocking` calls `g_pollable_input_stream_is_readable()`, and then calls `g_input_stream_read()` if it returns `TRUE`. This means you only need to override it if it is possible that your `is_readable` implementation may return `TRUE` when the stream is not actually readable.

GTypeInterface `g_iface`; | The parent interface.
`can_poll` () | Checks if the GPollableInputStream instance is actually pollable
`is_readable` () | Checks if the stream is readable
`create_source` () | Creates a GSource to poll the stream
`read_nonblocking` () | Does a non-blocking read or returns `G_IO_ERROR_WOULD_BLOCK`

Since 2.28

### g_pollable_input_stream_can_poll ()

    gboolean            g_pollable_input_stream_can_poll    (GPollableInputStream *stream);

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

Since 2.28

### g_pollable_input_stream_is_readable ()

    gboolean            g_pollable_input_stream_is_readable (GPollableInputStream *stream);

Checks if `stream` can be read.

Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to `g_input_stream_read()` after this returns `TRUE` would still block. To guarantee non-blocking behavior, you should always use `g_pollable_input_stream_read_nonblocking()`, which will return a `G_IO_ERROR_WOULD_BLOCK` error rather than blocking.

`stream` : | a GPollableInputStream.
Returns : | `TRUE` if `stream` is readable, `FALSE` if not. If an error has occurred on `stream`, this will result in `g_pollable_input_stream_is_readable()` returning `TRUE`, and the next attempt to read will return the error.

Since 2.28

### g_pollable_input_stream_create_source ()

    GSource *           g_pollable_input_stream_create_source
                                                            (GPollableInputStream *stream,
                                                             GCancellable *cancellable);

Creates a GSource that triggers when `stream` can be read, or `cancellable` is triggered or an error occurs. The callback on the source is of the GPollableSourceFunc type.

As with `g_pollable_input_stream_is_readable()`, it is possible that the stream may not actually be readable even after the source triggers, so you should use `g_pollable_input_stream_read_nonblocking()` rather than `g_input_stream_read()` from the callback.

`stream` : | a GPollableInputStream.
`cancellable` : | a GCancellable, or `NULL`. [allow-none]
Returns : | a new GSource. [transfer full]

Since 2.28

### g_pollable_input_stream_read_nonblocking ()

    gssize              g_pollable_input_stream_read_nonblocking
                                                            (GPollableInputStream *stream,
                                                             void *buffer,
                                                             gsize size,
                                                             GCancellable *cancellable,
                                                             GError **error);

Attempts to read up to `size` bytes from `stream` into `buffer`, as with `g_input_stream_read()`. If `stream` is not currently readable, this will immediately return `G_IO_ERROR_WOULD_BLOCK`, and you can use `g_pollable_input_stream_create_source()` to create a GSource that will be triggered when `stream` is readable.

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: read_nonblocking

`stream` : | a GPollableInputStream
`buffer` : | a buffer to read data into (which should be at least `size` bytes long).
`size` : | the number of bytes you want to read
`cancellable` : | a GCancellable, or `NULL`. [allow-none]
`error` : | GError for error reporting, or `NULL` to ignore.
Returns : | the number of bytes read, or -1 on error (including `G_IO_ERROR_WOULD_BLOCK`).

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

## See Also

GInputStream, GPollableOutputStream, GFileDescriptorBased