Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/gballoc_requirements.md

raw
1 # gballoc requirements
2 ================
3
4 ## Overview
5
6 gballoc is a module that is a pass through for the malloc, realloc and free memory management functions described in C99, section 7.20.3.
7 The pass through has the purpose of tracking memory allocations in order to compute the maximal memory usage of an application using the memory management functions.
8
9 ## References
10
11 [ISO/IEC 9899:TC3]
12
13 ## Exposed API
14
15 ```c
16 extern int gballoc_init(void);
17 extern void gballoc_deinit(void);
18 extern void* gballoc_malloc(size_t size);
19 extern void* gballoc_calloc(size_t nmemb, size_t size);
20 extern void* gballoc_realloc(void* ptr, size_t size);
21 extern void gballoc_free(void* ptr);
22
23
24 extern int gballoc_resetCounters(void);
25 extern size_t gballoc_getMaximumMemoryUsed(void);
26 extern size_t gballoc_getCurrentMemoryUsed(void);
27 extern size_t gballoc_getAllocationCount(void));
28 extern void gballoc_resetMetrics(void);
29 ```
30
31 ### gballoc_init
32
33 ```c
34 extern int gballoc_init(void);
35 ```
36
37 **SRS_GBALLOC_01_024: [** gballoc_init shall initialize the gballoc module and return 0 upon success. **]**
38
39 **SRS_GBALLOC_01_025: [** Init after Init shall fail and return a non-zero value. **]**
40
41 **SRS_GBALLOC_01_026: [** gballoc_Init shall create a lock handle that will be used to make the other gballoc APIs thread-safe. **]**
42
43 **SRS_GBALLOC_01_027: [** If the Lock creation fails, gballoc_init shall return a non-zero value. **]**
44
45 **SRS_GBALLOC_01_002: [** Upon initialization the total memory used and maximum total memory used tracked by the module shall be set to 0. **]**
46
47 ### gballoc_deinit
48
49 ```c
50 extern void gballoc_deinit(void);
51 ```
52
53 **SRS_GBALLOC_01_028: [** gballoc_deinit shall free all resources allocated by gballoc_init. **]**
54
55 **SRS_GBALLOC_01_029: [** if gballoc is not initialized gballoc_deinit shall do nothing. **]**
56
57 ### gballoc_malloc
58
59 ```c
60 extern void* gballoc_malloc(size_t size);
61 ```
62
63 **SRS_GBALLOC_01_003: [** gballoc_malloc shall call the C99 malloc function and return its result. **]**
64
65 **SRS_GBALLOC_01_004: [** If the underlying malloc call is successful, gballoc_malloc shall increment the total memory used with the amount indicated by size. **]**
66
67 **SRS_GBALLOC_01_012: [** When the underlying malloc call fails, gballoc_malloc shall return NULL and size should not be counted towards total memory used. **]**
68
69 **SRS_GBALLOC_01_013: [** When gballoc_malloc fails allocating memory for its internal use, gballoc_malloc shall return NULL. **]**
70
71 **SRS_GBALLOC_01_030: [** gballoc_malloc shall ensure thread safety by using the lock created by gballoc_Init. **]**
72
73 **SRS_GBALLOC_01_039: [** If gballoc was not initialized gballoc_malloc shall simply call malloc without any memory tracking being performed. **]**
74
75 **SRS_GBALLOC_01_048: [** If acquiring the lock fails, gballoc_malloc shall return NULL. **]**
76
77 ### gballoc_calloc
78
79 ```c
80 extern void* gballoc_calloc(size_t nmemb, size_t size);
81 ```
82
83 **SRS_GBALLOC_01_020: [** gballoc_calloc shall call the C99 calloc function and return its result. **]**
84
85 **SRS_GBALLOC_01_021: [** If the underlying calloc call is successful, gballoc_calloc shall increment the total memory used with nmemb*size. **]**
86
87 **SRS_GBALLOC_01_022: [** When the underlying calloc call fails, gballoc_calloc shall return NULL and size should not be counted towards total memory used. **]**
88
89 **SRS_GBALLOC_01_023: [** When gballoc_calloc fails allocating memory for its internal use, gballoc_calloc shall return NULL. **]**
90
91 **SRS_GBALLOC_01_031: [** gballoc_calloc shall ensure thread safety by using the lock created by gballoc_Init **]**
92
93 **SRS_GBALLOC_01_040: [** If gballoc was not initialized gballoc_calloc shall simply call calloc without any memory tracking being performed. **]**
94
95 **SRS_GBALLOC_01_046: [** If acquiring the lock fails, gballoc_calloc shall return NULL. **]**
96
97 ### gballoc_realloc
98
99 ```c
100 extern void* gballoc_realloc(void* ptr, size_t size);
101 ```
102
103 **SRS_GBALLOC_01_005: [** gballoc_realloc shall call the C99 realloc function and return its result. **]**
104
105 **SRS_GBALLOC_01_006: [** If the underlying realloc call is successful, gballoc_realloc shall look up the size associated with the pointer ptr and decrease the total memory used with that size. **]**
106
107 **SRS_GBALLOC_01_007: [** If realloc is successful, gballoc_realloc shall also increment the total memory used value tracked by this module. **]**
108
109 **SRS_GBALLOC_01_014: [** When the underlying realloc call fails, gballoc_realloc shall return NULL and no change should be made to the counted total memory usage. **]**
110
111 **SRS_GBALLOC_01_015: [** When allocating memory used for tracking by gballoc_realloc fails, gballoc_realloc shall return NULL and no change should be made to the counted total memory usage. **]**
112
113 **SRS_GBALLOC_01_016: [** When the ptr pointer cannot be found in the pointers tracked by gballoc, gballoc_realloc shall return NULL and the underlying realloc shall not be called. **]**
114
115 **SRS_GBALLOC_01_017: [** When ptr is NULL, gballoc_realloc shall call the underlying realloc with ptr being NULL and the realloc result shall be tracked by gballoc. **]**
116
117 **SRS_GBALLOC_01_032: [** gballoc_realloc shall ensure thread safety by using the lock created by gballoc_Init. **]**
118
119 **SRS_GBALLOC_01_041: [** If gballoc was not initialized gballoc_realloc shall shall simply call realloc without any memory tracking being performed. **]**
120
121 **SRS_GBALLOC_01_047: [** If acquiring the lock fails, gballoc_realloc shall return NULL. **]**
122
123 ### gballoc_free
124
125 ```c
126 extern void gballoc_free(void* ptr);
127 ```
128
129 **SRS_GBALLOC_01_008: [** gballoc_free shall call the C99 free function. **]**
130
131 **SRS_GBALLOC_01_009: [** gballoc_free shall also look up the size associated with the ptr pointer and decrease the total memory used with the associated size amount. **]**
132
133 **SRS_GBALLOC_01_019: [** When the ptr pointer cannot be found in the pointers tracked by gballoc, gballoc_free shall not free any memory. **]**
134
135 **SRS_GBALLOC_01_033: [** gballoc_free shall ensure thread safety by using the lock created by gballoc_Init. **]**
136
137 **SRS_GBALLOC_01_042: [** If gballoc was not initialized gballoc_free shall shall simply call free. **]**
138
139 **SRS_GBALLOC_01_049: [** If acquiring the lock fails, gballoc_free shall do nothing. **]**
140
141 ### gballoc_getMaximumMemoryUsed
142
143 ```c
144 extern size_t gballoc_getMaximumMemoryUsed(void);
145 ```
146
147 **SRS_GBALLOC_01_010: [** gballoc_getMaximumMemoryUsed shall return the maximum amount of total memory used recorded since the module initialization. **]**
148
149 **SRS_GBALLOC_01_011: [** The maximum total memory used shall be the maximum of the total memory used at any point. **]**
150
151 **SRS_GBALLOC_01_034: [** gballoc_getMaximumMemoryUsed shall ensure thread safety by using the lock created by gballoc_Init. **]**
152
153 **SRS_GBALLOC_01_038: [** If gballoc was not initialized gballoc_getMaximumMemoryUsed shall return MAX_INT_SIZE. **]**
154
155 **SRS_GBALLOC_01_050: [** If the lock cannot be acquired, gballoc_getMaximumMemoryUsed shall return SIZE_MAX. **]**
156
157 ### gballoc_getCurrentMemoryUsed
158
159 ```c
160 extern size_t gballoc_getCurrentMemoryUsed(void);
161 ```
162
163 **SRS_GBALLOC_02_001: [** gballoc_getCurrentMemoryUsed shall return the currently used memory size. **]**
164
165 **SRS_GBALLOC_01_036: [** gballoc_getCurrentMemoryUsed shall ensure thread safety by using the lock created by gballoc_Init. **]**
166
167 **SRS_GBALLOC_01_044: [** If gballoc was not initialized gballoc_getCurrentMemoryUsed shall return SIZE_MAX. **]**
168
169 **SRS_GBALLOC_01_051: [** If the lock cannot be acquired, gballoc_getCurrentMemoryUsed shall return SIZE_MAX. **]**
170
171 ### gballoc_getAllocationCount
172
173 ```c
174 extern size_t gballoc_getAllocationCount(void));
175 ```
176
177 **SRS_GBALLOC_07_001: [** If `gballoc` was not initialized `gballoc_getAllocationCount` shall return `0`. **]**
178
179 **SRS_GBALLOC_07_002: [** `gballoc_getAllocationCount` shall ensure thread safety by using the lock created by `gballoc_Init` **]**
180
181 **SRS_GBALLOC_07_003: [** If the lock cannot be acquired, `gballoc_getAllocationCount` shall return `0`. **]**
182
183 **SRS_GBALLOC_07_004: [** `gballoc_getAllocationCount` shall return the currently number of allocations. **]**
184
185 ### gballoc_resetMetrics
186
187 ```c
188 extern void gballoc_resetMetrics(void);
189 ```
190
191 **SRS_GBALLOC_07_005: [** If `gballoc` was not initialized `gballoc_reset Metrics` shall do nothing.**]**
192
193 **SRS_GBALLOC_07_006: [** `gballoc_resetMetrics` shall ensure thread safety by using the lock created by `gballoc_Init` **]**
194
195 **SRS_GBALLOC_07_007: [** If the lock cannot be acquired, `gballoc_reset Metrics` shall do nothing.**]**
196
197 **SRS_GBALLOC_07_008: [** `gballoc_resetMetrics` shall reset the total allocation size, max allocation size and number of allocation to zero. **]**