GNOME.org
 

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

commit 74fcf8851fd84613399bbcc53150e2e441e80fb2
Author: Colin Walters <walters verbum org>
Date:   Mon Oct 12 15:21:35 2015 -0400

    gir: Update annotations from GLib git master

 gir/gio-2.0.c     |  124 ++++++++++++++++++++++++++++++++++++++++++++---------
 gir/glib-2.0.c    |   80 +++++++++++++++++++++++-----------
 gir/gobject-2.0.c |   10 ++--
 3 files changed, 162 insertions(+), 52 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 0488eee..7dcb173 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -6180,12 +6180,12 @@
  * @see_also: #GInputStream, #GOutputStream
  *
  * GIOStream represents an object that has both read and write streams.
- * Generally the two streams acts as separate input and output streams,
+ * Generally the two streams act as separate input and output streams,
  * but they share some common resources and state. For instance, for
- * seekable streams they may use the same position in both streams.
+ * seekable streams, both streams may use the same position.
  *
- * Examples of #GIOStream objects are #GSocketConnection which represents
- * a two-way network connection, and #GFileIOStream which represent a
+ * Examples of #GIOStream objects are #GSocketConnection, which represents
+ * a two-way network connection; and #GFileIOStream, which represents a
  * file handle opened in read-write mode.
  *
  * To do the actual reading and writing you need to get the substreams
@@ -6194,8 +6194,8 @@
  * The #GIOStream object owns the input and the output streams, not the other
  * way around, so keeping the substreams alive will not keep the #GIOStream
  * object alive. If the #GIOStream object is freed it will be closed, thus
- * closing the substream, so even if the substreams stay alive they will
- * always just return a %G_IO_ERROR_CLOSED for all operations.
+ * closing the substreams, so even if the substreams stay alive they will
+ * always return %G_IO_ERROR_CLOSED for all operations.
  *
  * To close a stream use g_io_stream_close() which will close the common
  * stream object and also the individual substreams. You can also close
@@ -7678,7 +7678,8 @@
  * %NULL.
  *
  * Sockets operate in two general modes, blocking or non-blocking. When
- * in blocking mode all operations block until the requested operation
+ * in blocking mode all operations (which don’t take an explicit blocking
+ * parameter) block until the requested operation
  * 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.
  * To know when a call would successfully run you can call g_socket_condition_check(),
@@ -15960,8 +15961,8 @@
  * each application is a client. So this method will always return
  * %NULL for message bus clients.
  *
- * Returns: (transfer none): a #GCredentials or %NULL if not available.
- *     Do not free this object, it is owned by @connection.
+ * Returns: (transfer none) (nullable): a #GCredentials or %NULL if not
+ *     available. Do not free this object, it is owned by @connection.
  * Since: 2.26
  */
 
@@ -25999,7 +26000,7 @@
  * @error: location to store the error occurring, or %NULL to ignore
  *
  * Closes the stream, releasing resources related to it. This will also
- * closes the individual input and output streams, if they are not already
+ * close the individual input and output streams, if they are not already
  * closed.
  *
  * Once the stream is closed, all other operations will return
@@ -34203,7 +34204,7 @@
  * g_socket_get_available_bytes:
  * @socket: a #GSocket
  *
- * Get the amount of data pending in the OS input buffer.
+ * Get the amount of data pending in the OS input buffer, without blocking.
  *
  * If @socket is a UDP or SCTP socket, this will return the size of
  * just the next packet, even if additional packets are buffered after
@@ -34469,6 +34470,11 @@
  * Check whether the socket is connected. This is only useful for
  * connection-oriented sockets.
  *
+ * If using g_socket_shutdown(), this function will return %TRUE until the
+ * socket has been shut down for reading and writing. If you do a non-blocking
+ * connect, this function will not return %TRUE until after you call
+ * g_socket_check_connect_result().
+ *
  * Returns: %TRUE if socket is connected, %FALSE otherwise.
  * Since: 2.22
  */
@@ -34924,8 +34930,8 @@
  * @cancellable: (allow-none): a %GCancellable or %NULL
  * @error: a #GError pointer, or %NULL
  *
- * Receive data from a socket.  This is the most complicated and
- * fully-featured version of this call. For easier use, see
+ * Receive data from a socket.  For receiving multiple messages, see
+ * g_socket_receive_messages(); for easier use, see
  * g_socket_receive() and g_socket_receive_from().
  *
  * If @address is non-%NULL then @address will be set equal to the
