1 /*

     2  * Summary: interface for the memory allocator

     3  * Description: provides interfaces for the memory allocator,

     4  *              including debugging capabilities.

     5  *

     6  * Copy: See Copyright for the status of this software.

     7  *

     8  * Author: Daniel Veillard

     9  * Portion Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. 

    10  */

    11 

    12 /** @file

    13 @publishedAll

    14 @released

    15 */

    16 

    17 #ifndef LIBXML2_XMLMEMORY_H

    18 #define LIBXML2_XMLMEMORY_H

    19 

    20 #include <stddef.h>

    21 #include <stdapis/libxml2/libxml2_xmlversion.h>

    22 

    23 

    24 /**

    25  * DEBUG_MEMORY:

    26  *

    27  * DEBUG_MEMORY replaces the allocator with a collect and debug

    28  * shell to the libc allocator.

    29  * DEBUG_MEMORY should only be activated when debugging

    30  * libxml i.e. if libxml has been configured with --with-debug-mem too.

    31  */

    32 /* #define DEBUG_MEMORY_FREED */

    33 /* #define DEBUG_MEMORY_LOCATION */

    34 

    35 #ifdef DEBUG

    36 #ifndef DEBUG_MEMORY

    37 #define DEBUG_MEMORY

    38 #endif

    39 #endif

    40 

    41 /**

    42  * DEBUG_MEMORY_LOCATION:

    43  *

    44  * DEBUG_MEMORY_LOCATION should be activated only when debugging

    45  * libxml i.e. if libxml has been configured with --with-debug-mem too.

    46  */

    47 #ifdef DEBUG_MEMORY_LOCATION

    48 #endif

    49 

    50 #ifdef __cplusplus

    51 extern "C" {

    52 #endif

    53 

    54 /*

    55  * The XML memory wrapper support 4 basic overloadable functions.

    56  */

    57 /**

    58  * xmlFreeFunc:

    59  * @param mem an already allocated block of memory

    60  *

    61  * Signature for a free() implementation.

    62  */

    63 typedef void (XMLCALL *xmlFreeFunc)(void *mem);

    64 /**

    65  * xmlMallocFunc:

    66  * @param size the size requested in bytes

    67  *

    68  * Signature for a malloc() implementation.

    69  *

    70  * Returns a pointer to the newly allocated block or NULL in case of error.

    71  */

    72 typedef void *(XMLCALL *xmlMallocFunc)(size_t size);

    73 

    74 /**

    75  * xmlReallocFunc:

    76  * @param mem an already allocated block of memory

    77  * @param size the new size requested in bytes

    78  *

    79  * Signature for a realloc() implementation.

    80  *

    81  * Returns a pointer to the newly reallocated block or NULL in case of error.

    82  */

    83 typedef void *(XMLCALL *xmlReallocFunc)(void *mem, size_t size);

    84 

    85 /**

    86  * xmlStrdupFunc:

    87  * @param str a zero terminated string

    88  *

    89  * Signature for an strdup() implementation.

    90  *

    91  * Returns the copy of the string or NULL in case of error.

    92  */

    93 typedef char *(XMLCALL *xmlStrdupFunc)(const char *str);

    94 

    95 /*The 4 interfaces used for all memory handling within libxml.

    96 LIBXML_DLL_IMPORT extern xmlFreeFunc xmlFree;

    97 LIBXML_DLL_IMPORT extern xmlMallocFunc xmlMalloc;

    98 LIBXML_DLL_IMPORT extern xmlMallocFunc xmlMallocAtomic;

    99 LIBXML_DLL_IMPORT extern xmlReallocFunc xmlRealloc;

   100 LIBXML_DLL_IMPORT extern xmlStrdupFunc xmlMemStrdup;

   101  */

   102 

   103 /*

   104  * The way to overload the existing functions.

   105  * The xmlGc function have an extra entry for atomic block

   106  * allocations useful for garbage collected memory allocators

   107  */

   108 XMLPUBFUN int XMLCALL

   109         xmlMemSetup     (xmlFreeFunc freeFunc,

   110                          xmlMallocFunc mallocFunc,

   111                          xmlReallocFunc reallocFunc,

   112                          xmlStrdupFunc strdupFunc);

   113 XMLPUBFUN int XMLCALL

   114         xmlMemGet       (xmlFreeFunc *freeFunc,

   115                          xmlMallocFunc *mallocFunc,

   116                          xmlReallocFunc *reallocFunc,

   117                          xmlStrdupFunc *strdupFunc);

   118 

   119 #ifndef XMLENGINE_EXCLUDE_UNUSED

   120 

   121 XMLPUBFUN int XMLCALL

   122         xmlGcMemSetup   (xmlFreeFunc freeFunc,

   123                          xmlMallocFunc mallocFunc,

   124                          xmlMallocFunc mallocAtomicFunc,

   125                          xmlReallocFunc reallocFunc,

   126                          xmlStrdupFunc strdupFunc);

   127 

   128 XMLPUBFUN int XMLCALL

   129         xmlGcMemGet     (xmlFreeFunc *freeFunc,

   130                          xmlMallocFunc *mallocFunc,

   131                          xmlMallocFunc *mallocAtomicFunc,

   132                          xmlReallocFunc *reallocFunc,

   133                          xmlStrdupFunc *strdupFunc);

   134 #endif /* ifndef XMLENGINE_EXCLUDE_UNUSED */

   135 

   136 /*

   137  * Initialization of the memory layer.

   138  */

   139 XMLPUBFUN int XMLCALL

   140         xmlInitMemory   (void);

   141 

   142 /*

   143  * Cleanup of the memory layer.

   144  */

   145 XMLPUBFUN void XMLCALL

   146                 xmlCleanupMemory        (void);

   147 /*

   148  * These are specific to the XML debug memory wrapper.

   149  */

   150 XMLPUBFUN int XMLCALL

   151         xmlMemUsed      (void);

   152 

   153 #ifndef XMLENGINE_EXCLUDE_FILE_FUNC

   154 XMLPUBFUN void XMLCALL

   155         xmlMemDisplay   (FILE *fp);

   156 XMLPUBFUN void XMLCALL

   157         xmlMemShow      (FILE *fp, int nr);

   158 #endif

   159 

   160 XMLPUBFUN void XMLCALL

   161         xmlMemoryDump   (void);

   162 XMLPUBFUN void * XMLCALL

   163         xmlMemMalloc    (size_t size);

   164 XMLPUBFUN void * XMLCALL

   165         xmlMemRealloc   (void *ptr,size_t size);

   166 XMLPUBFUN void XMLCALL

   167         xmlMemFree      (void *ptr);

   168 XMLPUBFUN char * XMLCALL

   169         xmlMemoryStrdup (const char *str);

   170 XMLPUBFUN void * XMLCALL

   171         xmlMallocLoc    (size_t size, const char *file, int line);

   172 XMLPUBFUN void * XMLCALL

   173         xmlReallocLoc   (void *ptr, size_t size, const char *file, int line);

   174 XMLPUBFUN void * XMLCALL

   175         xmlMallocAtomicLoc (size_t size, const char *file, int line);

   176 XMLPUBFUN char * XMLCALL

   177         xmlMemStrdupLoc (const char *str, const char *file, int line);

   178 

   179 

   180 #ifdef DEBUG_MEMORY_LOCATION

   181 /**

   182  * xmlMalloc:

   183  * @param size number of bytes to allocate

   184  *

   185  * Wrapper for the malloc() function used in the XML library.

   186  *

   187  * Returns the pointer to the allocated area or NULL in case of error.

   188  */

   189 #define xmlMalloc(size) xmlMallocLoc((size), __FILE__, __LINE__)

   190 /**

   191  * xmlMallocAtomic:

   192  * @param size number of bytes to allocate

   193  *

   194  * Wrapper for the malloc() function used in the XML library for allocation

   195  * of block not containing pointers to other areas.

   196  *

   197  * Returns the pointer to the allocated area or NULL in case of error.

   198  */

   199 #define xmlMallocAtomic(size) xmlMallocAtomicLoc((size), __FILE__, __LINE__)

   200 /**

   201  * xmlRealloc:

   202  * @param ptr pointer to the existing allocated area

   203  * @param size number of bytes to allocate

   204  *

   205  * Wrapper for the realloc() function used in the XML library.

   206  *

   207  * Returns the pointer to the allocated area or NULL in case of error.

   208  */

   209 #define xmlRealloc(ptr, size) xmlReallocLoc((ptr), (size), __FILE__, __LINE__)

   210 /**

   211  * xmlMemStrdup:

   212  * @param str pointer to the existing string

   213  *

   214  * Wrapper for the strdup() function, xmlStrdup() is usually preferred.

   215  *

   216  * Returns the pointer to the allocated area or NULL in case of error.

   217  */

   218 #define xmlMemStrdup(str) xmlMemStrdupLoc((str), __FILE__, __LINE__)

   219 

   220 #endif /* DEBUG_MEMORY_LOCATION */

   221 

   222 #ifdef __cplusplus

   223 }

   224 #endif /* __cplusplus */

   225 

   226 

   227 #endif  /* LIBXML2_MEMORY_H */