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