@@ -34964,6 +34970,8 @@
  * 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
  * (and g_socket_receive_message() may pass system-specific flags out).
+ * Flags passed in to the parameter affect the receive operation; flags returned
+ * out of it are relevant to the specific returned message.
  *
  * As with g_socket_receive(), data may be discarded if @socket is
  * %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not
@@ -34989,6 +34997,73 @@
 
 
 /**
+ * g_socket_receive_messages:
+ * @socket: a #GSocket
+ * @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
+ * @cancellable: (allow-none): a %GCancellable or %NULL
+ * @error: #GError for error reporting, or %NULL to ignore
+ *
+ * Receive multiple data messages from @socket in one go.  This is the most
+ * complicated and fully-featured version of this call. For easier use, see
+ * g_socket_receive(), g_socket_receive_from(), and g_socket_receive_message().
+ *
+ * @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. Using
+ * multiple #GInputVectors is more memory-efficient than manually copying data
+ * out of a single buffer to multiple sources, and more system-call-efficient
+ * than making multiple calls to g_socket_receive(), such as in scenarios where
+ * a lot of data packets need to be received (e.g. high-bandwidth video
+ * streaming over RTP/UDP).
+ *
+ * @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 #GSocket:blocking is %TRUE the call will block until @num_messages have
+ * been received, or the end of the stream is reached.
+ *
+ * If #GSocket:blocking is %FALSE 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.
+ *
+ * In blocking mode, if #GSocket:timeout is positive and is reached before any
+ * messages are received, %G_IO_ERROR_TIMED_OUT is returned, otherwise up to
+ * @num_messages are returned. (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_socket_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
+ * operating system will be returned, and subsequent calls to
+ * g_socket_receive_messages() will return 0 (with no error set).
+ *
+ * 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.
+ *
+ * Returns: number of messages received, or -1 on error. Note that the number
+ *     of messages received may be smaller than @num_messages if in non-blocking
+ *     mode, 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_socket_receive_with_blocking:
  * @socket: a #GSocket
  * @buffer: (array length=size) (element-type guint8): a buffer to
@@ -35051,8 +35126,8 @@
  * @cancellable: (allow-none): a %GCancellable or %NULL
  * @error: #GError for error reporting, or %NULL to ignore.
  *
- * Send data to @address on @socket.  This is the most complicated and
- * fully-featured version of this call. For easier use, see
+ * Send data to @address on @socket.  For sending multiple messages see
+ * g_socket_send_messages(); for easier use, see
  * g_socket_send() and g_socket_send_to().
  *
  * If @address is %NULL then the message is sent to the default receiver
@@ -35135,7 +35210,9 @@
  * notified of a %G_IO_OUT condition. (On Windows in particular, this is
  * very common due to the way the underlying APIs work.)
  *
- * On error -1 is returned and @error is set accordingly.
+ * 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.
  *
  * Returns: number of messages sent, or -1 on error. Note that the number of
  *     messages sent may be smaller than @num_messages if the socket is
@@ -35253,7 +35330,8 @@
  * @blocking: Whether to use blocking I/O or not.
  *
  * Sets the blocking mode of the socket. In blocking mode
- * all operations block until they succeed or there is an error. In
+ * all operations (which don’t take an explicit blocking parameter) block until
+ * they succeed or there is an error. In
  * non-blocking mode all functions return results immediately or
  * with a %G_IO_ERROR_WOULD_BLOCK error.
  *
@@ -35421,7 +35499,7 @@
  * @shutdown_write: whether to shut down the write side
  * @error: #GError for error reporting, or %NULL to ignore.
  *
- * Shut down part of a full-duplex connection.
+ * Shut down part or all of a full-duplex connection.
  *
  * If @shutdown_read is %TRUE then the receiving side of the connection
  * is shut down, and further reading is disallowed.
@@ -35431,9 +35509,10 @@
  *
  * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE.
  *
- * One example where this is used is graceful disconnect for TCP connections
- * where you close the sending side, then wait for the other side to close
- * the connection, thus ensuring that the other side saw all sent data.
+ * One example where it is useful to shut down only one side of a connection is
+ * graceful disconnect for TCP connections where you close the sending side,
+ * then wait for the other side to close the connection, thus ensuring that the
+ * other side saw all sent data.
  *
  * Returns: %TRUE on success, %FALSE on error
  * Since: 2.22
@@ -39569,6 +39648,9 @@
  * If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to
  * calling g_unix_socket_address_new().
  *
+ * If @type is %G_UNIX_SOCKET_ADDRESS_ANONYMOUS, @path and @path_len will be
+ * ignored.
+ *
  * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len
  * bytes of @path will be copied to the socket's path, and only those
  * bytes will be considered part of the name. (If @path_len is -1,
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 0d5431b..07e8813 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -5623,10 +5623,12 @@
  * GLib provides a standard method of reporting errors from a called
  * function to the calling code. (This is the same problem solved by
  * exceptions in other languages.) It's important to understand that
- * this method is both a data type (the #GError struct) and a set of
- * rules. If you use #GError incorrectly, then your code will not
+ * this method is both a data type (the #GError struct) and a [set of
+ * rules][gerror-rules]. If you use #GError incorrectly, then your code will not
  * properly interoperate with other code that uses #GError, and users
- * of your API will probably get confused.
+ * of your API will probably get confused. In most cases, [using #GError is
+ * preferred over numeric error codes][gerror-comparison], but there are
+ * situations where numeric error codes are useful for performance.
  *
  * First and foremost: #GError should only be used to report recoverable
  * runtime errors, never to report programming errors. If the programmer
@@ -5872,6 +5874,29 @@
  *   instead treat any unrecognized error code as equivalent to
  *   FAILED.
  *
+ * ## Comparison of #GError and traditional error handling # {#gerror-comparison}
+ *
+ * #GError has several advantages over traditional numeric error codes:
+ * importantly, tools like
+ * [gobject-introspection](https://developer.gnome.org/gi/stable/) understand
+ * #GErrors and convert them to exceptions in bindings; the message includes
+ * more information than just a code; and use of a domain helps prevent
+ * misinterpretation of error codes.
+ *
+ * #GError has disadvantages though: it requires a memory allocation, and
+ * formatting the error message string has a performance overhead. This makes it
+ * unsuitable for use in retry loops where errors are a common case, rather than
+ * being unusual. For example, using %G_IO_ERROR_WOULD_BLOCK means hitting these
+ * overheads in the normal control flow. String formatting overhead can be
+ * eliminated by using g_set_error_literal() in some cases.
+ *
+ * These performance issues can be compounded if a function wraps the #GErrors
+ * returned by the functions it calls: this multiplies the number of allocations
+ * and string formatting operations. This can be partially mitigated by using
+ * g_prefix_error().
+ *
+ * ## Rules for use of #GError # {#gerror-rules}
+ *
  * Summary of rules for use of #GError:
  *
  * - Do not report programming errors via #GError.
@@ -8827,8 +8852,8 @@
 /**
  * g_ascii_strtod:
  * @nptr: the string to convert to a numeric value.
- * @endptr: if non-%NULL, it returns the character after
- *           the last character used in the conversion.
+ * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the
+ *           character after the last character used in the conversion.
  *
  * Converts a string to a #gdouble value.
  *
@@ -8861,8 +8886,8 @@
 /**
  * g_ascii_strtoll:
  * @nptr: the string to convert to a numeric value.
- * @endptr: if non-%NULL, it returns the character after
- *           the last character used in the conversion.
+ * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the
+ *           character after the last character used in the conversion.
  * @base: to be used for the conversion, 2..36 or 0
  *
  * Converts a string to a #gint64 value.
@@ -8891,8 +8916,8 @@
 /**
  * g_ascii_strtoull:
  * @nptr: the string to convert to a numeric value.
- * @endptr: if non-%NULL, it returns the character after
- *           the last character used in the conversion.
+ * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the
+ *           character after the last character used in the conversion.
  * @base: to be used for the conversion, 2..36 or 0
  *
  * Converts a string to a #guint64 value.
@@ -10041,7 +10066,7 @@
  * }
  * ]|
  *
- * You must initialise the variable in some way -- either by use of an
+ * You must initialize the variable in some way -- either by use of an
  * initialiser or by ensuring that an _init function will be called on
  * it unconditionally before it goes out of scope.
  *
@@ -11403,7 +11428,7 @@
 /**
  * g_bytes_get_data:
  * @bytes: a #GBytes
- * @size: (out) (allow-none): location to return size of byte data
+ * @size: (out) (optional): location to return size of byte data
  *
  * Get the byte data in the #GBytes. This data should not be modified.
  *
@@ -11413,8 +11438,8 @@
  * may represent an empty string with @data non-%NULL and @size as 0. %NULL will
  * not be returned if @size is non-zero.
  *
- * Returns: (transfer none) (array length=size) (type guint8) (allow-none): a pointer to the
- *          byte data, or %NULL
+ * Returns: (transfer none) (array length=size) (element-type guint8) (nullable):
+ *          a pointer to the byte data, or %NULL
  * Since: 2.32
  */
 
@@ -11448,7 +11473,7 @@
 
 /**
  * g_bytes_new:
- * @data: (transfer none) (array length=size) (element-type guint8) (allow-none):
+ * @data: (transfer none) (array length=size) (element-type guint8) (nullable):
  *        the data to be used for the bytes
  * @size: the size of @data
  *
@@ -11480,7 +11505,7 @@
 
 /**
  * g_bytes_new_static: (skip)
- * @data: (transfer full) (array length=size) (element-type guint8) (allow-none):
+ * @data: (transfer full) (array length=size) (element-type guint8) (nullable):
  *           the data to be used for the bytes
  * @size: the size of @data
  *
@@ -11496,7 +11521,7 @@
 
 /**
  * g_bytes_new_take:
- * @data: (transfer full) (array length=size) (element-type guint8) (allow-none):
+ * @data: (transfer full) (array length=size) (element-type guint8) (nullable):
  *           the data to be used for the bytes
  * @size: the size of @data
  *
@@ -11519,8 +11544,9 @@
 
 
 /**
- * g_bytes_new_with_free_func:
- * @data: (array length=size) (allow-none): the data to be used for the bytes
+ * g_bytes_new_with_free_func: (skip)
+ * @data: (array length=size) (element-type guint8) (nullable):
+ *           the data to be used for the bytes
  * @size: the size of @data
  * @free_func: the function to call to release the data
  * @user_data: data to pass to @free_func
@@ -11553,7 +11579,7 @@
 
 /**
  * g_bytes_unref:
- * @bytes: (allow-none): a #GBytes
+ * @bytes: (nullable): a #GBytes
  *
  * Releases a reference on @bytes.  This may result in the bytes being
  * freed.
@@ -11582,7 +11608,7 @@
 /**
  * g_bytes_unref_to_data:
  * @bytes: (transfer full): a #GBytes
- * @size: location to place the length of the returned data
+ * @size: (out): location to place the length of the returned data
  *
  * Unreferences the bytes, and returns a pointer the same byte data
  * contents.
@@ -11592,8 +11618,8 @@
  * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the
  * data is copied.
  *
- * Returns: (transfer full): a pointer to the same byte data, which should
- *          be freed with g_free()
+ * Returns: (transfer full) (array length=size) (element-type guint8):
+ *          a pointer to the same byte data, which should be freed with g_free()
  * Since: 2.32
  */
 
@@ -22502,12 +22528,14 @@
 
 /**
  * g_propagate_error:
- * @dest: error return location
- * @src: error to move into the return location
+ * @dest: (out callee-allocates) (optional) (nullable): error return location
+ * @src: (transfer full): error to move into the return location
  *
  * If @dest is %NULL, free @src; otherwise, moves @src into * dest 
  * The error variable @dest points to must be %NULL.
  *
+ * @src must be non-%NULL.
+ *
  * Note that @src is no longer valid after this call. If you want
  * to keep using the same GError*, you need to set it to %NULL
  * after calling this function on it.
@@ -28721,8 +28749,8 @@
 /**
  * g_strtod:
  * @nptr: the string to convert to a numeric value.
- * @endptr: if non-%NULL, it returns the character after
- *           the last character used in the conversion.
+ * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the
+ *           character after the last character used in the conversion.
  *
  * Converts a string to a #gdouble value.
  * It calls the standard strtod() function to handle the conversion, but
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 025266e..b78b988 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -3939,7 +3939,7 @@
  * @name: canonical name of the property specified
  * @nick: nick name for the property specified
  * @blurb: description of the property specified
- * @default_value: default value for the property specified
+ * @default_value: (nullable): default value for the property specified
  * @flags: flags for the property specified
  *
  * Creates a new #GParamSpecString instance.
@@ -6853,10 +6853,10 @@
  * g_value_unset:
  * @value: An initialized #GValue structure.
  *
- * Clears the current value in @value and "unsets" the type,
- * this releases all resources associated with this GValue.
- * An unset value is the same as an uninitialized (zero-filled)
- * #GValue structure.
+ * Clears the current value in @value (if any) and "unsets" the type,
+ * this releases all resources associated with this GValue. An unset
+ * value is the same as an uninitialized (zero-filled) #GValue
+ * structure.
  */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]