gi-gio-2.0.27: Gio bindings

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

GI.Gio.Interfaces.PollableOutputStream

Contents

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

Description

`PollableOutputStream` is implemented by `GOutputStreams` 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.

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, Word64)

# 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 # (/=) :: PollableOutputStream -> PollableOutputStream -> Bool #
GObject PollableOutputStream Source # |
Instance details Defined in GI.Gio.Interfaces.PollableOutputStream
TypedObject PollableOutputStream Source # |
Instance details Defined in GI.Gio.Interfaces.PollableOutputStream Methods glibType :: IO GType Source #
ManagedPtrNewtype PollableOutputStream Source # |
Instance details Defined in GI.Gio.Interfaces.PollableOutputStream Methods toManagedPtr :: PollableOutputStream -> ManagedPtr PollableOutputStream Source #
IsGValue PollableOutputStream Source # | Convert `PollableOutputStream` to and from `GValue` with `toGValue` and `fromGValue`.
Instance details Defined in GI.Gio.Interfaces.PollableOutputStream Methods toGValue :: PollableOutputStream -> IO GValue Source # fromGValue :: GValue -> IO PollableOutputStream Source #
HasParentTypes PollableOutputStream Source # |
Instance details Defined in GI.Gio.Interfaces.PollableOutputStream
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

## Overloaded methods

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

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.

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.

## 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, Word64) | 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.

Since: 2.60