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