From 2ceadfd4eb583b27de925de66606f498ce9c89de Mon Sep 17 00:00:00 2001 From: Benjamin Gilbert Date: Sun, 16 Apr 2023 00:36:56 -0400 Subject: [PATCH 1/2] docs/newformat: link to old g_auto* docs The new glib docs don't document the g_auto* macros (https://gitlab.gnome.org/GNOME/glib/-/issues/2718) so link to the old docs site instead. Signed-off-by: Benjamin Gilbert --- docs/newformat/index.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/docs/newformat/index.md b/docs/newformat/index.md index 8f4e1c3..ff0d3a4 100644 --- a/docs/newformat/index.md +++ b/docs/newformat/index.md @@ -226,14 +226,14 @@ with the slice allocator.) Use the regular memory allocator for all other allocations. When allocating and freeing an object within the same function, use -`g_autoptr()` or `g_autofree` to automatically free the object when it goes -out of scope. This makes early returns simpler, since those paths don't -need to explicitly deallocate or `goto` a common cleanup label. -`g_autoptr()` is suitable for structs with their own free functions, and -`g_autofree` is for arbitrary memory that can be freed with `g_free()`. -Variables declared with `g_auto*` must always be initialized on the spot -(perhaps to `NULL`) to avoid freeing a garbage pointer; CI has a check for -this. +[`g_autoptr`][g_autoptr]`()` or [`g_autofree`][g_autofree] to automatically +free the object when it goes out of scope. This makes early returns +simpler, since those paths don't need to explicitly deallocate or `goto` a +common cleanup label. `g_autoptr()` is suitable for structs with their own +free functions, and `g_autofree` is for arbitrary memory that can be freed +with `g_free()`. Variables declared with `g_auto*` must always be +initialized on the spot (perhaps to `NULL`) to avoid freeing a garbage +pointer; CI has a check for this. When allocating an object that will be returned from the function, or will be linked into data structures that outlive the function, prefer using @@ -242,11 +242,11 @@ object cannot leak, but simplifies cleanup if the function has subsequent early returns. Use [`g_steal_pointer`][g_steal_pointer]`(&object)` to remove `object` from the control of `g_auto*`. -There is also `g_auto()` for stack-allocated structs and allocated arrays of -allocated strings. The latter is spelled `g_auto(GStrv)`, and the former is -used by a few OpenSlide APIs to support automatic cleanup. (Notably, the -TIFF handle cache, and an OpenSlide-provided wrapper around the slice -allocator.) +There is also [`g_auto`][g_auto]`()` for stack-allocated structs and +allocated arrays of allocated strings. The latter is spelled +`g_auto(GStrv)`, and the former is used by a few OpenSlide APIs to support +automatic cleanup. (Notably, the TIFF handle cache, and an +OpenSlide-provided wrapper around the slice allocator.) Define a `g_autoptr()` cleanup function for any struct that would benefit from automatic cleanup. To do so, glib requires a typedef for the struct @@ -276,6 +276,9 @@ bool do_something(GError **err) { ``` [slice allocator]: https://docs.gtk.org/glib/memory-slices.html +[g_autoptr]: https://developer-old.gnome.org/glib/unstable/glib-Miscellaneous-Macros.html#g-autoptr +[g_autofree]: https://developer-old.gnome.org/glib/unstable/glib-Miscellaneous-Macros.html#g-autofree +[g_auto]: https://developer-old.gnome.org/glib/unstable/glib-Miscellaneous-Macros.html#g-auto [g_steal_pointer]: https://docs.gtk.org/glib/func.steal_pointer.html From 1770cb643935bfdacdbf2b21509a94a4e17516e3 Mon Sep 17 00:00:00 2001 From: Benjamin Gilbert Date: Wed, 19 Apr 2023 00:31:39 -0400 Subject: [PATCH 2/2] doc/newformat: stop using glib slice allocator Link to allocator docs on the old glib docs site, since they're more comprehensive than the new ones. For https://github.com/openslide/openslide/pull/435. Signed-off-by: Benjamin Gilbert --- docs/newformat/index.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/newformat/index.md b/docs/newformat/index.md index ff0d3a4..0e0b491 100644 --- a/docs/newformat/index.md +++ b/docs/newformat/index.md @@ -218,12 +218,10 @@ highest-resolution level. ## Memory allocation -OpenSlide uses the glib memory allocators, except where an external API -requires the use of a different allocator. Use the [slice allocator] for -fixed-length allocations that are likely to occur repeatedly, such as -structs and uncompressed pixel data. (Cache entries _must_ be allocated -with the slice allocator.) Use the regular memory allocator for all other -allocations. +OpenSlide uses the [glib memory allocator], except where an external API +requires the use of a different allocator. OpenSlide previously also used +the glib [slice allocator], but [no longer does]. Allocate structs with +[`g_new0`][g_new0]`(struct some_struct, 1)`. When allocating and freeing an object within the same function, use [`g_autoptr`][g_autoptr]`()` or [`g_autofree`][g_autofree] to automatically @@ -245,8 +243,7 @@ remove `object` from the control of `g_auto*`. There is also [`g_auto`][g_auto]`()` for stack-allocated structs and allocated arrays of allocated strings. The latter is spelled `g_auto(GStrv)`, and the former is used by a few OpenSlide APIs to support -automatic cleanup. (Notably, the TIFF handle cache, and an -OpenSlide-provided wrapper around the slice allocator.) +automatic cleanup, notably the TIFF handle cache. Define a `g_autoptr()` cleanup function for any struct that would benefit from automatic cleanup. To do so, glib requires a typedef for the struct @@ -260,7 +257,7 @@ struct foo { static void foo_free(struct foo *f) { ... - g_slice_free(struct foo, f); + g_free(f); } typedef struct foo foo; @@ -270,12 +267,15 @@ G_DEFINE_AUTOPTR_CLEANUP_FUNC(foo, foo_free) bool do_something(GError **err) { ... - g_autoptr(foo) my_foo = ...; + g_autoptr(foo) my_foo = g_new0(struct foo, 1); ... } ``` -[slice allocator]: https://docs.gtk.org/glib/memory-slices.html +[glib memory allocator]: https://developer-old.gnome.org/glib/unstable/glib-Memory-Allocation.html +[slice allocator]: https://developer-old.gnome.org/glib/unstable/glib-Memory-Slices.html +[no longer does]: https://github.com/openslide/openslide/issues/430 +[g_new0]: https://developer-old.gnome.org/glib/unstable/glib-Memory-Allocation.html#g-new0 [g_autoptr]: https://developer-old.gnome.org/glib/unstable/glib-Miscellaneous-Macros.html#g-autoptr [g_autofree]: https://developer-old.gnome.org/glib/unstable/glib-Miscellaneous-Macros.html#g-autofree [g_auto]: https://developer-old.gnome.org/glib/unstable/glib-Miscellaneous-Macros.html#g-auto