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