Browse code

mem: initial doxygen documentation for MM, small whitespace changes

Henning Westerholt authored on 13/07/2011 22:11:48
Showing 11 changed files
... ...
@@ -1,6 +1,4 @@
1
-/* $Id$
2
- *
3
- *
1
+/*
4 2
  * Copyright (C) 2001-2003 FhG Fokus
5 3
  *
6 4
  * This file is part of sip-router, a free SIP server.
... ...
@@ -17,6 +15,7 @@
17 15
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
18 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
19 17
  */
18
+
20 19
 /*
21 20
  * History:
22 21
  * --------
... ...
@@ -42,6 +41,12 @@
42 41
  *               (only the first bucket was tried) (andrei)
43 42
  */
44 43
 
44
+/**
45
+ * \file
46
+ * \brief Simple, very fast, malloc library
47
+ * \ingroup mem
48
+ */
49
+
45 50
 
46 51
 #if !defined(q_malloc)  && (defined F_MALLOC)
47 52
 
... ...
@@ -1,7 +1,4 @@
1
-/* $Id$
2
- *
3
- * simple, very fast, malloc library
4
- *
1
+/*
5 2
  * Copyright (C) 2001-2003 FhG Fokus
6 3
  *
7 4
  * This file is part of sip-router, a free SIP server.
... ...
@@ -18,6 +15,7 @@
18 15
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20 17
  */
18
+
21 19
 /*
22 20
  * History:
23 21
  * --------
... ...
@@ -29,6 +27,12 @@
29 27
  *  2007-06-23  added hash bitmap (andrei)
30 28
  */
31 29
 
30
+/**
31
+ * \file
32
+ * \brief Simple, very fast, malloc library
33
+ * \ingroup mem
34
+ */
35
+
32 36
 
33 37
 #if !defined(f_malloc_h)
34 38
 #define f_malloc_h
... ...
@@ -104,6 +108,10 @@ struct fm_frag_lnk{
104 108
 	unsigned long no;
105 109
 };
106 110
 
