| 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.Objects.IOStream
Description
GIOStream represents an object that has both read and write streams.
Generally the two streams act as separate input and output streams,
but they share some common resources and state. For instance, for
seekable streams, both streams may use the same position.
Examples of GIOStream objects are SocketConnection, which represents
a two-way network connection; and FileIOStream, which represents a
file handle opened in read-write mode.
To do the actual reading and writing you need to get the substreams
with iOStreamGetInputStream and
iOStreamGetOutputStream.
The GIOStream object owns the input and the output streams, not the other
way around, so keeping the substreams alive will not keep the GIOStream
object alive. If the GIOStream object is freed it will be closed, thus
closing the substreams, so even if the substreams stay alive they will
always return G_IO_ERROR_CLOSED for all operations.
To close a stream use iOStreamClose which will close the common
stream object and also the individual substreams. You can also close
the substreams themselves. In most cases this only marks the
substream as closed, so further I/O on it fails but common state in the
GIOStream may still be open. However, some streams may support
‘half-closed’ states where one direction of the stream is actually shut down.
Operations on GIOStreams cannot be started while another operation on the
GIOStream or its substreams is in progress. Specifically, an application can
read from the InputStream and write to the
OutputStream simultaneously (either in separate threads, or as
asynchronous operations in the same thread), but an application cannot start
any GIOStream operation while there is a GIOStream, GInputStream or
GOutputStream operation in progress, and an application can’t start any
GInputStream or GOutputStream operation while there is a GIOStream
operation in progress.
This is a product of individual stream operations being associated with a
given [typegLib.MainContext] (the thread-default context at the time the
operation was started), rather than entire streams being associated with a
single GMainContext.
GIO may run operations on GIOStreams from other (worker) threads, and this
may be exposed to application code in the behaviour of wrapper streams, such
as BufferedInputStream or TlsConnection. With such
wrapper APIs, application code may only run operations on the base (wrapped)
stream when the wrapper stream is idle. Note that the semantics of such
operations may not be well-defined due to the state the wrapper stream leaves
the base stream in (though they are guaranteed not to crash).
Since: 2.22
Synopsis
- newtype IOStream = IOStream (ManagedPtr IOStream)
- class (GObject o, IsDescendantOf IOStream o) => IsIOStream o
- toIOStream :: (MonadIO m, IsIOStream o) => o -> m IOStream
- type family ResolveIOStreamMethod (t :: Symbol) o where ...
- data IOStreamClearPendingMethodInfo
- iOStreamClearPending :: (HasCallStack, MonadIO m, IsIOStream a) => a -> m ()
- data IOStreamCloseMethodInfo
- iOStreamClose :: (HasCallStack, MonadIO m, IsIOStream a, IsCancellable b) => a -> Maybe b -> m ()
- data IOStreamCloseAsyncMethodInfo
- iOStreamCloseAsync :: (HasCallStack, MonadIO m, IsIOStream a, IsCancellable b) => a -> Int32 -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- data IOStreamCloseFinishMethodInfo
- iOStreamCloseFinish :: (HasCallStack, MonadIO m, IsIOStream a, IsAsyncResult b) => a -> b -> m ()
- data IOStreamGetInputStreamMethodInfo
- iOStreamGetInputStream :: (HasCallStack, MonadIO m, IsIOStream a) => a -> m InputStream
- data IOStreamGetOutputStreamMethodInfo
- iOStreamGetOutputStream :: (HasCallStack, MonadIO m, IsIOStream a) => a -> m OutputStream
- data IOStreamHasPendingMethodInfo
- iOStreamHasPending :: (HasCallStack, MonadIO m, IsIOStream a) => a -> m Bool
- data IOStreamIsClosedMethodInfo
- iOStreamIsClosed :: (HasCallStack, MonadIO m, IsIOStream a) => a -> m Bool
- data IOStreamSetPendingMethodInfo
- iOStreamSetPending :: (HasCallStack, MonadIO m, IsIOStream a) => a -> m ()
- data IOStreamSpliceAsyncMethodInfo
- iOStreamSpliceAsync :: (HasCallStack, MonadIO m, IsIOStream a, IsIOStream b, IsCancellable c) => a -> b -> [IOStreamSpliceFlags] -> Int32 -> Maybe c -> Maybe AsyncReadyCallback -> m ()
- iOStreamSpliceFinish :: (HasCallStack, MonadIO m, IsAsyncResult a) => a -> m ()
- data IOStreamClosedPropertyInfo
- getIOStreamClosed :: (MonadIO m, IsIOStream o) => o -> m Bool
- iOStreamClosed :: AttrLabelProxy "closed"
- data IOStreamInputStreamPropertyInfo
- getIOStreamInputStream :: (MonadIO m, IsIOStream o) => o -> m InputStream
- iOStreamInputStream :: AttrLabelProxy "inputStream"
- data IOStreamOutputStreamPropertyInfo
- getIOStreamOutputStream :: (MonadIO m, IsIOStream o) => o -> m OutputStream
- iOStreamOutputStream :: AttrLabelProxy "outputStream"
Exported types
Memory-managed wrapper type.
Constructors
| IOStream (ManagedPtr IOStream) |
Instances
class (GObject o, IsDescendantOf IOStream o) => IsIOStream o Source #
Type class for types which can be safely cast to IOStream, for instance with toIOStream.
Instances
| (GObject o, IsDescendantOf IOStream o) => IsIOStream o Source # | |
Defined in GI.Gio.Objects.IOStream | |
toIOStream :: (MonadIO m, IsIOStream o) => o -> m IOStream Source #
Methods
Click to display all available methods, including inherited ones
Methods
bindProperty, bindPropertyFull, clearPending, close, closeAsync, closeFinish, forceFloating, freezeNotify, getv, hasPending, isClosed, isFloating, notify, notifyByPspec, ref, refSink, runDispose, spliceAsync, stealData, stealQdata, thawNotify, unref, watchClosure.
Getters
getData, getInputStream, getOutputStream, getProperty, getQdata.
Setters
type family ResolveIOStreamMethod (t :: Symbol) o where ... Source #
Equations
clearPending
data IOStreamClearPendingMethodInfo Source #
Instances
| (signature ~ m (), MonadIO m, IsIOStream a) => OverloadedMethod IOStreamClearPendingMethodInfo a signature Source # | |
Defined in GI.Gio.Objects.IOStream Methods overloadedMethod :: a -> signature # | |
| OverloadedMethodInfo IOStreamClearPendingMethodInfo (a :: Type) Source # | |
Defined in GI.Gio.Objects.IOStream Methods | |
Arguments
| :: (HasCallStack, MonadIO m, IsIOStream a) | |
| => a |
|
| -> m () |
Clears the pending flag on stream.
Since: 2.22
close
data IOStreamCloseMethodInfo Source #
Instances
| (signature ~ (Maybe b -> m ()), MonadIO m, IsIOStream a, IsCancellable b) => OverloadedMethod IOStreamCloseMethodInfo a signature Source # | |
Defined in GI.Gio.Objects.IOStream Methods overloadedMethod :: a -> signature # | |
| OverloadedMethodInfo IOStreamCloseMethodInfo (a :: Type) Source # | |
Defined in GI.Gio.Objects.IOStream Methods | |
Arguments
| :: (HasCallStack, MonadIO m, IsIOStream a, IsCancellable b) | |
| => a |
|
| -> Maybe b |
|
| -> m () | (Can throw |
Closes the stream, releasing resources related to it. This will also close the individual input and output streams, if they are not already closed.
Once the stream is closed, all other operations will return
IOErrorEnumClosed. Closing a stream multiple times will not
return an error.
Closing a stream will automatically flush any outstanding buffers in the stream.
Streams will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible.
Some streams might keep the backing store of the stream (e.g. a file descriptor) open after the stream is closed. See the documentation for the individual stream for details.
On failure the first error that happened will be reported, but the
close operation will finish as much as possible. A stream that failed
to close will still return IOErrorEnumClosed for all operations.
Still, it is important to check and report the error to the user,
otherwise there might be a loss of data as all data might not be written.
If cancellable is not NULL, then the operation can be cancelled by
triggering the cancellable object from another thread. If the operation
was cancelled, the error IOErrorEnumCancelled will be returned.
Cancelling a close will still leave the stream closed, but some streams
can use a faster close that doesn't block to e.g. check errors.
The default implementation of this method just calls close on the individual input/output streams.
Since: 2.22
closeAsync
data IOStreamCloseAsyncMethodInfo Source #
Instances
| (signature ~ (Int32 -> Maybe b -> Maybe AsyncReadyCallback -> m ()), MonadIO m, IsIOStream a, IsCancellable b) => OverloadedMethod IOStreamCloseAsyncMethodInfo a signature Source # | |
Defined in GI.Gio.Objects.IOStream Methods overloadedMethod :: a -> signature # | |
| OverloadedMethodInfo IOStreamCloseAsyncMethodInfo (a :: Type) Source # | |
Defined in GI.Gio.Objects.IOStream Methods | |
Arguments
| :: (HasCallStack, MonadIO m, IsIOStream a, IsCancellable b) | |
| => a |
|
| -> Int32 |
|
| -> Maybe b |
|
| -> Maybe AsyncReadyCallback |
|
| -> m () |
Requests an asynchronous close of the stream, releasing resources
related to it. When the operation is finished callback will be
called. You can then call iOStreamCloseFinish to get
the result of the operation.
For behaviour details see iOStreamClose.
The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all.
Since: 2.22
closeFinish
data IOStreamCloseFinishMethodInfo Source #
Instances
| (signature ~ (b -> m ()), MonadIO m, IsIOStream a, IsAsyncResult b) => OverloadedMethod IOStreamCloseFinishMethodInfo a signature Source # | |
Defined in GI.Gio.Objects.IOStream Methods overloadedMethod :: a -> signature # | |
| OverloadedMethodInfo IOStreamCloseFinishMethodInfo (a :: Type) Source # | |
Defined in GI.Gio.Objects.IOStream Methods | |
Arguments
| :: (HasCallStack, MonadIO m, IsIOStream a, IsAsyncResult b) | |
| => a |
|
| -> b |
|
| -> m () | (Can throw |
Closes a stream.
Since: 2.22
getInputStream
data IOStreamGetInputStreamMethodInfo Source #
Instances
| (signature ~ m InputStream, MonadIO m, IsIOStream a) => OverloadedMethod IOStreamGetInputStreamMethodInfo a signature Source # | |
Defined in GI.Gio.Objects.IOStream Methods overloadedMethod :: a -> signature # | |
| OverloadedMethodInfo IOStreamGetInputStreamMethodInfo (a :: Type) Source # | |
Defined in GI.Gio.Objects.IOStream Methods | |
iOStreamGetInputStream Source #
Arguments
| :: (HasCallStack, MonadIO m, IsIOStream a) | |
| => a |
|
| -> m InputStream | Returns: a |
Gets the input stream for this object. This is used for reading.
Since: 2.22
getOutputStream
data IOStreamGetOutputStreamMethodInfo Source #
Instances
| (signature ~ m OutputStream, MonadIO m, IsIOStream a) => OverloadedMethod IOStreamGetOutputStreamMethodInfo a signature Source # | |
Defined in GI.Gio.Objects.IOStream Methods overloadedMethod :: a -> signature # | |
| OverloadedMethodInfo IOStreamGetOutputStreamMethodInfo (a :: Type) Source # | |
Defined in GI.Gio.Objects.IOStream Methods | |
iOStreamGetOutputStream Source #
Arguments
| :: (HasCallStack, MonadIO m, IsIOStream a) | |
| => a |
|
| -> m OutputStream | Returns: a |
Gets the output stream for this object. This is used for writing.
Since: 2.22
hasPending
data IOStreamHasPendingMethodInfo Source #
Instances
| (signature ~ m Bool, MonadIO m, IsIOStream a) => OverloadedMethod IOStreamHasPendingMethodInfo a signature Source # | |
Defined in GI.Gio.Objects.IOStream Methods overloadedMethod :: a -> signature # | |
| OverloadedMethodInfo IOStreamHasPendingMethodInfo (a :: Type) Source # | |
Defined in GI.Gio.Objects.IOStream Methods | |
Arguments
| :: (HasCallStack, MonadIO m, IsIOStream a) | |
| => a |
|
| -> m Bool | Returns: |
Checks if a stream has pending actions.
Since: 2.22
isClosed
data IOStreamIsClosedMethodInfo Source #
Instances
| (signature ~ m Bool, MonadIO m, IsIOStream a) => OverloadedMethod IOStreamIsClosedMethodInfo a signature Source # | |
Defined in GI.Gio.Objects.IOStream Methods overloadedMethod :: a -> signature # | |
| OverloadedMethodInfo IOStreamIsClosedMethodInfo (a :: Type) Source # | |
Defined in GI.Gio.Objects.IOStream Methods | |
Arguments
| :: (HasCallStack, MonadIO m, IsIOStream a) | |
| => a |
|
| -> m Bool | Returns: |
Checks if a stream is closed.
Since: 2.22
setPending
data IOStreamSetPendingMethodInfo Source #
Instances
| (signature ~ m (), MonadIO m, IsIOStream a) => OverloadedMethod IOStreamSetPendingMethodInfo a signature Source # | |
Defined in GI.Gio.Objects.IOStream Methods overloadedMethod :: a -> signature # | |
| OverloadedMethodInfo IOStreamSetPendingMethodInfo (a :: Type) Source # | |
Defined in GI.Gio.Objects.IOStream Methods | |
Arguments
| :: (HasCallStack, MonadIO m, IsIOStream a) | |
| => a |
|
| -> m () | (Can throw |
Sets stream to have actions pending. If the pending flag is
already set or stream is closed, it will return False and set
error.
Since: 2.22
spliceAsync
data IOStreamSpliceAsyncMethodInfo Source #
Instances
| (signature ~ (b -> [IOStreamSpliceFlags] -> Int32 -> Maybe c -> Maybe AsyncReadyCallback -> m ()), MonadIO m, IsIOStream a, IsIOStream b, IsCancellable c) => OverloadedMethod IOStreamSpliceAsyncMethodInfo a signature Source # | |
Defined in GI.Gio.Objects.IOStream Methods overloadedMethod :: a -> signature # | |
| OverloadedMethodInfo IOStreamSpliceAsyncMethodInfo (a :: Type) Source # | |
Defined in GI.Gio.Objects.IOStream Methods | |
Arguments
| :: (HasCallStack, MonadIO m, IsIOStream a, IsIOStream b, IsCancellable c) | |
| => a |
|
| -> b |
|
| -> [IOStreamSpliceFlags] |
|
| -> Int32 |
|
| -> Maybe c |
|
| -> Maybe AsyncReadyCallback |
|
| -> m () |
Asynchronously splice the output stream of stream1 to the input stream of
stream2, and splice the output stream of stream2 to the input stream of
stream1.
When the operation is finished callback will be called.
You can then call iOStreamSpliceFinish to get the
result of the operation.
Since: 2.28
spliceFinish
Arguments
| :: (HasCallStack, MonadIO m, IsAsyncResult a) | |
| => a |
|
| -> m () | (Can throw |
Finishes an asynchronous io stream splice operation.
Since: 2.28
Properties
closed
Whether the stream is closed.
Since: 2.22
data IOStreamClosedPropertyInfo Source #
Instances
getIOStreamClosed :: (MonadIO m, IsIOStream o) => o -> m Bool Source #
Get the value of the “closed” property.
When overloading is enabled, this is equivalent to
get iOStream #closed
iOStreamClosed :: AttrLabelProxy "closed" Source #
inputStream
The InputStream to read from.
Since: 2.22
data IOStreamInputStreamPropertyInfo Source #
Instances
| AttrInfo IOStreamInputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream Associated Types
Methods attrGet :: AttrBaseTypeConstraint IOStreamInputStreamPropertyInfo o => o -> IO (AttrGetType IOStreamInputStreamPropertyInfo) # attrSet :: (AttrBaseTypeConstraint IOStreamInputStreamPropertyInfo o, AttrSetTypeConstraint IOStreamInputStreamPropertyInfo b) => o -> b -> IO () # attrClear :: AttrBaseTypeConstraint IOStreamInputStreamPropertyInfo o => o -> IO () # attrConstruct :: (AttrBaseTypeConstraint IOStreamInputStreamPropertyInfo o, AttrSetTypeConstraint IOStreamInputStreamPropertyInfo b) => b -> IO (GValueConstruct o) # attrTransfer :: (AttrBaseTypeConstraint IOStreamInputStreamPropertyInfo o, AttrTransferTypeConstraint IOStreamInputStreamPropertyInfo b) => Proxy o -> b -> IO (AttrTransferType IOStreamInputStreamPropertyInfo) # | |||||||||||||||||||||||||||||||||
| type AttrAllowedOps IOStreamInputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream | |||||||||||||||||||||||||||||||||
| type AttrBaseTypeConstraint IOStreamInputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
| type AttrGetType IOStreamInputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream | |||||||||||||||||||||||||||||||||
| type AttrLabel IOStreamInputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream | |||||||||||||||||||||||||||||||||
| type AttrOrigin IOStreamInputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream | |||||||||||||||||||||||||||||||||
| type AttrSetTypeConstraint IOStreamInputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream | |||||||||||||||||||||||||||||||||
| type AttrTransferType IOStreamInputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream | |||||||||||||||||||||||||||||||||
| type AttrTransferTypeConstraint IOStreamInputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream | |||||||||||||||||||||||||||||||||
getIOStreamInputStream :: (MonadIO m, IsIOStream o) => o -> m InputStream Source #
Get the value of the “input-stream” property.
When overloading is enabled, this is equivalent to
get iOStream #inputStream
iOStreamInputStream :: AttrLabelProxy "inputStream" Source #
outputStream
The OutputStream to write to.
Since: 2.22
data IOStreamOutputStreamPropertyInfo Source #
Instances
| AttrInfo IOStreamOutputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream Associated Types
Methods attrGet :: AttrBaseTypeConstraint IOStreamOutputStreamPropertyInfo o => o -> IO (AttrGetType IOStreamOutputStreamPropertyInfo) # attrSet :: (AttrBaseTypeConstraint IOStreamOutputStreamPropertyInfo o, AttrSetTypeConstraint IOStreamOutputStreamPropertyInfo b) => o -> b -> IO () # attrClear :: AttrBaseTypeConstraint IOStreamOutputStreamPropertyInfo o => o -> IO () # attrConstruct :: (AttrBaseTypeConstraint IOStreamOutputStreamPropertyInfo o, AttrSetTypeConstraint IOStreamOutputStreamPropertyInfo b) => b -> IO (GValueConstruct o) # attrTransfer :: (AttrBaseTypeConstraint IOStreamOutputStreamPropertyInfo o, AttrTransferTypeConstraint IOStreamOutputStreamPropertyInfo b) => Proxy o -> b -> IO (AttrTransferType IOStreamOutputStreamPropertyInfo) # | |||||||||||||||||||||||||||||||||
| type AttrAllowedOps IOStreamOutputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream | |||||||||||||||||||||||||||||||||
| type AttrBaseTypeConstraint IOStreamOutputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
| type AttrGetType IOStreamOutputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream | |||||||||||||||||||||||||||||||||
| type AttrLabel IOStreamOutputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream | |||||||||||||||||||||||||||||||||
| type AttrOrigin IOStreamOutputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream | |||||||||||||||||||||||||||||||||
| type AttrSetTypeConstraint IOStreamOutputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream | |||||||||||||||||||||||||||||||||
| type AttrTransferType IOStreamOutputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream | |||||||||||||||||||||||||||||||||
| type AttrTransferTypeConstraint IOStreamOutputStreamPropertyInfo Source # | |||||||||||||||||||||||||||||||||
Defined in GI.Gio.Objects.IOStream | |||||||||||||||||||||||||||||||||
getIOStreamOutputStream :: (MonadIO m, IsIOStream o) => o -> m OutputStream Source #
Get the value of the “output-stream” property.
When overloading is enabled, this is equivalent to
get iOStream #outputStream
iOStreamOutputStream :: AttrLabelProxy "outputStream" Source #