luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-11 23:16:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Move the GIOStream SECTION

Browse Source 
Move the contents to the struct docs.

Signed-off-by: Philip Withnall <philip@tecnocode.co.uk>

Helps: #3037
This commit is contained in:
Philip Withnall 2023-10-23 00:44:20 +01:00
parent 71ff617159
commit eefda8158e
2 changed files with 31 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
gio/giostream.c
View File

@ -32,57 +32,56 @@
#include "gtask.h"
/**
* SECTION:giostream
* @short_description: Base class for implementing read/write streams
* @include: gio/gio.h
* @see_also: #GInputStream, #GOutputStream
* GIOStream:
*
* GIOStream represents an object that has both read and write streams.
* `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 #GSocketConnection, which represents
* a two-way network connection; and #GFileIOStream, which represents a
* Examples of `GIOStream` objects are [class@Gio.SocketConnection], which represents
* a two-way network connection; and [class@Gio.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 g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
* with [method@Gio.IOStream.get_input_stream] and
* [method@Gio.IOStream.get_output_stream].
*
* 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
* 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.
* always return `G_IO_ERROR_CLOSED` for all operations.
*
* To close a stream use g_io_stream_close() which will close the common
* To close a stream use [method@Gio.IOStream.close] 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.
* `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 #GInputStream and write to the #GOutputStream 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.
* Operations on `GIOStream`s cannot be started while another operation on the
* `GIOStream` or its substreams is in progress. Specifically, an application can
* read from the [class@Gio.InputStream] and write to the
* [class@Gio.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 #GMainContext (the thread-default context at the time the operation was
* started), rather than entire streams being associated with a single
* #GMainContext.
* given [type@GLib.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
* GIO may run operations on `GIOStream`s from other (worker) threads, and this
* may be exposed to application code in the behaviour of wrapper streams, such
* as #GBufferedInputStream or #GTlsConnection. 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).
* as [class@Gio.BufferedInputStream] or [class@Gio.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
*/

5
gio/giostream.h
View File

@ -40,11 +40,6 @@ G_BEGIN_DECLS
typedef struct _GIOStreamPrivate GIOStreamPrivate;
typedef struct _GIOStreamClass GIOStreamClass;
/**
* GIOStream:
*
* Base class for read-write streams.
**/
struct _GIOStream
{
GObject parent_instance;