diff options
| -rw-r--r-- | gir/gio-2.0.c | 86 | ||||
| -rw-r--r-- | gir/glib-2.0.c | 150 | ||||
| -rw-r--r-- | gir/gobject-2.0.c | 524 |
3 files changed, 413 insertions, 347 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 4d98f216..3e4e0886 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -316,8 +316,8 @@ * * In the event that the application is marked * %G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will - * send the @option dictionary to the primary instance where it can be - * read with g_application_command_line_get_options(). The signal + * send the @options dictionary to the primary instance where it can be + * read with g_application_command_line_get_options_dict(). The signal * handler can modify the dictionary before returning, and the * modified dictionary will be sent. * @@ -2176,6 +2176,31 @@ /** + * GNetworkMonitor:network-metered: + * + * Whether the network is considered metered. That is, whether the + * system has traffic flowing through the default connection that is + * subject to limitations set by service providers. For example, traffic + * might be billed by the amount of data transmitted, or there might be a + * quota on the amount of traffic per month. This is typical with tethered + * connections (3G and 4G) and in such situations, bandwidth intensive + * applications may wish to avoid network activity where possible if it will + * cost the user money or use up their limited quota. + * + * If more information is required about specific devices then the + * system network management API should be used instead (for example, + * NetworkManager or ConnMan). + * + * If this information is not available then no networks will be + * marked as metered. + * + * See also #GNetworkMonitor:network-available. + * + * Since: 2.46 + */ + + +/** * GNetworkMonitorInterface: * @g_iface: The parent interface. * @network_changed: the virtual function pointer for the @@ -10876,6 +10901,16 @@ /** + * _g_poll_file_monitor_new: + * @file: a #GFile. + * + * Polls @file for changes. + * + * Returns: a new #GFileMonitor for the given #GFile. + */ + + +/** * g_action_activate: * @action: a #GAction * @parameter: (allow-none): the parameter to the activation @@ -16188,6 +16223,25 @@ /** + * g_dbus_connection_register_object_with_closures: (rename-to g_dbus_connection_register_object) + * @connection: A #GDBusConnection. + * @object_path: The object path to register at. + * @interface_info: Introspection data for the interface. + * @method_call_closure: (nullable): #GClosure for handling incoming method calls. + * @get_property_closure: (nullable): #GClosure for getting a property. + * @set_property_closure: (nullable): #GClosure for setting a property. + * @error: Return location for error or %NULL. + * + * Version of g_dbus_connection_register_object() using closures instead of a + * #GDBusInterfaceVTable for easier binding in other languages. + * + * Returns: 0 if @error is set, otherwise a registration id (never 0) + * that can be used with g_dbus_connection_unregister_object() . + * Since: 2.46 + */ + + +/** * g_dbus_connection_register_subtree: * @connection: a #GDBusConnection * @object_path: the object path to register the subtree at @@ -16435,7 +16489,8 @@ * all object paths * @arg0: (allow-none): contents of first string argument to match on or %NULL * to match on all kinds of arguments - * @flags: flags describing how to subscribe to the signal (currently unused) + * @flags: #GDBusSignalFlags describing how arg0 is used in subscribing to the + * signal * @callback: callback to invoke when there is a signal matching the requested data * @user_data: user data to pass to @callback * @user_data_free_func: (allow-none): function to free @user_data with when @@ -28459,6 +28514,18 @@ /** + * g_network_monitor_get_network_metered: + * @monitor: the #GNetworkMonitor + * + * Checks if the network is metered. + * See #GNetworkMonitor:network-metered for more details. + * + * Returns: whether the connection is metered + * Since: 2.46 + */ + + +/** * g_network_service_get_domain: * @srv: a #GNetworkService * @@ -29457,16 +29524,6 @@ /** - * g_poll_file_monitor_new: - * @file: a #GFile. - * - * Polls @file for changes. - * - * Returns: a new #GFileMonitor for the given #GFile. - */ - - -/** * g_pollable_input_stream_can_poll: * @stream: a #GPollableInputStream. * @@ -30441,6 +30498,9 @@ * The return result is a %NULL terminated list of strings which should * be released with g_strfreev(). * + * If @path is invalid or does not exist in the #GResource, + * %G_RESOURCE_ERROR_NOT_FOUND will be returned. + * * @lookup_flags controls the behaviour of the lookup. * * Returns: (array zero-terminated=1) (transfer full): an array of constant strings diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index c5d86754..c5a947ee 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -6956,6 +6956,35 @@ * On UNIX, the GLib mainloop is incompatible with fork(). Any program * using the mainloop must either exec() or exit() from the child * without returning to the mainloop. + * + * ## Memory management of sources # {#mainloop-memory-management} + * + * There are two options for memory management of the user data passed to a + * #GSource to be passed to its callback on invocation. This data is provided + * in calls to g_timeout_add(), g_timeout_add_full(), g_idle_add(), etc. and + * more generally, using g_source_set_callback(). This data is typically an + * object which ‘owns’ the timeout or idle callback, such as a widget or a + * network protocol implementation. In many cases, it is an error for the + * callback to be invoked after this owning object has been destroyed, as that + * results in use of freed memory. + * + * The first, and preferred, option is to store the source ID returned by + * functions such as g_timeout_add() or g_source_attach(), and explicitly + * remove that source from the main context using g_source_remove() when the + * owning object is finalised. This ensures that the callback can only be + * invoked while the object is still alive. + * + * The second option is to hold a strong reference to the object in the + * callback, and to release it in the callback’s #GDestroyNotify. This ensures + * that the object is kept alive until after the source is finalized, which is + * guaranteed to be after it is invoked for the final time. The #GDestroyNotify + * is another callback passed to the ‘full’ variants of #GSource functions (for + * example, g_timeout_add_full()). It is called when the source is finalized, + * and is designed for releasing references like this. + * + * One important caveat of this second approach is that it will keep the object + * alive indefinitely if the main loop is stopped before the #GSource is + * invoked, which may be undesirable. */ @@ -7023,7 +7052,7 @@ * g_slice_free(), plain malloc() with free(), and (if you're using C++) * new with delete and new[] with delete[]. Otherwise bad things can happen, * since these allocators may use different memory pools (and new/delete call - * constructors and destructors). See also g_mem_set_vtable(). + * constructors and destructors). */ @@ -7585,6 +7614,13 @@ * certain number of columns, then \%Ns is not a correct solution * anyway, since it fails to take wide characters (see g_unichar_iswide()) * into account. + * + * Note also that there are various printf() parameters which are platform + * dependent. GLib provides platform independent macros for these parameters + * which should be used instead. A common example is %G_GUINT64_FORMAT, which + * should be used instead of `%llu` or similar parameters for formatting + * 64-bit integers. These macros are all named `G_*_FORMAT`; see + * [Basic Types][glib-Basic-Types]. */ @@ -7837,6 +7873,20 @@ * and #GAsyncQueue, which are thread-safe and need no further * application-level locking to be accessed from multiple threads. * Most refcounting functions such as g_object_ref() are also thread-safe. + * + * A common use for #GThreads is to move a long-running blocking operation out + * of the main thread and into a worker thread. For GLib functions, such as + * single GIO operations, this is not necessary, and complicates the code. + * Instead, the `…_async()` version of the function should be used from the main + * thread, eliminating the need for locking and synchronisation between multiple + * threads. If an operation does need to be moved to a worker thread, consider + * using g_task_run_in_thread(), or a #GThreadPool. #GThreadPool is often a + * better choice than #GThread, as it handles thread reuse and task queueing; + * #GTask uses this internally. + * + * However, if multiple blocking operations need to be performed in sequence, + * and it is not possible to use #GTask for them, moving them to a worker thread + * can clarify the code. */ @@ -9373,7 +9423,7 @@ * @queue: a #GAsyncQueue * @data: the @data to remove from the @queue * - * Remove an item from the queue. This function does not block. + * Remove an item from the queue. * * Returns: %TRUE if the item was removed * Since: 2.46 @@ -9385,7 +9435,7 @@ * @queue: a #GAsyncQueue * @data: the @data to remove from the @queue * - * Remove an item from the queue. This function does not block. + * Remove an item from the queue. * * This function must be called while holding the @queue's lock. * @@ -14450,6 +14500,10 @@ * * A convenience function/macro to log an error message. * + * This is not intended for end user error reporting. Use of #GError is + * preferred for that instead, as it allows calling functions to perform actions + * conditional on the type of error. + * * Error messages are always fatal, resulting in a call to * abort() to terminate the application. This function will * result in a core dump; don't use it for errors you expect. @@ -16018,7 +16072,7 @@ * If you supplied a @key_destroy_func when creating the * #GHashTable, the old key is freed using that function. * - * Returns: %TRUE of the key did not exist yet + * Returns: %TRUE if the key did not exist yet */ @@ -16646,6 +16700,9 @@ * returns %FALSE it is automatically removed from the list of event * sources and will not be called again. * + * See [memory management of sources][mainloop-memory-management] for details + * on how to handle the return value and memory management of @data. + * * This internally creates a main loop source using g_idle_source_new() * and attaches it to the global #GMainContext using g_source_attach(), so * the callback will be invoked in whichever thread is running that main @@ -16668,6 +16725,9 @@ * events pending. If the function returns %FALSE it is automatically * removed from the list of event sources and will not be called again. * + * See [memory management of sources][mainloop-memory-management] for details + * on how to handle the return value and memory management of @data. + * * This internally creates a main loop source using g_idle_source_new() * and attaches it to the global #GMainContext using g_source_attach(), so * the callback will be invoked in whichever thread is running that main @@ -20688,25 +20748,20 @@ * This function is useful for avoiding an extra copy of allocated memory returned * by a non-GLib-based API. * - * A different allocator can be set using g_mem_set_vtable(). - * * Returns: if %TRUE, malloc() and g_malloc() can be mixed. + * Deprecated: 2.46: GLib always uses the system malloc, so this function always + * returns %TRUE. */ /** * g_mem_profile: * - * Outputs a summary of memory usage. + * GLib used to support some tools for memory profiling, but this + * no longer works. There are many other useful tools for memory + * profiling these days which can be used instead. * - * It outputs the frequency of allocations of different sizes, - * the total number of bytes which have been allocated, - * the total number of bytes which have been freed, - * and the difference between the previous two values, i.e. the number of bytes - * still in use. - * - * Note that this function will not output anything unless you have - * previously installed the #glib_mem_profiler_table with g_mem_set_vtable(). + * Deprecated: 2.46: Use other memory profiling tools instead */ @@ -20714,17 +20769,12 @@ * g_mem_set_vtable: * @vtable: table of memory allocation routines. * - * Sets the #GMemVTable to use for memory allocation. You can use this - * to provide custom memory allocation routines. - * - * The @vtable only needs to provide malloc(), realloc(), and free() - * functions; GLib can provide default implementations of the others. - * The malloc() and realloc() implementations should return %NULL on - * failure, GLib will handle error-checking for you. @vtable is copied, - * so need not persist after this function has been called. + * This function used to let you override the memory allocation function. + * However, its use was incompatible with the use of global constructors + * in GLib and GIO, because those use the GLib allocators before main is + * reached. Therefore this function is now deprecated and is just a stub. * - * Note that this function must be called before using any other GLib - * functions. + * Deprecated: 2.46: Use other memory profiling tools instead */ @@ -26709,6 +26759,9 @@ * should not count on @func being called with @data as its first * parameter. * + * See [memory management of sources][mainloop-memory-management] for details + * on how to handle memory management of @data. + * * Typically, you won't use this function. Instead use functions specific * to the type of source you are using. */ @@ -26952,13 +27005,8 @@ * main(). wmain() has a wide character argument vector as parameter. * * At least currently, mingw doesn't support wmain(), so if you use - * mingw to develop the spawned program, it will have to call the - * undocumented function __wgetmainargs() to get the wide character - * argument vector and environment. See gspawn-win32-helper.c in the - * GLib sources or init.c in the mingw runtime sources for a prototype - * for that function. Alternatively, you can retrieve the Win32 system - * level wide character command line passed to the spawned program - * using the GetCommandLineW() function. + * mingw to develop the spawned program, it should call + * g_win32_get_command_line() to get arguments in UTF-8. * * On Windows the low-level child process creation API CreateProcess() * doesn't use argument vectors, but a command line. The C runtime @@ -27356,6 +27404,10 @@ * It can be passed to g_hash_table_new() as the @hash_func parameter, * when using non-%NULL strings as keys in a #GHashTable. * + * Note that this function may not be a perfect fit for all use cases. + * For example, it produces some hash collisions with strings as short + * as 2. + * * Returns: a hash value corresponding to the key */ @@ -29795,6 +29847,10 @@ * If the thread can not be created the program aborts. See * g_thread_try_new() if you want to attempt to deal with failures. * + * If you are using threads to offload (potentially many) short-lived tasks, + * #GThreadPool may be more appropriate than manually spawning and tracking + * multiple #GThreads. + * * To free the struct returned by this function, use g_thread_unref(). * Note that g_thread_join() implicitly unrefs the #GThread as well. * @@ -30463,6 +30519,9 @@ * timeout is recalculated based on the current time and the given interval * (it does not try to 'catch up' time lost in delays). * + * See [memory management of sources][mainloop-memory-management] for details + * on how to handle the return value and memory management of @data. + * * If you want to have a timer in the "seconds" range and do not care * about the exact time of the first call of the timer, use the * g_timeout_add_seconds() function; this function allows for more @@ -30504,6 +30563,9 @@ * timeout is recalculated based on the current time and the given interval * (it does not try to 'catch up' time lost in delays). * + * See [memory management of sources][mainloop-memory-management] for details + * on how to handle the return value and memory management of @data. + * * This internally creates a main loop source using g_timeout_source_new() * and attaches it to the global #GMainContext using g_source_attach(), so * the callback will be invoked in whichever thread is running that main @@ -30537,6 +30599,9 @@ * of one second. If you need finer precision and have such a timeout, * you may want to use g_timeout_add() instead. * + * See [memory management of sources][mainloop-memory-management] for details + * on how to handle the return value and memory management of @data. + * * The interval given is in terms of monotonic time, not wall clock * time. See g_get_monotonic_time(). * @@ -30572,6 +30637,9 @@ * After each call to the timeout function, the time of the next * timeout is recalculated based on the current time and the given @interval * + * See [memory management of sources][mainloop-memory-management] for details + * on how to handle the return value and memory management of @data. + * * If you want timing more precise than whole seconds, use g_timeout_add() * instead. * @@ -33641,7 +33709,7 @@ * type. This includes the types %G_VARIANT_TYPE_STRING, * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE. * - * The string will always be UTF-8 encoded. + * The string will always be UTF-8 encoded, and will never be %NULL. * * If @length is non-%NULL then the length of the string (in bytes) is * returned there. For trusted values, this information is already @@ -34679,7 +34747,9 @@ * * Creates a string #GVariant with the contents of @string. * - * @string must be valid UTF-8. + * @string must be valid UTF-8, and must not be %NULL. To encode + * potentially-%NULL strings, use g_variant_new() with `ms` as the + * [format string][gvariant-format-strings-maybe-types]. * * Returns: (transfer none): a floating reference to a new string #GVariant instance * Since: 2.24 @@ -34707,7 +34777,8 @@ * * Creates a string #GVariant with the contents of @string. * - * @string must be valid UTF-8. + * @string must be valid UTF-8, and must not be %NULL. To encode + * potentially-%NULL strings, use this with g_variant_new_maybe(). * * This function consumes @string. g_free() will be called on @string * when it is no longer required. @@ -35750,6 +35821,10 @@ * * A convenience function/macro to log a warning message. * + * This is not intended for end user error reporting. Use of #GError is + * preferred for that instead, as it allows calling functions to perform actions + * conditional on the type of error. + * * You can make warnings fatal at runtime by setting the `G_DEBUG` * environment variable (see * [Running GLib Applications](glib-running.html)). @@ -36227,10 +36302,7 @@ /** * glib_mem_profiler_table: * - * A #GMemVTable containing profiling variants of the memory - * allocation functions. Use them together with g_mem_profile() - * in order to get information about the memory allocation pattern - * of your program. + * Deprecated: 2.46: Use other memory profiling tools instead */ diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index afbc2d2f..c778d2ff 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -441,10 +441,10 @@ * separately (typically by using #GArray or #GPtrArray) and put a pointer * to the buffer in the structure. * - * A final word about type names: Such an identifier needs to be at least - * three characters long. There is no upper length limit. The first character - * needs to be a letter (a-z or A-Z) or an underscore '_'. Subsequent - * characters can be letters, numbers or any of '-_+'. + * As mentioned in the [GType conventions][gtype-conventions], type names must + * be at least three characters long. There is no upper length limit. The first + * character must be a letter (a–z or A–Z) or an underscore (‘_’). Subsequent + * characters can be letters, numbers or any of ‘-_+’. */ @@ -551,6 +551,12 @@ * construction and destruction, property access methods, and signal * support. Signals are described in detail [here][gobject-Signals]. * + * For a tutorial on implementing a new GObject class, see [How to define and + * implement a new GObject][howto-gobject]. For a list of naming conventions for + * GObjects and their methods, see the [GType conventions][gtype-conventions]. + * For the high-level concepts behind GObject, read [Instantiable classed types: + * Objects][gtype-instantiable-classed]. + * * ## Floating references # {#floating-ref} * * GInitiallyUnowned is derived from GObject. The only difference between @@ -686,6 +692,32 @@ * Specification of no detail argument for signal handlers (omission of the * detail part of the signal specification upon connection) serves as a * wildcard and matches any detail argument passed in to emission. + * + * ## Memory management of signal handlers # {#signal-memory-management} + * + * If you are connecting handlers to signals and using a #GObject instance as + * your signal handler user data, you should remember to pair calls to + * g_signal_connect() with calls to g_signal_handler_disconnect() or + * g_signal_handlers_disconnect_by_func(). While signal handlers are + * automatically disconnected when the object emitting the signal is finalised, + * they are not automatically disconnected when the signal handler user data is + * destroyed. If this user data is a #GObject instance, using it from a + * signal handler after it has been finalised is an error. + * + * There are two strategies for managing such user data. The first is to + * disconnect the signal handler (using g_signal_handler_disconnect() or + * g_signal_handlers_disconnect_by_func()) when the user data (object) is + * finalised; this has to be implemented manually. For non-threaded programs, + * g_signal_connect_object() can be used to implement this automatically. + * Currently, however, it is unsafe to use in threaded programs. + * + * The second is to hold a strong reference on the user data until after the + * signal is disconnected for other reasons. This can be implemented + * automatically using g_signal_connect_data(). + * + * The first approach is recommended, as the second approach can result in + * effective memory leaks of the user data if the signal handler is never + * disconnected for some reason. */ @@ -869,22 +901,17 @@ /** * g_cclosure_marshal_BOOLEAN__FLAGS: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: a #GValue which can store the returned #gboolean + * @n_param_values: 2 + * @param_values: a #GValue array holding instance and arg1 + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with handlers that - * take a flags type as an argument and return a boolean. If you have - * such a signal, you will probably also need to use an accumulator, - * such as g_signal_accumulator_true_handled(). + * A marshaller for a #GCClosure with a callback of type + * `gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter + * denotes a flags type. */ @@ -944,39 +971,23 @@ /** * g_cclosure_marshal_BOOL__FLAGS: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() * - * An old alias for g_cclosure_marshal_BOOLEAN__FLAGS(). + * Another name for g_cclosure_marshal_BOOLEAN__FLAGS(). */ /** * g_cclosure_marshal_STRING__OBJECT_POINTER: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: a #GValue, which can store the returned string + * @n_param_values: 3 + * @param_values: a #GValue array holding instance, arg1 and arg2 + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with handlers that - * take a #GObject and a pointer and produce a string. It is highly - * unlikely that your signal handler fits this description. + * A marshaller for a #GCClosure with a callback of type + * `gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. */ @@ -1001,20 +1012,16 @@ /** * g_cclosure_marshal_VOID__BOOLEAN: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gboolean parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with a single - * boolean argument. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. */ @@ -1039,20 +1046,16 @@ /** * g_cclosure_marshal_VOID__BOXED: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #GBoxed* parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with a single - * argument which is any boxed pointer type. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. */ @@ -1077,20 +1080,16 @@ /** * g_cclosure_marshal_VOID__CHAR: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gchar parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with a single - * character argument. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. */ @@ -1115,20 +1114,16 @@ /** * g_cclosure_marshal_VOID__DOUBLE: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gdouble parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with one - * double-precision floating point argument. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. */ @@ -1153,20 +1148,16 @@ /** * g_cclosure_marshal_VOID__ENUM: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the enumeration parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with a single - * argument with an enumerated type. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. */ @@ -1191,20 +1182,16 @@ /** * g_cclosure_marshal_VOID__FLAGS: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the flags parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with a single - * argument with a flags types. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. */ @@ -1229,20 +1216,16 @@ /** * g_cclosure_marshal_VOID__FLOAT: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gfloat parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with one - * single-precision floating point argument. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. */ @@ -1267,20 +1250,16 @@ /** * g_cclosure_marshal_VOID__INT: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gint parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with a single - * integer argument. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. */ @@ -1305,20 +1284,16 @@ /** * g_cclosure_marshal_VOID__LONG: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #glong parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with with a single - * long integer argument. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. */ @@ -1343,20 +1318,16 @@ /** * g_cclosure_marshal_VOID__OBJECT: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #GObject* parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with a single - * #GObject argument. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. */ @@ -1381,20 +1352,16 @@ /** * g_cclosure_marshal_VOID__PARAM: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #GParamSpec* parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with a single - * argument of type #GParamSpec. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. */ @@ -1419,24 +1386,16 @@ /** * g_cclosure_marshal_VOID__POINTER: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * - * A #GClosureMarshal function for use with signals with a single raw - * pointer argument type. + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gpointer parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * If it is possible, it is better to use one of the more specific - * functions such as g_cclosure_marshal_VOID__OBJECT() or - * g_cclosure_marshal_VOID__OBJECT(). + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. */ @@ -1461,20 +1420,16 @@ /** * g_cclosure_marshal_VOID__STRING: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gchar* parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with a single string - * argument. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. */ @@ -1499,20 +1454,16 @@ /** * g_cclosure_marshal_VOID__UCHAR: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #guchar parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with a single - * unsigned character argument. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. */ @@ -1537,39 +1488,31 @@ /** * g_cclosure_marshal_VOID__UINT: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #guint parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with with a single - * unsigned integer argument. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. */ /** * g_cclosure_marshal_VOID__UINT_POINTER: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 3 + * @param_values: a #GValue array holding instance, arg1 and arg2 + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with a unsigned int - * and a pointer as arguments. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. */ @@ -1613,20 +1556,16 @@ /** * g_cclosure_marshal_VOID__ULONG: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gulong parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with a single - * unsigned long integer argument. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. */ @@ -1651,20 +1590,18 @@ /** * g_cclosure_marshal_VOID__VARIANT: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #GVariant* parameter + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with a single - * #GVariant argument. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. + * + * Since: 2.26 */ @@ -1689,19 +1626,16 @@ /** * g_cclosure_marshal_VOID__VOID: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 1 + * @param_values: a #GValue array holding only the instance + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GClosureMarshal function for use with signals with no arguments. + * A marshaller for a #GCClosure with a callback of type + * `void (*callback) (gpointer instance, gpointer user_data)`. */ |