DatagramBased

Interface for socket-like objects with datagram semantics.

A gio.datagram_based.DatagramBased is a networking interface for representing datagram-based 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 gio.socket.Socket, which wraps the UNIX socket API on UNIX and winsock2 on Windows.

gio.datagram_based.DatagramBased is entirely platform independent, and is intended to be used alongside higher-level networking APIs such as gio.iostream.IOStream.

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 the interface should take advantage of vectored I/O to minimise processing or system calls. For example, gio.socket.Socket uses recvmmsg() and sendmmsg() 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 assemble or disassemble a message.

Each gio.datagram_based.DatagramBased operation has a timeout parameter which may be negative for blocking behaviour, zero for non-blocking behaviour, or positive for timeout behaviour. A blocking operation blocks until finished or there is an error. A non-blocking operation will return immediately with a gio.types.IOErrorEnum.WouldBlock error if it cannot make progress. A timeout operation will block until the operation is complete or the timeout expires; if the timeout expires it will return what progress it made, or gio.types.IOErrorEnum.TimedOut if no progress was made. To know when a call would successfully run you can call gio.datagram_based.DatagramBased.conditionCheck or gio.datagram_based.DatagramBased.conditionWait. You can also use gio.datagram_based.DatagramBased.createSource and attach it to a glib.main_context.MainContext to get callbacks when I/O is possible.

When running a non-blocking operation applications should always be able to handle getting a gio.types.IOErrorEnum.WouldBlock error even when some other 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 reasons. For instance, on Windows a socket is always seen as writable until a write returns gio.types.IOErrorEnum.WouldBlock.

As with gio.socket.Socket, gio.datagram_based.DatagramBaseds can be either connection oriented (for example, SCTP) or connectionless (for example, UDP). gio.datagram_based.DatagramBaseds must be datagram-based, not stream-based. The interface does not cover connection establishment — use methods on the underlying type to establish a connection before sending and receiving data through the gio.datagram_based.DatagramBased API. For connectionless socket types the target/source address is specified or received in each I/O operation.

Like most other APIs in GLib, gio.datagram_based.DatagramBased is not inherently thread safe. To use a gio.datagram_based.DatagramBased concurrently from multiple threads, you must implement your own locking.

Members

Functions

conditionCheck
glib.types.IOCondition conditionCheck(glib.types.IOCondition condition)

Checks on the readiness of datagram_based to perform operations. The operations specified in condition are checked for and masked against the currently-satisfied conditions on datagram_based. The result is returned.

conditionWait
bool conditionWait(glib.types.IOCondition condition, long timeout, gio.cancellable.Cancellable cancellable)

Waits for up to timeout microseconds for condition to become true on datagram_based. If the condition is met, true is returned.

createSource
glib.source.Source createSource(glib.types.IOCondition condition, gio.cancellable.Cancellable cancellable)

Creates a #GSource that can be attached to a #GMainContext to monitor for the availability of the specified condition on the #GDatagramBased. The #GSource keeps a reference to the datagram_based.