mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-24 22:46:15 +01:00
docs: Move the GDatagramBased SECTION
Move contents to struct docs. Helps: #3037
This commit is contained in:
parent
926f56c7c7
commit
081cc5af25
@ -32,57 +32,56 @@
|
|||||||
#include "glibintl.h"
|
#include "glibintl.h"
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* SECTION:gdatagrambased
|
* GDatagramBased:
|
||||||
* @short_description: Low-level datagram communications interface
|
|
||||||
* @include: gio/gio.h
|
|
||||||
* @see_also: #GSocket, [<gnetworking.h>][gio-gnetworking.h]
|
|
||||||
*
|
*
|
||||||
* A #GDatagramBased is a networking interface for representing datagram-based
|
* Interface for socket-like objects with datagram semantics.
|
||||||
|
*
|
||||||
|
* A `GDatagramBased` is a networking interface for representing datagram-based
|
||||||
* communications. It is a more or less direct mapping of the core parts of the
|
* communications. It is a more or less direct mapping of the core parts of the
|
||||||
* BSD socket API in a portable GObject interface. It is implemented by
|
* BSD socket API in a portable GObject interface. It is implemented by
|
||||||
* #GSocket, which wraps the UNIX socket API on UNIX and winsock2 on Windows.
|
* [struct@Gio.Socket], which wraps the UNIX socket API on UNIX and winsock2 on Windows.
|
||||||
*
|
*
|
||||||
* #GDatagramBased is entirely platform independent, and is intended to be used
|
* `GDatagramBased` is entirely platform independent, and is intended to be used
|
||||||
* alongside higher-level networking APIs such as #GIOStream.
|
* alongside higher-level networking APIs such as [struct@Gio.IOStream].
|
||||||
*
|
*
|
||||||
* It uses vectored scatter/gather I/O by default, allowing for many messages
|
* It uses vectored scatter/gather I/O by default, allowing for many messages
|
||||||
* to be sent or received in a single call. Where possible, implementations of
|
* to be sent or received in a single call. Where possible, implementations of
|
||||||
* the interface should take advantage of vectored I/O to minimise processing
|
* the interface should take advantage of vectored I/O to minimise processing
|
||||||
* or system calls. For example, #GSocket uses recvmmsg() and sendmmsg() where
|
* or system calls. For example, `GSocket` uses `recvmmsg()` and `sendmmsg()`
|
||||||
* possible. Callers should take advantage of scatter/gather I/O (the use of
|
* where possible. Callers should take advantage of scatter/gather I/O (the use of
|
||||||
* multiple buffers per message) to avoid unnecessary copying of data to
|
* multiple buffers per message) to avoid unnecessary copying of data to
|
||||||
* assemble or disassemble a message.
|
* assemble or disassemble a message.
|
||||||
*
|
*
|
||||||
* Each #GDatagramBased operation has a timeout parameter which may be negative
|
* Each `GDatagramBased` operation has a timeout parameter which may be negative
|
||||||
* for blocking behaviour, zero for non-blocking behaviour, or positive for
|
* for blocking behaviour, zero for non-blocking behaviour, or positive for
|
||||||
* timeout behaviour. A blocking operation blocks until finished or there is an
|
* timeout behaviour. A blocking operation blocks until finished or there is an
|
||||||
* error. A non-blocking operation will return immediately with a
|
* error. A non-blocking operation will return immediately with a
|
||||||
* %G_IO_ERROR_WOULD_BLOCK error if it cannot make progress. A timeout operation
|
* `G_IO_ERROR_WOULD_BLOCK` error if it cannot make progress. A timeout operation
|
||||||
* will block until the operation is complete or the timeout expires; if the
|
* will block until the operation is complete or the timeout expires; if the
|
||||||
* timeout expires it will return what progress it made, or
|
* timeout expires it will return what progress it made, or
|
||||||
* %G_IO_ERROR_TIMED_OUT if no progress was made. To know when a call would
|
* `G_IO_ERROR_TIMED_OUT` if no progress was made. To know when a call would
|
||||||
* successfully run you can call g_datagram_based_condition_check() or
|
* successfully run you can call [method@Gio.DatagramBased.condition_check] or
|
||||||
* g_datagram_based_condition_wait(). You can also use
|
* [method@Gio.DatagramBased.condition_wait]. You can also use
|
||||||
* g_datagram_based_create_source() and attach it to a #GMainContext to get
|
* [method@Gio.DatagramBased.create_source] and attach it to a [struct@Glib.MainContext]
|
||||||
* callbacks when I/O is possible.
|
* to get callbacks when I/O is possible.
|
||||||
*
|
*
|
||||||
* When running a non-blocking operation applications should always be able to
|
* When running a non-blocking operation applications should always be able to
|
||||||
* handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other function
|
* 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 of a race
|
* 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 reasons. For
|
* condition in the application, but it can also happen for other reasons. For
|
||||||
* instance, on Windows a socket is always seen as writable until a write
|
* instance, on Windows a socket is always seen as writable until a write
|
||||||
* returns %G_IO_ERROR_WOULD_BLOCK.
|
* returns `G_IO_ERROR_WOULD_BLOCK`.
|
||||||
*
|
*
|
||||||
* As with #GSocket, #GDatagramBaseds can be either connection oriented (for
|
* As with `GSocket`, `GDatagramBased`s can be either connection oriented (for
|
||||||
* example, SCTP) or connectionless (for example, UDP). #GDatagramBaseds must be
|
* example, SCTP) or connectionless (for example, UDP). `GDatagramBased`s must be
|
||||||
* datagram-based, not stream-based. The interface does not cover connection
|
* datagram-based, not stream-based. The interface does not cover connection
|
||||||
* establishment — use methods on the underlying type to establish a connection
|
* establishment — use methods on the underlying type to establish a connection
|
||||||
* before sending and receiving data through the #GDatagramBased API. For
|
* before sending and receiving data through the `GDatagramBased` API. For
|
||||||
* connectionless socket types the target/source address is specified or
|
* connectionless socket types the target/source address is specified or
|
||||||
* received in each I/O operation.
|
* received in each I/O operation.
|
||||||
*
|
*
|
||||||
* Like most other APIs in GLib, #GDatagramBased is not inherently thread safe.
|
* Like most other APIs in GLib, `GDatagramBased` is not inherently thread safe.
|
||||||
* To use a #GDatagramBased concurrently from multiple threads, you must
|
* To use a `GDatagramBased` concurrently from multiple threads, you must
|
||||||
* implement your own locking.
|
* implement your own locking.
|
||||||
*
|
*
|
||||||
* Since: 2.48
|
* Since: 2.48
|
||||||
|
@ -41,13 +41,6 @@ G_BEGIN_DECLS
|
|||||||
#define G_TYPE_IS_DATAGRAM_BASED(type) (g_type_is_a ((type), \
|
#define G_TYPE_IS_DATAGRAM_BASED(type) (g_type_is_a ((type), \
|
||||||
G_TYPE_DATAGRAM_BASED))
|
G_TYPE_DATAGRAM_BASED))
|
||||||
|
|
||||||
/**
|
|
||||||
* GDatagramBased:
|
|
||||||
*
|
|
||||||
* Interface for socket-like objects with datagram semantics.
|
|
||||||
*
|
|
||||||
* Since: 2.48
|
|
||||||
*/
|
|
||||||
typedef struct _GDatagramBasedInterface GDatagramBasedInterface;
|
typedef struct _GDatagramBasedInterface GDatagramBasedInterface;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
Loading…
Reference in New Issue
Block a user