module Gio::DatagramBased

Overview

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 BSD socket API in a portable GObject interface. It is implemented by 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 alongside higher-level networking APIs such as Gio::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, GSocket 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 GDatagramBased 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 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 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 successfully run you can call Gio::DatagramBased#condition_check or Gio::DatagramBased#condition_wait. You can also use Gio::DatagramBased#create_source and attach it to a GLib::MainContext to get callbacks when I/O is possible.

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 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 G_IO_ERROR_WOULD_BLOCK.

As with GSocket, GDatagramBaseds can be either connection oriented (for example, SCTP) or connectionless (for example, UDP). GDatagramBaseds 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 GDatagramBased API. For connectionless socket types the target/source address is specified or received in each I/O operation.

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

Direct including types

• Gio::Socket

Defined in:

lib/gi-crystal/src/auto/gio-2.0/datagram_based.cr

Constructors

• .cast(obj : GObject::Object) : self

  Cast a GObject::Object to self, throws a TypeCastError if the cast can't be made.

Class Method Summary

• .cast?(obj : GObject::Object) : self | Nil
• .g_type : UInt64

Instance Method Summary

• #condition_check(condition : GLib::IOCondition) : GLib::IOCondition
• #condition_wait(condition : GLib::IOCondition, timeout : Int64, cancellable : Gio::Cancellable | Nil) : Bool
• #create_source(condition : GLib::IOCondition, cancellable : Gio::Cancellable | Nil) : GLib::Source
• #receive_messages(messages : Enumerable(Gio::InputMessage), flags : Int32, timeout : Int64, cancellable : Gio::Cancellable | Nil) : Int32
• #send_messages(messages : Enumerable(Gio::OutputMessage), flags : Int32, timeout : Int64, cancellable : Gio::Cancellable | Nil) : Int32
• #to_unsafe

Constructor Detail

Class Method Detail

Instance Method Detail