GPollableInputStream: GIO Reference Manual

## GPollableInputStream GPollableInputStream — Interface for pollable input streams |

## Functions

gboolean | g_pollable_input_stream_can_poll ()
gboolean | g_pollable_input_stream_is_readable ()
GSource * | g_pollable_input_stream_create_source ()
gssize | g_pollable_input_stream_read_nonblocking ()

## Types and Values

| GPollableInputStream
struct | GPollableInputStreamInterface

## Object Hierarchy

        GInterface
        ╰── GPollableInputStream

## Prerequisites

GPollableInputStream requires GInputStream.

## Known Implementations

GPollableInputStream is implemented by GConverterInputStream, GMemoryInputStream and GUnixInputStream.

## Includes

    #include <gio/gio.h>

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

## Functions

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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 count,
                                    GCancellable *cancellable,
                                    GError **error);

Attempts to read up to `count` 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

#### Parameters

stream | a GPollableInputStream |
buffer | a buffer to read data into (which should be at least `count` bytes long). | [array length=count][element-type guint8]
count | 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`).

## Types and Values

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

#### Members

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

## See Also

GInputStream, GPollableOutputStream, GFileDescriptorBased