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

Contents

- Exported types
- Methods
  - canPoll
  - createSource
  - isWritable
  - writeNonblocking
  - writevNonblocking

Description

`GPollableOutputStream` is implemented by `OutputStream`s that can be polled for readiness to write. 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 `GPollableOutputStream` but have only certain instances of that class be pollable. If `pollableOutputStreamCanPoll` returns false, then the behavior of other `GPollableOutputStream` methods is undefined.

Since: 2.28

Synopsis

- newtype PollableOutputStream = PollableOutputStream (ManagedPtr PollableOutputStream)
- class (GObject o, IsDescendantOf PollableOutputStream o) => IsPollableOutputStream o
- toPollableOutputStream :: (MonadIO m, IsPollableOutputStream o) => o -> m PollableOutputStream
- pollableOutputStreamCanPoll :: (HasCallStack, MonadIO m, IsPollableOutputStream a) => a -> m Bool
- pollableOutputStreamCreateSource :: (HasCallStack, MonadIO m, IsPollableOutputStream a, IsCancellable b) => a -> Maybe b -> m Source
- pollableOutputStreamIsWritable :: (HasCallStack, MonadIO m, IsPollableOutputStream a) => a -> m Bool
- pollableOutputStreamWriteNonblocking :: (HasCallStack, MonadIO m, IsPollableOutputStream a, IsCancellable b) => a -> Maybe ByteString -> Maybe b -> m Int64
- pollableOutputStreamWritevNonblocking :: (HasCallStack, MonadIO m, IsPollableOutputStream a, IsCancellable b) => a -> [OutputVector] -> Maybe b -> m (PollableReturn, CSize)

# Exported types

newtype PollableOutputStream Source #

Memory-managed wrapper type.

Constructors

PollableOutputStream (ManagedPtr PollableOutputStream) |

#### Instances

Instances details

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

class (GObject o, IsDescendantOf PollableOutputStream o) => IsPollableOutputStream o Source #

Type class for types which can be safely cast to `PollableOutputStream`, for instance with `toPollableOutputStream`.

#### Instances

Instances details

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

toPollableOutputStream :: (MonadIO m, IsPollableOutputStream o) => o -> m PollableOutputStream Source #

Cast to `PollableOutputStream`, 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, flush, flushAsync, flushFinish, forceFloating, freezeNotify, getv, hasPending, isClosed, isClosing, isFloating, isWritable, notify, notifyByPspec, ref, refSink, runDispose, splice, spliceAsync, spliceFinish, stealData, stealQdata, thawNotify, unref, watchClosure, write, writeAll, writeAllAsync, writeAllFinish, writeAsync, writeBytes, writeBytesAsync, writeBytesFinish, writeFinish, writeNonblocking, writev, writevAll, writevAllAsync, writevAllFinish, writevAsync, writevFinish, writevNonblocking.

#### Getters

getData, getProperty, getQdata.

#### Setters

setData, setDataFull, setPending, setProperty.

## canPoll

pollableOutputStreamCanPoll Source #

Arguments

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

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

pollableOutputStreamCreateSource Source #

Arguments

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

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

As with `pollableOutputStreamIsWritable`, it is possible that the stream may not actually be writable even after the source triggers, so you should use `pollableOutputStreamWriteNonblocking` rather than `outputStreamWrite` from the callback.

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

Since: 2.28

## isWritable

pollableOutputStreamIsWritable Source #

Arguments

:: (HasCallStack, MonadIO m, IsPollableOutputStream a) |
=> a | `stream`: a `PollableOutputStream`.
-> m Bool | Returns: `True` if `stream` is writable, `False` if not. If an error has occurred on `stream`, this will result in `pollableOutputStreamIsWritable` returning `True`, and the next attempt to write will return the error.

Checks if `stream` can be written.

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

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

Since: 2.28

## writeNonblocking

pollableOutputStreamWriteNonblocking Source #

Arguments

:: (HasCallStack, MonadIO m, IsPollableOutputStream a, IsCancellable b) |
=> a | `stream`: a `PollableOutputStream`
-> Maybe ByteString | `buffer`: a buffer to write data from
-> Maybe b | `cancellable`: a `Cancellable`, or `Nothing`
-> m Int64 | Returns: the number of bytes written, or -1 on error (including `IOErrorEnumWouldBlock`). (Can throw `GError`)

Attempts to write up to `count` bytes from `buffer` to `stream`, as with `outputStreamWrite`. If `stream` is not currently writable, this will immediately return `IOErrorEnumWouldBlock`, and you can use `pollableOutputStreamCreateSource` to create a `Source` that will be triggered when `stream` is writable.

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.

Also note that if `IOErrorEnumWouldBlock` is returned some underlying transports like D/TLS require that you re-send the same `buffer` and `count` in the next write call.

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

## writevNonblocking

pollableOutputStreamWritevNonblocking Source #

Arguments

:: (HasCallStack, MonadIO m, IsPollableOutputStream a, IsCancellable b) |
=> a | `stream`: a `PollableOutputStream`
-> [OutputVector] | `vectors`: the buffer containing the `GOutputVectors` to write.
-> Maybe b | `cancellable`: a `Cancellable`, or `Nothing`
-> m (PollableReturn, CSize) | Returns: %`gPOLLABLERETURNOK` on success, `PollableReturnWouldBlock` if the stream is not currently writable (and `error` is *not* set), or `PollableReturnFailed` if there was an error in which case `error` will be set. (Can throw `GError`)

Attempts to write the bytes contained in the `nVectors` `vectors` to `stream`, as with `outputStreamWritev`. If `stream` is not currently writable, this will immediately return %`gPOLLABLERETURNWOULDBLOCK`, and you can use `pollableOutputStreamCreateSource` to create a `Source` that will be triggered when `stream` is writable. `error` will *not* be set in that case.

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.

Also note that if `PollableReturnWouldBlock` is returned some underlying transports like D/TLS require that you re-send the same `vectors` and `nVectors` in the next write call.

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

Since: 2.60