Commit 3add5e28 authored by Philip Withnall's avatar Philip Withnall

gio: Document thread safety of the streams API

Specifically, GIOStream and the TLS connection streams.

Includes wording adapted from suggestions by Dan Winship
<danw@gnome.org>.

https://bugzilla.gnome.org/show_bug.cgi?id=735754
parent 18fe6d83
......@@ -40,7 +40,10 @@
* (g_input_stream_skip()).
*
* To copy the content of an input stream to an output stream without
* manually handling the reads and writes, use g_output_stream_splice().
* manually handling the reads and writes, use g_output_stream_splice().
*
* See the documentation for #GIOStream for details of thread safety of
* streaming APIs.
*
* All of these functions have async variants too.
**/
......
......@@ -60,6 +60,28 @@
* #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.
*
* 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.
*
* 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 #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).
*
* Since: 2.22
*/
......
......@@ -40,7 +40,10 @@
* (g_output_stream_flush()).
*
* To copy the content of an input stream to an output stream without
* manually handling the reads and writes, use g_output_stream_splice().
* manually handling the reads and writes, use g_output_stream_splice().
*
* See the documentation for #GIOStream for details of thread safety of
* streaming APIs.
*
* All of these functions have async variants too.
**/
......
......@@ -156,6 +156,10 @@ g_tls_client_connection_default_init (GTlsClientConnectionInterface *iface)
* must have pollable input and output streams) which is assumed to
* communicate with the server identified by @server_identity.
*
* See the documentation for #GTlsConnection:base-io-stream for restrictions
* on when application code can run operations on the @base_io_stream after
* this function has returned.
*
* Returns: (transfer full) (type GTlsClientConnection): the new
* #GTlsClientConnection, or %NULL on error
*
......
......@@ -95,7 +95,11 @@ g_tls_connection_class_init (GTlsConnectionClass *klass)
/**
* GTlsConnection:base-io-stream:
*
* The #GIOStream that the connection wraps
* The #GIOStream that the connection wraps. The connection holds a reference
* to this stream, and may run operations on the stream from other threads
* throughout its lifetime. Consequently, after the #GIOStream has been
* constructed, application code may only run its own operations on this
* stream when no #GIOStream operations are running.
*
* Since: 2.28
*/
......@@ -621,7 +625,8 @@ g_tls_connection_get_peer_certificate_errors (GTlsConnection *conn)
* on @conn, this will send a close notification regardless of the
* setting of this property. If you explicitly want to do an unclean
* close, you can close @conn's #GTlsConnection:base-io-stream rather
* than closing @conn itself.
* than closing @conn itself, but note that this may only be done when no other
* operations are pending on @conn or the base I/O stream.
*
* Since: 2.28
*/
......
......@@ -71,6 +71,10 @@ g_tls_server_connection_default_init (GTlsServerConnectionInterface *iface)
* Creates a new #GTlsServerConnection wrapping @base_io_stream (which
* must have pollable input and output streams).
*
* See the documentation for #GTlsConnection:base-io-stream for restrictions
* on when application code can run operations on the @base_io_stream after
* this function has returned.
*
* Returns: (transfer full) (type GTlsServerConnection): the new
* #GTlsServerConnection, or %NULL on error
*
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment