From 74fcf8851fd84613399bbcc53150e2e441e80fb2 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Mon, 12 Oct 2015 15:21:35 -0400 Subject: 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 0488eeef..7dcb1739 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 @@ -34988,6 +34996,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 @@ -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 0d5431bc..07e8813b 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 025266e6..b78b988c 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. */ -- cgit v1.2.1