gi-gio-2.0.38: Gio bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gio.Interfaces.PollableInputStream

Contents

- Exported types
- Methods
  - canPoll
  - createSource
  - isReadable
  - readNonblocking

Description

`GPollableInputStream` is implemented by `InputStream`s 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.

Some classes may implement `GPollableInputStream` but have only certain instances of that class be pollable. If `pollableInputStreamCanPoll` returns false, then the behavior of other `GPollableInputStream` methods is undefined.

Since: 2.28

Synopsis

- newtype PollableInputStream = PollableInputStream (ManagedPtr PollableInputStream)
- class (GObject o, IsDescendantOf PollableInputStream o) => IsPollableInputStream o
- toPollableInputStream :: (MonadIO m, IsPollableInputStream o) => o -> m PollableInputStream
- pollableInputStreamCanPoll :: (HasCallStack, MonadIO m, IsPollableInputStream a) => a -> m Bool
- pollableInputStreamCreateSource :: (HasCallStack, MonadIO m, IsPollableInputStream a, IsCancellable b) => a -> Maybe b -> m Source
- pollableInputStreamIsReadable :: (HasCallStack, MonadIO m, IsPollableInputStream a) => a -> m Bool
- pollableInputStreamReadNonblocking :: (HasCallStack, MonadIO m, IsPollableInputStream a, IsCancellable b) => a -> Maybe ByteString -> Maybe b -> m (Int64, Maybe ByteString)

# Exported types

newtype PollableInputStream Source #

Memory-managed wrapper type.

Constructors

PollableInputStream (ManagedPtr PollableInputStream) |

#### Instances

Instances details

Eq PollableInputStream Source # |
Instance details Defined in GI.Gio.Interfaces.PollableInputStream Methods (==) :: PollableInputStream -> PollableInputStream -> Bool Source # (/=) :: PollableInputStream -> PollableInputStream -> Bool Source #
GObject PollableInputStream Source # |
Instance details Defined in GI.Gio.Interfaces.PollableInputStream
ManagedPtrNewtype PollableInputStream Source # |
Instance details Defined in GI.Gio.Interfaces.PollableInputStream Methods toManagedPtr :: PollableInputStream -> ManagedPtr PollableInputStream Source #
TypedObject PollableInputStream Source # |
Instance details Defined in GI.Gio.Interfaces.PollableInputStream Methods glibType :: IO GType Source #
HasParentTypes PollableInputStream Source # |
Instance details Defined in GI.Gio.Interfaces.PollableInputStream
IsGValue (Maybe PollableInputStream) Source # | Convert `PollableInputStream` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gio.Interfaces.PollableInputStream Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe PollableInputStream -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe PollableInputStream) Source #
type ParentTypes PollableInputStream Source # |
Instance details Defined in GI.Gio.Interfaces.PollableInputStream type ParentTypes PollableInputStream = '[InputStream, Object]

class (GObject o, IsDescendantOf PollableInputStream o) => IsPollableInputStream o Source #

Type class for types which can be safely cast to `PollableInputStream`, for instance with `toPollableInputStream`.

#### Instances

Instances details

(GObject o, IsDescendantOf PollableInputStream o) => IsPollableInputStream o Source # |
Instance details Defined in GI.Gio.Interfaces.PollableInputStream

toPollableInputStream :: (MonadIO m, IsPollableInputStream o) => o -> m PollableInputStream Source #

Cast to `PollableInputStream`, for types for which this is known to be safe. For general casts, use `castTo`.

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

bindProperty, bindPropertyFull, canPoll, clearPending, close, closeAsync, closeFinish, createSource, forceFloating, freezeNotify, getv, hasPending, isClosed, isFloating, isReadable, notify, notifyByPspec, read, readAll, readAllAsync, readAllFinish, readAsync, readBytes, readBytesAsync, readBytesFinish, readFinish, readNonblocking, ref, refSink, runDispose, skip, skipAsync, skipFinish, stealData, stealQdata, thawNotify, unref, watchClosure.

#### Getters

getData, getProperty, getQdata.

#### Setters

setData, setDataFull, setPending, setProperty.

## canPoll

pollableInputStreamCanPoll Source #

Arguments

:: (HasCallStack, MonadIO m, IsPollableInputStream a) |
=> a | `stream`: a `PollableInputStream`.
-> m Bool | Returns: `True` if `stream` is pollable, `False` if not.

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

Since: 2.28

## createSource

pollableInputStreamCreateSource Source #

Arguments

:: (HasCallStack, MonadIO m, IsPollableInputStream a, IsCancellable b) |
=> a | `stream`: a `PollableInputStream`.
-> Maybe b | `cancellable`: a `Cancellable`, or `Nothing`
-> m Source | Returns: a new `Source`

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

As with `pollableInputStreamIsReadable`, it is possible that the stream may not actually be readable even after the source triggers, so you should use `pollableInputStreamReadNonblocking` rather than `inputStreamRead` from the callback.

The behaviour of this method is undefined if `pollableInputStreamCanPoll` returns `False` for `stream`.

Since: 2.28

## isReadable

pollableInputStreamIsReadable Source #

Arguments

:: (HasCallStack, MonadIO m, IsPollableInputStream a) |
=> a | `stream`: a `PollableInputStream`.
-> m Bool | Returns: `True` if `stream` is readable, `False` if not. If an error has occurred on `stream`, this will result in `pollableInputStreamIsReadable` returning `True`, and the next attempt to read will return the error.

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 `inputStreamRead` after this returns `True` would still block. To guarantee non-blocking behavior, you should always use `pollableInputStreamReadNonblocking`, which will return a `IOErrorEnumWouldBlock` error rather than blocking.

The behaviour of this method is undefined if `pollableInputStreamCanPoll` returns `False` for `stream`.

Since: 2.28

## readNonblocking

pollableInputStreamReadNonblocking Source #

Arguments

:: (HasCallStack, MonadIO m, IsPollableInputStream a, IsCancellable b) |
=> a | `stream`: a `PollableInputStream`
-> Maybe ByteString | `buffer`: a buffer to read data into (which should be at least `count` bytes long).
-> Maybe b | `cancellable`: a `Cancellable`, or `Nothing`
-> m (Int64, Maybe ByteString) | Returns: the number of bytes read, or -1 on error (including `IOErrorEnumWouldBlock`). (Can throw `GError`)

Attempts to read up to `count` bytes from `stream` into `buffer`, as with `inputStreamRead`. If `stream` is not currently readable, this will immediately return `IOErrorEnumWouldBlock`, and you can use `pollableInputStreamCreateSource` to create a `Source` 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.

The behaviour of this method is undefined if `pollableInputStreamCanPoll` returns `False` for `stream`.