[tor-commits] [tor/master] document our allocator conventions

[nickm@xxxxxxxxxxxxxx]

commit 7ca5f4bf0365b853cdb0bab5cc9cb0ce6deaec26
Author: Nick Mathewson <nickm@xxxxxxxxxxxxxx>
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
 ---------------------------
 



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits