diff options
Diffstat (limited to 'gir/glib-2.0.c')
| -rw-r--r-- | gir/glib-2.0.c | 80 |
1 files changed, 54 insertions, 26 deletions
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 |