1Bareos Memory Management
2========================
3
4General
5-------
6
7This document describes the memory management routines that are used in
8Bareos and is meant to be a technical discussion for developers rather
9than part of the user manual.
10
11Since Bareos may be called upon to handle filenames of varying and more
12or less arbitrary length, special attention needs to be used in the code
13to ensure that memory buffers are sufficiently large. There are four
14possibilities for memory usage within **Bareos**. Each will be described
15in turn. They are:
16
17-  Statically allocated memory.
18
19-  Dynamically allocated memory using malloc() and free().
20
21-  Non-pooled memory.
22
23-  Pooled memory.
24
25Statically Allocated Memory
26~~~~~~~~~~~~~~~~~~~~~~~~~~~
27
28Statically allocated memory is of the form:
29
30::
31
32    char buffer[MAXSTRING];
33
34The use of this kind of memory is discouraged except when you are 100%
35sure that the strings to be used will be of a fixed length. One example
36of where this is appropriate is for **Bareos** resource names, which are
37currently limited to 127 characters (MAX_NAME_LENGTH). Although this
38maximum size may change, particularly to accommodate Unicode, it will
39remain a relatively small value.
40
41Dynamically Allocated Memory
42~~~~~~~~~~~~~~~~~~~~~~~~~~~~
43
44Dynamically allocated memory is obtained using the standard malloc()
45routines. As in:
46
47::
48
49    char *buf;
50    buf = malloc(256);
51
52This kind of memory can be released with:
53
54::
55
56    free(buf);
57
58It is recommended to use this kind of memory only when you are sure that
59you know the memory size needed and the memory will be used for short
60periods of time – that is it would not be appropriate to use statically
61allocated memory. An example might be to obtain a large memory buffer
62for reading and writing files.
63
64Pooled and Non-pooled Memory
65~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66
67In order to facility the handling of arbitrary length filenames and to
68efficiently handle a high volume of dynamic memory usage, we have
69implemented routines between the C code and the malloc routines. The
70first is called “Pooled” memory, and is memory, which once allocated and
71then released, is not returned to the system memory pool, but rather
72retained in a Bareos memory pool. The next request to acquire pooled
73memory will return any free memory block. In addition, each memory block
74has its current size associated with the block allowing for easy
75checking if the buffer is of sufficient size. This kind of memory would
76normally be used in high volume situations (lots of malloc()s and
77free()s) where the buffer length may have to frequently change to adapt
78to varying filename lengths.
79
80The non-pooled memory is handled by routines similar to those used for
81pooled memory, allowing for easy size checking. However, non-pooled
82memory is returned to the system rather than being saved in the Bareos
83pool. This kind of memory would normally be used in low volume
84situations (few malloc()s and free()s), but where the size of the buffer
85might have to be adjusted frequently.
86
87Types of Memory Pool:
88'''''''''''''''''''''
89
90Currently there are three memory pool types:
91
92-  PM_NOPOOL – non-pooled memory.
93
94-  PM_FNAME – a filename pool.
95
96-  PM_MESSAGE – a message buffer pool.
97
98-  PM_EMSG – error message buffer pool.
99
100Getting Memory:
101'''''''''''''''
102
103To get memory, one uses:
104
105::
106
107    void *get_pool_memory(pool);
108
109where **pool** is one of the above mentioned pool names. The size of the
110memory returned will be determined by the system to be most appropriate
111for the application.
112
113If you wish non-pooled memory, you may alternatively call:
114
115::
116
117    void *get_memory(size_t size);
118
119The buffer length will be set to the size specified, and it will be
120assigned to the PM_NOPOOL pool (no pooling).
121
122Releasing Memory:
123'''''''''''''''''
124
125To free memory acquired by either of the above two calls, use:
126
127::
128
129    void free_pool_memory(void *buffer);
130
131where buffer is the memory buffer returned when the memory was acquired.
132If the memory was originally allocated as type PM_NOPOOL, it will be
133released to the system, otherwise, it will be placed on the appropriate
134Bareos memory pool free chain to be used in a subsequent call for memory
135from that pool.
136
137Determining the Memory Size:
138''''''''''''''''''''''''''''
139
140To determine the memory buffer size, use:
141
142::
143
144    size_t sizeof_pool_memory(void *buffer);
145
146Resizing Pool Memory:
147'''''''''''''''''''''
148
149To resize pool memory, use:
150
151::
152
153    void *realloc_pool_memory(void *buffer);
154
155The buffer will be reallocated, and the contents of the original buffer
156will be preserved, but the address of the buffer may change.
157
158Automatic Size Adjustment:
159''''''''''''''''''''''''''
160
161To have the system check and if necessary adjust the size of your pooled
162memory buffer, use:
163
164::
165
166    void *check_pool_memory_size(void *buffer, size_t new-size);
167
168where **new-size** is the buffer length needed. Note, if the buffer is
169already equal to or larger than **new-size** no buffer size change will
170occur. However, if a buffer size change is needed, the original contents
171of the buffer will be preserved, but the buffer address may change. Many
172of the low level Bareos subroutines expect to be passed a pool memory
173buffer and use this call to ensure the buffer they use is sufficiently
174large.
175
176Releasing All Pooled Memory:
177''''''''''''''''''''''''''''
178
179In order to avoid orphaned buffer error messages when terminating the
180program, use:
181
182::
183
184    void close_memory_pool();
185
186to free all unused memory retained in the Bareos memory pool. Note, any
187memory not returned to the pool via free_pool_memory() will not be
188released by this call.
189
190Pooled Memory Statistics:
191'''''''''''''''''''''''''
192
193For debugging purposes and performance tuning, the following call will
194print the current memory pool statistics:
195
196::
197
198    void print_memory_pool_stats();
199
200an example output is:
201
202::
203
204    Pool  Maxsize  Maxused  Inuse
205       0      256        0      0
206       1      256        1      0
207       2      256        1      0
208