gi-gio-2.0.19: Gio bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com)
Safe Haskell | None
Language | Haskell2010

GI.Gio.Interfaces.PollableInputStream

Contents

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

Description

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

Since: 2.28

Synopsis

- newtype PollableInputStream = PollableInputStream (ManagedPtr PollableInputStream)
- noPollableInputStream :: Maybe PollableInputStream
- class GObject 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

# Exported types

newtype PollableInputStream Source #

Memory-managed wrapper type.

Constructors

PollableInputStream (ManagedPtr PollableInputStream) |

Instances

GObject PollableInputStream Source # |
Instance details Defined in GI.Gio.Interfaces.PollableInputStream Methods gobjectType :: PollableInputStream -> IO GType Source #
IsObject PollableInputStream Source # |
Instance details Defined in GI.Gio.Interfaces.PollableInputStream
IsPollableInputStream PollableInputStream Source # |
Instance details Defined in GI.Gio.Interfaces.PollableInputStream
IsInputStream PollableInputStream Source # |
Instance details Defined in GI.Gio.Interfaces.PollableInputStream

noPollableInputStream :: Maybe PollableInputStream Source #

A convenience alias for `Nothing` :: `Maybe` `PollableInputStream`.

class GObject o => IsPollableInputStream o Source #

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

Instances

(GObject a, (UnknownAncestorError PollableInputStream a :: Constraint)) => IsPollableInputStream a Source # |
Instance details Defined in GI.Gio.Interfaces.PollableInputStream
IsPollableInputStream PollableInputStream Source # |
Instance details Defined in GI.Gio.Interfaces.PollableInputStream
IsPollableInputStream ConverterInputStream Source # |
Instance details Defined in GI.Gio.Objects.ConverterInputStream
IsPollableInputStream MemoryInputStream Source # |
Instance details Defined in GI.Gio.Objects.MemoryInputStream
IsPollableInputStream UnixInputStream Source # |
Instance details Defined in GI.Gio.Objects.UnixInputStream

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

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

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.

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