111
+/**
112
+ * \brief Block of memory for F_MALLOC memory manager
113
+ * \see mem_info
114
+ */
107 115
 struct fm_block{
108 116
 	unsigned long size; /* total size */
109 117
 #if defined(DBG_F_MALLOC) || defined(MALLOC_STATS)
... ...
@@ -1,6 +1,4 @@
1 1
 /*
2
- * $Id$
3
- *
4 2
  * Copyright (C) 2001-2003 FhG Fokus
5 3
  *
6 4
  * This file is part of sip-router, a free SIP server.
... ...
@@ -24,6 +22,14 @@
24 22
  * 
25 23
  */
26 24
 
25
+/**
26
+ * \file
27
+ * \brief Main definitions for memory manager
28
+ * 
29
+ * Main definitions for memory manager, like malloc, free and realloc
30
+ * \ingroup mem
31
+ */
32
+
27 33
 
28 34
 #include <stdio.h>
29 35
 #include <stdlib.h>
... ...
@@ -55,6 +61,10 @@
55 61
 #endif
56 62
 
57 63
 
64
+/**
65
+ * \brief Initialize private memory pool
66
+ * \return 0 if the memory allocation was successful, -1 otherwise
67
+ */
58 68
 int init_pkg_mallocs()
59 69
 {
60 70
 #ifdef PKG_MALLOC
... ...
@@ -87,6 +97,9 @@ int init_pkg_mallocs()
87 97
 
88 98
 
89 99
 
100
+/**
101
+ * \brief Destroy private memory pool
102
+ */
90 103
 void destroy_pkg_mallocs()
91 104
 {
92 105
 #ifdef PKG_MALLOC
... ...
@@ -100,7 +113,11 @@ void destroy_pkg_mallocs()
100 113
 }
101 114
 
102 115
 
103
-
116
+/**
117
+ * \brief Initialize shared memory pool
118
+ * \param force_alloc Force allocation of memory, e.g. initialize complete block with zero
119
+ * \return 0 if the memory allocation was successful, -1 otherwise
120
+ */
104 121
 int init_shm_mallocs(int force_alloc)
105 122
 {
106 123
 #ifdef SHM_MEM
... ...
@@ -113,5 +130,3 @@ int init_shm_mallocs(int force_alloc)
113 130
 #endif
114 131
 	return 0;
115 132
 }
116
-
117
-
... ...
@@ -1,8 +1,4 @@
1
-/* $Id$
2
- *
3
- * memory related stuff (malloc & friends)
4
- * 
5
- *
1
+/*
6 2
  * Copyright (C) 2001-2003 FhG Fokus
7 3
  *
8 4
  * This file is part of sip-router, a free SIP server.
... ...
@@ -19,6 +15,7 @@
19 15
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
20 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21 17
  */
18
+
22 19
 /*
23 20
  * History:
24 21
  * --------
... ...
@@ -29,6 +26,23 @@
29 26
  *  2007-02-23   added pkg_info() and pkg_available() (andrei)
30 27
  */
31 28
 
29
+/**
30
+ * \defgroup mem SIP-router memory manager
31
+ * \brief  SIP-router internal memory manager
32
+ * 
33
+ * SIP-router internal memory manager for private (per process) and shared
34
+ * memory pools. It provides several different strategies for the memory
35
+ * management, like really fast, with extended debugging and also plain system
36
+ * memory management.
37
+ */
38
+
39
+/**
40
+ * \file
41
+ * \brief Main definitions for memory manager
42
+ * 
43
+ * \brief Main definitions for memory manager, like malloc, free and realloc
44
+ * \ingroup mem
45
+ */
32 46
 
33 47
 
34 48
 #ifndef mem_h
... ...
@@ -132,17 +146,31 @@
132 146
 #	define pkg_sums()
133 147
 #endif
134 148
 
149
+/**
150
+ * \brief Initialize private memory pool
151
+ * \return 0 if the memory allocation was successful, -1 otherwise
152
+ */
135 153
 int init_pkg_mallocs();
154
+
155
+/**
156
+ * \brief Destroy private memory pool
157
+ */
136 158
 void destroy_pkg_mallocs();
159
+
160
+/**
161
+ * \brief Initialize shared memory pool
162
+ * \param force_alloc Force allocation of memory, e.g. initialize complete block with zero
163
+ * \return 0 if the memory allocation was successful, -1 otherwise
164
+ */
137 165
 int init_shm_mallocs(int force_alloc);
138 166
 
139
-/*! generic logging helper for allocation errors in private memory pool/ system */
167
+/** generic logging helper for allocation errors in private memory pool/ system */
140 168
 #ifdef SYSTEM_MALLOC
141 169
 #define PKG_MEM_ERROR LM_ERR("could not allocate private memory from system")
142 170
 #else
143 171
 #define PKG_MEM_ERROR LM_ERR("could not allocate private memory from available pool")
144 172
 #endif
145
-/*! generic logging helper for allocation errors in shared memory pool */
173
+/** generic logging helper for allocation errors in shared memory pool */
146 174
 #define SHM_MEM_ERROR LM_ERR("could not allocate shared memory from available pool")
147 175
 
148 176
 #endif
... ...
@@ -1,6 +1,4 @@
1 1
 /*
2
- * $Id$
3
- *
4 2
  * Copyright (C) 2006 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -15,12 +13,19 @@
15 13
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 14
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 15
  */
18
-/* malloc debug messages
16
+
17
+/*
19 18
  * History:
20 19
  * --------
21 20
  *  2006-04-07             created by andrei
22 21
  */
23 22
 
23
+/**
24
+ * \file
25
+ * \brief Malloc debug messages
26
+ * \ingroup mem
27
+ */
28
+
24 29
 
25 30
 #ifndef _memdbg_h
26 31
 #define _memdbg_h
... ...
@@ -1,7 +1,4 @@
1
-/* $Id$*
2
- *
3
- * mem (malloc) info 
4
- *
1
+/*
5 2
  * Copyright (C) 2001-2003 FhG Fokus
6 3
  *
7 4
  * This file is part of sip-router, a free SIP server.
... ...
@@ -18,6 +15,7 @@
18 15
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20 17
  */
18
+
21 19
 /*
22 20
  * History:
23 21
  * --------
... ...
@@ -25,17 +23,28 @@
25 23
  *  2005-07-25  renamed meminfo to mem_info due to name conflict on solaris
26 24
  */
27 25
 
26
+/**
27
+ * \file
28
+ * \brief Memory manager (malloc) informations and statistics
29
+ * 
30
+ * Memory manager (malloc) informations and statistics, like the used memory,
31
+ * fragmentations etc..
32
+ * \ingroup mem
33
+ */
34
+
28 35
 #ifndef meminfo_h
29 36
 #define meminfo_h
30 37
 
38
+
39
+/** Memory information structure */
31 40
 struct mem_info{
32
-	unsigned long total_size;
33
-	unsigned long free;
34
-	unsigned long used;
35
-	unsigned long real_used; /*used + overhead*/
36
-	unsigned long max_used;
37
-	unsigned long min_frag;
38
-	unsigned long total_frags; /* total fragment no */
41
+	unsigned long total_size; /** total size of memory pool */
42
+	unsigned long free; /** free memory */
43
+	unsigned long used; /** allocated size */
44
+	unsigned long real_used; /** used size plus overhead from malloc */
45
+	unsigned long max_used; /** maximum used size since server start? */
46
+	unsigned long min_frag; /** minimum number of fragmentations? */
47
+	unsigned long total_frags; /** number of total memory fragments */
39 48
 };
40 49
 
41 50
 #endif
... ...
@@ -1,6 +1,4 @@
1
-/* $Id$
2
- *
3
- *
1
+/*
4 2
  * Copyright (C) 2001-2003 FhG Fokus
5 3
  *
6 4
  * This file is part of sip-router, a free SIP server.
... ...
@@ -17,6 +15,7 @@
17 15
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
18 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
19 17
  */
18
+
20 19
 /*
21 20
  * History:
22 21
  * --------
... ...
@@ -36,6 +35,12 @@
36 35
  *  2009-09-28  added fm_sums() (patch from Dragos Vingarzan)
37 36
  */
38 37
 
38
+/**
39
+ * \file
40
+ * \brief Simple & fast malloc library
41
+ * \ingroup mem
42
+ */
43
+
39 44
 
40 45
 #if !defined(q_malloc) && !(defined F_MALLOC)
41 46
 #define q_malloc
... ...
@@ -1,7 +1,4 @@
1
-/* $Id$
2
- *
3
- * simple & fast malloc library
4
- *
1
+/*
5 2
  * Copyright (C) 2001-2003 FhG Fokus
6 3
  *
7 4
  * This file is part of sip-router, a free SIP server.
... ...
@@ -18,6 +15,7 @@
18 15
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20 17
  */
18
+
21 19
 /*
22 20
  * History:
23 21
  * --------
... ...
@@ -28,6 +26,11 @@
28 26
  *  2004-11-10  support for > 4Gb mem. (switched to long) (andrei)
29 27
  */
30 28
 
29
+/**
30
+ * \file
31
+ * \brief Simple & fast malloc library
32
+ * \ingroup mem
33
+ */
31 34
 
32 35
 #if !defined(q_malloc_h) && !defined(F_MALLOC)
33 36
 #define q_malloc_h
... ...
@@ -103,6 +106,11 @@ struct qm_frag_lnk{
103 106
 };
104 107
 
105 108
 
109
+/**
110
+ * \brief Block of memory for Q_MALLOC memory manager
111
+ * \see mem_info
112
+ */
113
+
106 114
 struct qm_block{
107 115
 	unsigned long size; /* total size */
108 116
 	unsigned long used; /* alloc'ed size*/
... ...
@@ -1,6 +1,5 @@
1
-/* $Id$
2
- *
3
- * Shared memory functions
1
+/*
2
+
4 3
  *
5 4
  * Copyright (C) 2001-2003 FhG Fokus
6 5
  *
... ...
@@ -18,6 +17,7 @@
18 17
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19 18
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20 19
  */
20
+
21 21
 /*
22 22
  * History:
23 23
  * --------
... ...
@@ -28,6 +28,12 @@
28 28
  *  2007-06-10   support for sfm_malloc & shm_malloc_destroy() (andrei)
29 29
  */
30 30
 
31
+/**
32
+ * \file
33
+ * \brief  Shared memory functions
34
+ * \ingroup mem
35
+ */
36
+
31 37
 
32 38
 #ifdef SHM_MEM
33 39
 
... ...
@@ -1,5 +1,4 @@
1
-/* $Id$*
2
- *
1
+/*
3 2
  * shared mem stuff
4 3
  *
5 4
  * Copyright (C) 2001-2003 FhG Fokus
... ...
@@ -18,6 +17,7 @@
18 17
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19 18
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20 19
  */
20
+
21 21
 /*
22 22
  * History:
23 23
  * --------
... ...
@@ -29,6 +29,12 @@
29 29
  *  2007-06-10   support for sf_malloc (andrei)
30 30
  */
31 31
 
32
+/**
33
+ * \file
34
+ * \brief  Shared memory functions
35
+ * \ingroup mem
36
+ */
37
+
32 38
 
33 39
 #ifdef SHM_MEM
34 40
 
... ...
@@ -1,6 +1,4 @@
1 1
 /* 
2
- * $Id$
3
- * 
4 2
  * Copyright (C) 2009 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -15,27 +13,33 @@
15 13
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 14
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 15
  */
18
-/*
19
- * mem/src_loc.h - defines for src location ( function name, module a.s.o.),
20
- *  used for recording a *malloc()/ *free() caller.
21
- *
22
- * Expects MOD_NAME defined for modules (if it's not defined "core" will be
23
- * assumed).
24
- * Defines:
25
- *  _SRC_FUNCTION_  - current function name
26
- *  _SRC_FILENAME_  - current .c filename
27
- *  _SRC_LINE_      - current line
28
- *  _SRC_MODULE_    - module name, lib name or "<core>" (depends on MOD_NAME
29
- *                    being properly set)
30
- *  _SRC_LOC_       - module name + file name
31
- *
32
- */
16
+
33 17
 /*
34 18
  * History:
35 19
  * --------
36 20
  *  2009-10-08  initial version (andrei)
37 21
 */
38 22
 
23
+/**
24
+ * \file
25
+ * \brief Helper definitions for internal memory manager
26
+ * 
27
+ * Helper definitions for internal memory manager, defines for src location
28
+ * (function name, module a.s.o.), used for recording a *malloc()/ *free()
29
+ * caller. Expects MOD_NAME defined for modules (if it's not defined "core"
30
+ * will be assumed).
31
+ * 
32
+ * Defines:
33
+ * - _SRC_FUNCTION_  - current function name
34
+ * - _SRC_FILENAME_  - current .c filename
35
+ * - _SRC_LINE_      - current line
36
+ * - _SRC_MODULE_    - module name, lib name or "<core>" (depends on MOD_NAME
37
+ * being properly set)
38
+ * - _SRC_LOC_       - module name + file name
39
+ * \ingroup mem
40
+ */
41
+
42
+
39 43
 #ifndef __src_loc_h
40 44
 #define __src_loc_h
41 45