Skip to content

doc/newformat: stop using glib slice allocator #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 20, 2023
Merged

doc/newformat: stop using glib slice allocator #39

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2ceadfd
docs/newformat: link to old g_auto* docs
bgilbert Apr 16, 2023
1770cb6
doc/newformat: stop using glib slice allocator
bgilbert Apr 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 25 additions & 22 deletions docs/newformat/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,22 +218,20 @@ 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()` 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
Expand All @@ -242,11 +240,10 @@ 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.

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
Expand All @@ -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;
Expand All @@ -270,12 +267,18 @@ 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
[g_steal_pointer]: https://docs.gtk.org/glib/func.steal_pointer.html


Expand Down