1.. highlight:: c 2 3Memtypes 4======== 5 6FRR includes wrappers around ``malloc()`` and ``free()`` that count the number 7of objects currently allocated, for each of a defined ``MTYPE``. 8 9To this extent, there are *memory groups* and *memory types*. Each memory 10type must belong to a memory group, this is used just to provide some basic 11structure. 12 13Example: 14 15.. code-block:: c 16 :caption: mydaemon.h 17 18 DECLARE_MGROUP(MYDAEMON) 19 DECLARE_MTYPE(MYNEIGHBOR) 20 21.. code-block:: c 22 :caption: mydaemon.c 23 24 DEFINE_MGROUP( MYDAEMON, "My daemon's memory") 25 DEFINE_MTYPE( MYDAEMON, MYNEIGHBOR, "Neighbor entry") 26 DEFINE_MTYPE_STATIC(MYDAEMON, MYNEIGHBORNAME, "Neighbor name") 27 28 struct neigh *neighbor_new(const char *name) 29 { 30 struct neigh *n = XMALLOC(MYNEIGHBOR, sizeof(*n)); 31 n->name = XSTRDUP(MYNEIGHBORNAME, name); 32 return n; 33 } 34 35 void neighbor_free(struct neigh *n) 36 { 37 XFREE(MYNEIGHBORNAME, n->name); 38 XFREE(MYNEIGHBOR, n); 39 } 40 41 42Definition 43---------- 44 45.. c:type:: struct memtype 46 47 This is the (internal) type used for MTYPE definitions. The macros below 48 should be used to create these, but in some cases it is useful to pass a 49 ``struct memtype *`` pointer to some helper function. 50 51 The ``MTYPE_name`` created by the macros is declared as a pointer, i.e. 52 a function taking a ``struct memtype *`` argument can be called with an 53 ``MTYPE_name`` argument (as opposed to ``&MTYPE_name``.) 54 55 .. note:: 56 57 As ``MTYPE_name`` is a variable assigned from ``&_mt_name`` and not a 58 constant expression, it cannot be used as initializer for static 59 variables. In the case please fall back to ``&_mt_name``. 60 61.. c:macro:: DECLARE_MGROUP(name) 62 63 This macro forward-declares a memory group and should be placed in a 64 ``.h`` file. It expands to an ``extern struct memgroup`` statement. 65 66.. c:macro:: DEFINE_MGROUP(mname, description) 67 68 Defines/implements a memory group. Must be placed into exactly one ``.c`` 69 file (multiple inclusion will result in a link-time symbol conflict). 70 71 Contains additional logic (constructor and destructor) to register the 72 memory group in a global list. 73 74.. c:macro:: DECLARE_MTYPE(name) 75 76 Forward-declares a memory type and makes ``MTYPE_name`` available for use. 77 Note that the ``MTYPE_`` prefix must not be included in the name, it is 78 automatically prefixed. 79 80 ``MTYPE_name`` is created as a `static const` symbol, i.e. a compile-time 81 constant. It refers to an ``extern struct memtype _mt_name``, where `name` 82 is replaced with the actual name. 83 84.. c:macro:: DEFINE_MTYPE(group, name, description) 85 86 Define/implement a memory type, must be placed into exactly one ``.c`` 87 file (multiple inclusion will result in a link-time symbol conflict). 88 89 Like ``DEFINE_MGROUP``, this contains actual code to register the MTYPE 90 under its group. 91 92.. c:macro:: DEFINE_MTYPE_STATIC(group, name, description) 93 94 Same as ``DEFINE_MTYPE``, but the ``DEFINE_MTYPE_STATIC`` variant places 95 the C ``static`` keyword on the definition, restricting the MTYPE's 96 availability to the current source file. This should be appropriate in 97 >80% of cases. 98 99 .. todo:: 100 101 Daemons currently have ``daemon_memory.[ch]`` files listing all of 102 their MTYPEs. This is not how it should be, most of these types 103 should be moved into the appropriate files where they are used. 104 Only a few MTYPEs should remain non-static after that. 105 106 107Usage 108----- 109 110.. c:function:: void *XMALLOC(struct memtype *mtype, size_t size) 111 112.. c:function:: void *XCALLOC(struct memtype *mtype, size_t size) 113 114.. c:function:: void *XSTRDUP(struct memtype *mtype, const char *name) 115 116 Allocation wrappers for malloc/calloc/realloc/strdup, taking an extra 117 mtype parameter. 118 119.. c:function:: void *XREALLOC(struct memtype *mtype, void *ptr, size_t size) 120 121 Wrapper around realloc() with MTYPE tracking. Note that ``ptr`` may 122 be NULL, in which case the function does the same as XMALLOC (regardless 123 of whether the system realloc() supports this.) 124 125.. c:function:: void XFREE(struct memtype *mtype, void *ptr) 126 127 Wrapper around free(), again taking an extra mtype parameter. This is 128 actually a macro, with the following additional properties: 129 130 - the macro contains ``ptr = NULL`` 131 - if ptr is NULL, no operation is performed (as is guaranteed by system 132 implementations.) Do not surround XFREE with ``if (ptr != NULL)`` 133 checks. 134