git.sur5r.net Git - bacula/docs/blob - docs/manuals/de/old/developers/mempool.tex

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