docs: Move the GSocket SECTION

Move it to the struct docs.

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

Helps: #3037
This commit is contained in:
Philip Withnall 2023-10-24 10:57:35 +01:00
parent 0b0179678a
commit bd753fb87c

View File

@ -83,46 +83,44 @@
#endif #endif
/** /**
* SECTION:gsocket * GSocket:
* @short_description: Low-level socket object
* @include: gio/gio.h
* @see_also: #GInitable, [<gnetworking.h>][gio-gnetworking.h]
* *
* A #GSocket is a low-level networking primitive. It is a more or less * A `GSocket` is a low-level networking primitive. It is a more or less
* direct mapping of the BSD socket API in a portable GObject based API. * direct mapping of the BSD socket API in a portable GObject based API.
* It supports both the UNIX socket implementations and winsock2 on Windows. * It supports both the UNIX socket implementations and winsock2 on Windows.
* *
* #GSocket is the platform independent base upon which the higher level * `GSocket` is the platform independent base upon which the higher level
* network primitives are based. Applications are not typically meant to * network primitives are based. Applications are not typically meant to
* use it directly, but rather through classes like #GSocketClient, * use it directly, but rather through classes like [class@Gio.SocketClient],
* #GSocketService and #GSocketConnection. However there may be cases where * [class@Gio.SocketService] and [class@Gio.SocketConnection]. However there may
* direct use of #GSocket is useful. * be cases where direct use of `GSocket` is useful.
* *
* #GSocket implements the #GInitable interface, so if it is manually constructed * `GSocket` implements the [iface@Gio.Initable] interface, so if it is manually
* by e.g. g_object_new() you must call g_initable_init() and check the * constructed by e.g. [ctor@GObject.Object.new] you must call
* results before using the object. This is done automatically in * [method@Gio.Initable.init] and check the results before using the object.
* g_socket_new() and g_socket_new_from_fd(), so these functions can return * This is done automatically in [ctor@Gio.Socket.new] and
* %NULL. * [ctor@Gio.Socket.new_from_fd], so these functions can return `NULL`.
* *
* Sockets operate in two general modes, blocking or non-blocking. When * Sockets operate in two general modes, blocking or non-blocking. When
* in blocking mode all operations (which dont take an explicit blocking * in blocking mode all operations (which dont take an explicit blocking
* parameter) block until the requested operation * parameter) block until the requested operation
* is finished or there is an error. In non-blocking mode all calls that * is finished or there is an error. In non-blocking mode all calls that
* would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error. * would block return immediately with a `G_IO_ERROR_WOULD_BLOCK` error.
* To know when a call would successfully run you can call g_socket_condition_check(), * To know when a call would successfully run you can call
* or g_socket_condition_wait(). You can also use g_socket_create_source() and * [method@Gio.Socket.condition_check], or [method@Gio.Socket.condition_wait].
* attach it to a #GMainContext to get callbacks when I/O is possible. * You can also use [method@Gio.Socket.create_source] and attach it to a
* [type@GLib.MainContext] to get callbacks when I/O is possible.
* Note that all sockets are always set to non blocking mode in the system, and * Note that all sockets are always set to non blocking mode in the system, and
* blocking mode is emulated in GSocket. * blocking mode is emulated in `GSocket`.
* *
* When working in non-blocking mode applications should always be able to * When working in non-blocking mode applications should always be able to
* handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other * handle getting a `G_IO_ERROR_WOULD_BLOCK` error even when some other
* function said that I/O was possible. This can easily happen in case * function said that I/O was possible. This can easily happen in case
* of a race condition in the application, but it can also happen for other * of a race condition in the application, but it can also happen for other
* reasons. For instance, on Windows a socket is always seen as writable * reasons. For instance, on Windows a socket is always seen as writable
* until a write returns %G_IO_ERROR_WOULD_BLOCK. * until a write returns `G_IO_ERROR_WOULD_BLOCK`.
* *
* #GSockets can be either connection oriented or datagram based. * `GSocket`s can be either connection oriented or datagram based.
* For connection oriented types you must first establish a connection by * For connection oriented types you must first establish a connection by
* either connecting to an address or accepting a connection from another * either connecting to an address or accepting a connection from another
* address. For connectionless socket types the target/source address is * address. For connectionless socket types the target/source address is
@ -130,14 +128,14 @@
* *
* All socket file descriptors are set to be close-on-exec. * All socket file descriptors are set to be close-on-exec.
* *
* Note that creating a #GSocket causes the signal %SIGPIPE to be * Note that creating a `GSocket` causes the signal `SIGPIPE` to be
* ignored for the remainder of the program. If you are writing a * ignored for the remainder of the program. If you are writing a
* command-line utility that uses #GSocket, you may need to take into * command-line utility that uses `GSocket`, you may need to take into
* account the fact that your program will not automatically be killed * account the fact that your program will not automatically be killed
* if it tries to write to %stdout after it has been closed. * if it tries to write to `stdout` after it has been closed.
* *
* Like most other APIs in GLib, #GSocket is not inherently thread safe. To use * Like most other APIs in GLib, `GSocket` is not inherently thread safe. To use
* a #GSocket concurrently from multiple threads, you must implement your own * a `GSocket` concurrently from multiple threads, you must implement your own
* locking. * locking.
* *
* Since: 2.22 * Since: 2.22