commit 7ca5f4bf0365b853cdb0bab5cc9cb0ce6deaec26 Author: Nick Mathewson nickm@torproject.org Date: Fri Dec 8 10:29:01 2017 -0500

document our allocator conventions --- doc/HACKING/CodingStandards.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+)

diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md index dd21d6fd2..4b1bf4718 100644 --- a/doc/HACKING/CodingStandards.md +++ b/doc/HACKING/CodingStandards.md @@ -346,6 +346,46 @@ macro, as in: if (BUG(ptr == NULL)) return -1;

+Allocator conventions +--------------------- + +By convention, any tor type with a name like `abc_t` should be allocated +by a function named `abc_new()`. This function should never return +NULL. + +Also, a type named `abc_t` should be freed by a function named `abc_free_()`. +Don't call this `abc_free_()` function directly -- instead, wrap it in a +macro called `abc_free()`, using the `FREE_AND_NULL` macro: + + void abc_free_(abc_t *obj); + #define abc_free(obj) FREE_AND_NULL(abc_t, abc_free_, (abc)) + +This macro will free the underlying `abc_t` object, and will also set +the object pointer to NULL. + +You should define all `abc_free_()` functions to accept NULL inputs: + + void + abc_free_(abc_t *obj) + { + if (!obj) + return; + tor_free(obj->name); + thing_free(obj->thing); + tor_free(obj); + } + +If you need a free function that takes a `void *` argument (for example, +to use it as a function callback), define it with a name like +`abc_free_void()`: + + static void + abc_free_void_(void *obj) + { + abc_free_(obj); + } + + Doxygen comment conventions ---------------------------