[gobject-introspection] gir: Update annotations from GLib git master

[Rico Tzschichholz <ricotz src gnome org>]

commit d0680d574474e22f0b9877c8411c74507b2eaa2f
Author: Rico Tzschichholz <ricotz ubuntu com>
Date:   Sun Oct 25 21:33:34 2015 +0100

    gir: Update annotations from GLib git master

 gir/gio-2.0.c  |  300 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 gir/glib-2.0.c |   17 +++-
 2 files changed, 316 insertions(+), 1 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 7dcb173..ffb0161 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -4961,6 +4961,63 @@
 
 
 /**
+ * SECTION: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
+ * 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
+ * #GSocket, 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 #GIOStream.
+ *
+ * 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 g_datagram_based_condition_check() or
+ * g_datagram_based_condition_wait(). You can also use
+ * g_datagram_based_create_source() and attach it to a #GMainContext 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 or
+ * connectionless. 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.
+ *
+ * Since: 2.48
+ */
+
+
+/**
  * SECTION:gdatainputstream
  * @short_description: Data Input Stream
  * @include: gio/gio.h
@@ -15219,6 +15276,232 @@
 
 
 /**
+ * g_datagram_based_condition_check:
+ * @datagram_based: a #GDatagramBased
+ * @condition: a #GIOCondition mask to check
+ *
+ * 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.
+ *
+ * %G_IO_IN will be set in the return value if data is available to read with
+ * g_datagram_based_receive_messages(), or if the connection is closed remotely
+ * (EOS); and if the datagram_based has not been closed locally using some
+ * implementation-specific method (such as g_socket_close() or
+ * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket).
+ *
+ * If the connection is shut down or closed (by calling g_socket_close() or
+ * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
+ * example), all calls to this function will return %G_IO_ERROR_CLOSED.
+ *
+ * %G_IO_OUT will be set if it is expected that at least one byte can be sent
+ * using g_datagram_based_send_messages() without blocking. It will not be set
+ * if the datagram_based has been closed locally.
+ *
+ * %G_IO_HUP will be set if the connection has been closed locally.
+ *
+ * %G_IO_ERR will be set if there was an asynchronous error in transmitting data
+ * previously enqueued using g_datagram_based_send_messages().
+ *
+ * Note that on Windows, it is possible for an operation to return
+ * %G_IO_ERROR_WOULD_BLOCK even immediately after
+ * g_datagram_based_condition_check() has claimed that the #GDatagramBased is
+ * ready for writing. Rather than calling g_datagram_based_condition_check() and
+ * then writing to the #GDatagramBased if it succeeds, it is generally better to
+ * simply try writing right away, and try again later if the initial attempt
+ * returns %G_IO_ERROR_WOULD_BLOCK.
+ *
+ * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
+ * conditions will always be set in the output if they are true. Apart from
+ * these flags, the output is guaranteed to be masked by @condition.
+ *
+ * This call never blocks.
+ *
+ * Returns: the #GIOCondition mask of the current state
+ * Since: 2.48
+ */
+
+
+/**
+ * g_datagram_based_condition_wait:
+ * @datagram_based: a #GDatagramBased
+ * @condition: a #GIOCondition mask to wait for
+ * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1
+ *   to block indefinitely
+ * @cancellable: (nullable): a #GCancellable
+ * @error: return location for a #GError
+ *
+ * Waits for up to @timeout microseconds for condition to become true on
+ * @datagram_based. If the condition is met, %TRUE is returned.
+ *
+ * If @cancellable is cancelled before the condition is met, or if @timeout is
+ * reached before the condition is met, then %FALSE is returned and @error is
+ * set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT).
+ *
+ * Returns: %TRUE if the condition was met, %FALSE otherwise
+ * Since: 2.48
+ */
+
+
+/**
+ * g_datagram_based_create_source:
+ * @datagram_based: a #GDatagramBased
+ * @condition: a #GIOCondition mask to monitor
+ * @cancellable: (nullable): a #GCancellable
+ *
+ * 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.
+ *
+ * The callback on the source is of the #GDatagramBasedSourceFunc type.
+ *
+ * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these
+ * conditions will always be reported in the callback if they are true.
+ *
+ * If non-%NULL, @cancellable can be used to cancel the source, which will
+ * cause the source to trigger, reporting the current condition (which is
+ * likely 0 unless cancellation happened at the same time as a condition
+ * change). You can check for this in the callback using
+ * g_cancellable_is_cancelled().
+ *
+ * Returns: (transfer full): a newly allocated #GSource
+ * Since: 2.48
+ */
+
+
+/**
+ * g_datagram_based_receive_messages:
+ * @datagram_based: a #GDatagramBased
+ * @messages: (array length=num_messages): an array of #GInputMessage structs
+ * @num_messages: the number of elements in @messages
+ * @flags: an int containing #GSocketMsgFlags flags for the overall operation
+ * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1
+ *   to block indefinitely
+ * @cancellable: (allow-none): a %GCancellable
+ * @error: return location for a #GError
+ *
+ * Receive one or more data messages from @datagram_based in one go.
+ *
+ * @messages must point to an array of #GInputMessage structs and
+ * @num_messages must be the length of this array. Each #GInputMessage
+ * contains a pointer to an array of #GInputVector structs describing the
+ * buffers that the data received in each message will be written to.
+ *
+ * @flags modify how all messages are received. The commonly available
+ * arguments for this are available in the #GSocketMsgFlags enum, but the
+ * values there are the same as the system values, and the flags
+ * are passed in as-is, so you can pass in system-specific flags too. These
+ * flags affect the overall receive operation. Flags affecting individual
+ * messages are returned in #GInputMessage.flags.
+ *
+ * The other members of #GInputMessage are treated as described in its
+ * documentation.
+ *
+ * If @timeout is negative the call will block until @num_messages have been
+ * received, the connection is closed remotely (EOS), @cancellable is cancelled,
+ * or an error occurs.
+ *
+ * If @timeout is 0 the call will return up to @num_messages without blocking,
+ * or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system
+ * to be received.
+ *
+ * If @timeout is positive the call will block on the same conditions as if
+ * @timeout were negative. If the timeout is reached
+ * before any messages are received, %G_IO_ERROR_TIMED_OUT is returned,
+ * otherwise it will return the number of messages received before timing out.
+ * (Note: This is effectively the behaviour of `MSG_WAITFORONE` with
+ * recvmmsg().)
+ *
+ * To be notified when messages are available, wait for the %G_IO_IN condition.
+ * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
+ * g_datagram_based_receive_messages() even if you were previously notified of a
+ * %G_IO_IN condition.
+ *
+ * If the remote peer closes the connection, any messages queued in the
+ * underlying receive buffer will be returned, and subsequent calls to
+ * g_datagram_based_receive_messages() will return 0 (with no error set).
+ *
+ * If the connection is shut down or closed (by calling g_socket_close() or
+ * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for
+ * example), all calls to this function will return %G_IO_ERROR_CLOSED.
+ *
+ * On error -1 is returned and @error is set accordingly. An error will only
+ * be returned if zero messages could be received; otherwise the number of
+ * messages successfully received before the error will be returned. If
+ * @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any
+ * other error.
+ *
+ * Returns: number of messages received, or -1 on error. Note that the number
+ *     of messages received may be smaller than @num_messages if @timeout is
+ *     zero or positive, if the peer closed the connection, or if @num_messages
+ *     was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try
+ *     to receive the remaining messages.
+ * Since: 2.48
+ */
+
+
+/**
+ * g_datagram_based_send_messages:
+ * @datagram_based: a #GDatagramBased
+ * @messages: (array length=num_messages): an array of #GOutputMessage structs
+ * @num_messages: the number of elements in @messages
+ * @flags: an int containing #GSocketMsgFlags flags
+ * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1
+ *   to block indefinitely
+ * @cancellable: (nullable): a %GCancellable
+ * @error: return location for a #GError
+ *
+ * Send one or more data messages from @datagram_based in one go.
+ *
+ * @messages must point to an array of #GOutputMessage structs and
+ * @num_messages must be the length of this array. Each #GOutputMessage
+ * contains an address to send the data to, and a pointer to an array of
+ * #GOutputVector structs to describe the buffers that the data to be sent
+ * for each message will be gathered from.
+ *
+ * @flags modify how the message is sent. The commonly available arguments
+ * for this are available in the #GSocketMsgFlags enum, but the
+ * values there are the same as the system values, and the flags
+ * are passed in as-is, so you can pass in system-specific flags too.
+ *
+ * The other members of #GOutputMessage are treated as described in its
+ * documentation.
+ *
+ * If @timeout is negative the call will block until @num_messages have been
+ * sent, @cancellable is cancelled, or an error occurs.
+ *
+ * If @timeout is 0 the call will send up to @num_messages without blocking,
+ * or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages.
+ *
+ * If @timeout is positive the call will block on the same conditions as if
+ * @timeout were negative. If the timeout is reached before any messages are
+ * sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number
+ * of messages sent before timing out.
+ *
+ * To be notified when messages can be sent, wait for the %G_IO_OUT condition.
+ * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from
+ * g_datagram_based_send_messages() even if you were previously notified of a
+ * %G_IO_OUT condition. (On Windows in particular, this is very common due to
+ * the way the underlying APIs work.)
+ *
+ * If the connection is shut down or closed (by calling g_socket_close() or
+ * g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for
+ * example), all calls to this function will return %G_IO_ERROR_CLOSED.
+ *
+ * On error -1 is returned and @error is set accordingly. An error will only
+ * be returned if zero messages could be sent; otherwise the number of messages
+ * successfully sent before the error will be returned. If @cancellable is
+ * cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error.
+ *
+ * Returns: number of messages sent, or -1 on error. Note that the number of
+ *     messages sent may be smaller than @num_messages if @timeout is zero
+ *     or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in
+ *     which case the caller may re-try to send the remaining messages.
+ * Since: 2.48
+ */
+
+
+/**
  * g_dbus_action_group_get:
  * @connection: A #GDBusConnection
  * @bus_name: the bus name which exports the action group
@@ -33949,6 +34232,23 @@
 
 
 /**
+ * g_socket_connectable_to_string:
+ * @connectable: a #GSocketConnectable
+ *
+ * Format a #GSocketConnectable as a string. This is a human-readable format for
+ * use in debugging output, and is not a stable serialization format. It is not
+ * suitable for use in user interfaces as it exposes too much information for a
+ * user.
+ *
+ * If the #GSocketConnectable implementation does not support string formatting,
+ * the implementation’s type name will be returned as a fallback.
+ *
+ * Returns: (transfer full): the formatted string
+ * Since: 2.48
+ */
+
+
+/**
  * g_socket_connection_connect:
  * @connection: a #GSocketConnection
  * @address: a #GSocketAddress specifying the remote address.
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 07e8813..be8b181 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -19558,7 +19558,7 @@
  * @timeout_: (out): location to store timeout to be used in polling
  * @fds: (out caller-allocates) (array length=n_fds): location to
  *       store #GPollFD records that need to be polled.
- * @n_fds: length of @fds.
+ * @n_fds: (in): length of @fds.
  *
  * Determines information necessary to poll this main loop.
  *
@@ -25081,6 +25081,21 @@
 
 
 /**
+ * g_sequence_is_empty:
+ * @seq: a #GSequence
+ *
+ * Returns %TRUE if the sequence contains zero items.
+ *
+ * This function is functionally identical to checking the result of
+ * g_sequence_get_length() being equal to zero. However this function is
+ * implemented in O(1) running time.
+ *
+ * Returns: %TRUE if the sequence is empty, otherwise %FALSE.
+ * Since: 2.48
+ */
+
+
+/**
  * g_sequence_iter_compare:
  * @a: a #GSequenceIter
  * @b: a #GSequenceIter