williamr@4: /*
williamr@4:  * Summary: interface for the memory allocator
williamr@4:  * Description: provides interfaces for the memory allocator,
williamr@4:  *              including debugging capabilities.
williamr@4:  *
williamr@4:  * Copy: See Copyright for the status of this software.
williamr@4:  *
williamr@4:  * Author: Daniel Veillard
williamr@4:  * Portion Copyright © 2009 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. 
williamr@4:  */
williamr@4: 
williamr@4: /** @file
williamr@4: @publishedAll
williamr@4: @released
williamr@4: */
williamr@4: 
williamr@4: #ifndef LIBXML2_XMLMEMORY_H
williamr@4: #define LIBXML2_XMLMEMORY_H
williamr@4: 
williamr@4: #include <stddef.h>
williamr@4: #include <stdapis/libxml2/libxml2_xmlversion.h>
williamr@4: 
williamr@4: 
williamr@4: /**
williamr@4:  * DEBUG_MEMORY:
williamr@4:  *
williamr@4:  * DEBUG_MEMORY replaces the allocator with a collect and debug
williamr@4:  * shell to the libc allocator.
williamr@4:  * DEBUG_MEMORY should only be activated when debugging
williamr@4:  * libxml i.e. if libxml has been configured with --with-debug-mem too.
williamr@4:  */
williamr@4: /* #define DEBUG_MEMORY_FREED */
williamr@4: /* #define DEBUG_MEMORY_LOCATION */
williamr@4: 
williamr@4: #ifdef DEBUG
williamr@4: #ifndef DEBUG_MEMORY
williamr@4: #define DEBUG_MEMORY
williamr@4: #endif
williamr@4: #endif
williamr@4: 
williamr@4: /**
williamr@4:  * DEBUG_MEMORY_LOCATION:
williamr@4:  *
williamr@4:  * DEBUG_MEMORY_LOCATION should be activated only when debugging
williamr@4:  * libxml i.e. if libxml has been configured with --with-debug-mem too.
williamr@4:  */
williamr@4: #ifdef DEBUG_MEMORY_LOCATION
williamr@4: #endif
williamr@4: 
williamr@4: #ifdef __cplusplus
williamr@4: extern "C" {
williamr@4: #endif
williamr@4: 
williamr@4: /*
williamr@4:  * The XML memory wrapper support 4 basic overloadable functions.
williamr@4:  */
williamr@4: /**
williamr@4:  * xmlFreeFunc:
williamr@4:  * @param mem an already allocated block of memory
williamr@4:  *
williamr@4:  * Signature for a free() implementation.
williamr@4:  */
williamr@4: typedef void (XMLCALL *xmlFreeFunc)(void *mem);
williamr@4: /**
williamr@4:  * xmlMallocFunc:
williamr@4:  * @param size the size requested in bytes
williamr@4:  *
williamr@4:  * Signature for a malloc() implementation.
williamr@4:  *
williamr@4:  * Returns a pointer to the newly allocated block or NULL in case of error.
williamr@4:  */
williamr@4: typedef void *(XMLCALL *xmlMallocFunc)(size_t size);
williamr@4: 
williamr@4: /**
williamr@4:  * xmlReallocFunc:
williamr@4:  * @param mem an already allocated block of memory
williamr@4:  * @param size the new size requested in bytes
williamr@4:  *
williamr@4:  * Signature for a realloc() implementation.
williamr@4:  *
williamr@4:  * Returns a pointer to the newly reallocated block or NULL in case of error.
williamr@4:  */
williamr@4: typedef void *(XMLCALL *xmlReallocFunc)(void *mem, size_t size);
williamr@4: 
williamr@4: /**
williamr@4:  * xmlStrdupFunc:
williamr@4:  * @param str a zero terminated string
williamr@4:  *
williamr@4:  * Signature for an strdup() implementation.
williamr@4:  *
williamr@4:  * Returns the copy of the string or NULL in case of error.
williamr@4:  */
williamr@4: typedef char *(XMLCALL *xmlStrdupFunc)(const char *str);
williamr@4: 
williamr@4: /*The 4 interfaces used for all memory handling within libxml.
williamr@4: LIBXML_DLL_IMPORT extern xmlFreeFunc xmlFree;
williamr@4: LIBXML_DLL_IMPORT extern xmlMallocFunc xmlMalloc;
williamr@4: LIBXML_DLL_IMPORT extern xmlMallocFunc xmlMallocAtomic;
williamr@4: LIBXML_DLL_IMPORT extern xmlReallocFunc xmlRealloc;
williamr@4: LIBXML_DLL_IMPORT extern xmlStrdupFunc xmlMemStrdup;
williamr@4:  */
williamr@4: 
williamr@4: /*
williamr@4:  * The way to overload the existing functions.
williamr@4:  * The xmlGc function have an extra entry for atomic block
williamr@4:  * allocations useful for garbage collected memory allocators
williamr@4:  */
williamr@4: XMLPUBFUN int XMLCALL
williamr@4:         xmlMemSetup     (xmlFreeFunc freeFunc,
williamr@4:                          xmlMallocFunc mallocFunc,
williamr@4:                          xmlReallocFunc reallocFunc,
williamr@4:                          xmlStrdupFunc strdupFunc);
williamr@4: XMLPUBFUN int XMLCALL
williamr@4:         xmlMemGet       (xmlFreeFunc *freeFunc,
williamr@4:                          xmlMallocFunc *mallocFunc,
williamr@4:                          xmlReallocFunc *reallocFunc,
williamr@4:                          xmlStrdupFunc *strdupFunc);
williamr@4: 
williamr@4: #ifndef XMLENGINE_EXCLUDE_UNUSED
williamr@4: 
williamr@4: XMLPUBFUN int XMLCALL
williamr@4:         xmlGcMemSetup   (xmlFreeFunc freeFunc,
williamr@4:                          xmlMallocFunc mallocFunc,
williamr@4:                          xmlMallocFunc mallocAtomicFunc,
williamr@4:                          xmlReallocFunc reallocFunc,
williamr@4:                          xmlStrdupFunc strdupFunc);
williamr@4: 
williamr@4: XMLPUBFUN int XMLCALL
williamr@4:         xmlGcMemGet     (xmlFreeFunc *freeFunc,
williamr@4:                          xmlMallocFunc *mallocFunc,
williamr@4:                          xmlMallocFunc *mallocAtomicFunc,
williamr@4:                          xmlReallocFunc *reallocFunc,
williamr@4:                          xmlStrdupFunc *strdupFunc);
williamr@4: #endif /* ifndef XMLENGINE_EXCLUDE_UNUSED */
williamr@4: 
williamr@4: /*
williamr@4:  * Initialization of the memory layer.
williamr@4:  */
williamr@4: XMLPUBFUN int XMLCALL
williamr@4:         xmlInitMemory   (void);
williamr@4: 
williamr@4: /*
williamr@4:  * Cleanup of the memory layer.
williamr@4:  */
williamr@4: XMLPUBFUN void XMLCALL
williamr@4:                 xmlCleanupMemory        (void);
williamr@4: /*
williamr@4:  * These are specific to the XML debug memory wrapper.
williamr@4:  */
williamr@4: XMLPUBFUN int XMLCALL
williamr@4:         xmlMemUsed      (void);
williamr@4: 
williamr@4: #ifndef XMLENGINE_EXCLUDE_FILE_FUNC
williamr@4: XMLPUBFUN void XMLCALL
williamr@4:         xmlMemDisplay   (FILE *fp);
williamr@4: XMLPUBFUN void XMLCALL
williamr@4:         xmlMemShow      (FILE *fp, int nr);
williamr@4: #endif
williamr@4: 
williamr@4: XMLPUBFUN void XMLCALL
williamr@4:         xmlMemoryDump   (void);
williamr@4: XMLPUBFUN void * XMLCALL
williamr@4:         xmlMemMalloc    (size_t size);
williamr@4: XMLPUBFUN void * XMLCALL
williamr@4:         xmlMemRealloc   (void *ptr,size_t size);
williamr@4: XMLPUBFUN void XMLCALL
williamr@4:         xmlMemFree      (void *ptr);
williamr@4: XMLPUBFUN char * XMLCALL
williamr@4:         xmlMemoryStrdup (const char *str);
williamr@4: XMLPUBFUN void * XMLCALL
williamr@4:         xmlMallocLoc    (size_t size, const char *file, int line);
williamr@4: XMLPUBFUN void * XMLCALL
williamr@4:         xmlReallocLoc   (void *ptr, size_t size, const char *file, int line);
williamr@4: XMLPUBFUN void * XMLCALL
williamr@4:         xmlMallocAtomicLoc (size_t size, const char *file, int line);
williamr@4: XMLPUBFUN char * XMLCALL
williamr@4:         xmlMemStrdupLoc (const char *str, const char *file, int line);
williamr@4: 
williamr@4: 
williamr@4: #ifdef DEBUG_MEMORY_LOCATION
williamr@4: /**
williamr@4:  * xmlMalloc:
williamr@4:  * @param size number of bytes to allocate
williamr@4:  *
williamr@4:  * Wrapper for the malloc() function used in the XML library.
williamr@4:  *
williamr@4:  * Returns the pointer to the allocated area or NULL in case of error.
williamr@4:  */
williamr@4: #define xmlMalloc(size) xmlMallocLoc((size), __FILE__, __LINE__)
williamr@4: /**
williamr@4:  * xmlMallocAtomic:
williamr@4:  * @param size number of bytes to allocate
williamr@4:  *
williamr@4:  * Wrapper for the malloc() function used in the XML library for allocation
williamr@4:  * of block not containing pointers to other areas.
williamr@4:  *
williamr@4:  * Returns the pointer to the allocated area or NULL in case of error.
williamr@4:  */
williamr@4: #define xmlMallocAtomic(size) xmlMallocAtomicLoc((size), __FILE__, __LINE__)
williamr@4: /**
williamr@4:  * xmlRealloc:
williamr@4:  * @param ptr pointer to the existing allocated area
williamr@4:  * @param size number of bytes to allocate
williamr@4:  *
williamr@4:  * Wrapper for the realloc() function used in the XML library.
williamr@4:  *
williamr@4:  * Returns the pointer to the allocated area or NULL in case of error.
williamr@4:  */
williamr@4: #define xmlRealloc(ptr, size) xmlReallocLoc((ptr), (size), __FILE__, __LINE__)
williamr@4: /**
williamr@4:  * xmlMemStrdup:
williamr@4:  * @param str pointer to the existing string
williamr@4:  *
williamr@4:  * Wrapper for the strdup() function, xmlStrdup() is usually preferred.
williamr@4:  *
williamr@4:  * Returns the pointer to the allocated area or NULL in case of error.
williamr@4:  */
williamr@4: #define xmlMemStrdup(str) xmlMemStrdupLoc((str), __FILE__, __LINE__)
williamr@4: 
williamr@4: #endif /* DEBUG_MEMORY_LOCATION */
williamr@4: 
williamr@4: #ifdef __cplusplus
williamr@4: }
williamr@4: #endif /* __cplusplus */
williamr@4: 
williamr@4: 
williamr@4: #endif  /* LIBXML2_MEMORY_H */