luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-13 07:56:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'clear-pointer-doc' into 'main'

Browse Source 
gmem.c: Update g_clear_pointer() documentation

See merge request GNOME/glib!4093
This commit is contained in:
Philip Withnall 2024-05-24 10:16:51 +00:00
commit c02f50f0ba
1 changed files with 27 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
glib/gmem.c
View File

@ -244,7 +244,7 @@ g_free_sized (void *mem,
* g_clear_pointer: (skip) * g_clear_pointer: (skip)
* @pp: (nullable) (not optional) (inout) (transfer full): a pointer to a * @pp: (nullable) (not optional) (inout) (transfer full): a pointer to a
* variable, struct member etc. holding a pointer * variable, struct member etc. holding a pointer
* @destroy: a function to which a gpointer can be passed, to destroy *@pp * @destroy: a function to which a gpointer can be passed, to destroy `*pp`
* *
* Clears a reference to a variable. * Clears a reference to a variable.
* *
@ -257,9 +257,32 @@ g_free_sized (void *mem,
* A macro is also included that allows this function to be used without * A macro is also included that allows this function to be used without
* pointer casts. This will mask any warnings about incompatible function types * pointer casts. This will mask any warnings about incompatible function types
* or calling conventions, so you must ensure that your @destroy function is * or calling conventions, so you must ensure that your @destroy function is
* compatible with being called as `GDestroyNotify` using the standard calling * compatible with being called as [callback@GLib.DestroyNotify] using the
* convention for the platform that GLib was compiled for; otherwise the program * standard calling convention for the platform that GLib was compiled for;
* will experience undefined behaviour. * otherwise the program will experience undefined behaviour.
*
* Examples of this kind of undefined behaviour include using many Windows Win32
* APIs, as well as many if not all OpenGL and Vulkan calls on 32-bit Windows,
* which typically use the `__stdcall` calling convention rather than the
* `__cdecl` calling convention.
*
* The affected functions can be used by wrapping them in a
* [callback@GLib.DestroyNotify] that is declared with the standard calling
* convention:
*
* ```c
* // Wrapper needed to avoid mismatched calling conventions on Windows
* static void
* destroy_sync (void *sync)
* {
* glDeleteSync (sync);
* }
*
* // …
*
* g_clear_pointer (&sync, destroy_sync);
* ```
* *
* Since: 2.34 * Since: 2.34
**/ **/