From f30295fb5cd419396dbfa55338aa2f5920a892e3 Mon Sep 17 00:00:00 2001 From: Allen Webster Date: Sun, 10 Oct 2021 19:16:36 -0700 Subject: [PATCH] [examples] notes on the scratch pool --- examples/integration/memory_management.c | 38 ++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/examples/integration/memory_management.c b/examples/integration/memory_management.c index ac60832..aa15390 100644 --- a/examples/integration/memory_management.c +++ b/examples/integration/memory_management.c @@ -174,3 +174,41 @@ main(int argc, char **argv) release_config_file(files[2]); } } + +// @notes A final note on "scratch arenas". +// +// Often it is useful to use an arena for a temporary allocation that will be +// thrown away by the end of the current scope. One could create a new arena +// with MD_ArenaAlloc and later release it with MD_ArenaRelease, but this +// sort of case is perfect for using the thread-local scratch pool. +// +// To get an arena for scratch work from the pool one uses: +// MD_ArenaTemp scratch = MD_GetScratch(0, 0); +// To allocate with it: +// MD_WhateverArenaApi(scratch.arena, ...); +// And to release it: +// MD_ReleaseScratch(scratch); +// +// If an arena is being used for allocating something to return to the caller +// it is important that it not also be the scratch, or else when the scratch +// release happens, all of the memory that was supposed to stay allocated +// for the caller to see will also be released (or worse, marked as released +// but still valid looking for some time). +// +// To avoid this when getting a scratch arena the API MD_GetScratch allows you +// to specify arenas you are already using, to force it to pick one you are +// not using. In 99.99% of cases a call to this API either looks like: +// MD_GetScratch(0, 0); +// Or +// MD_GetScratch(&arena, 1); +// +// If there are more than one arena already in use when a new scratch is +// needed they can all be specified by packing them into an array: +// MD_Arena *arena_conflicts[2] = {arena1, arena2}; +// MD_GetScratch(arena_conflicts, 2); +// +// Watch out! If the scratch pool doesn't have a non-conflicting arena then +// it will return a null handle, likely leading to a crash. This can be +// avoided by defining a higher value for #define MD_IMPL_ScratchCount. +// But it's generally possible and a lot better to avoid this path. +