home *** CD-ROM | disk | FTP | other *** search
/ H4CK3R 14 / hacker14.iso / programacao / pythonwin / python.exe / PYMEM.H < prev    next >
Encoding:
C/C++ Source or Header  |  2002-11-23  |  4.0 KB  |  109 lines
  1. /* The PyMem_ family:  low-level memory allocation interfaces.
  2.    See objimpl.h for the PyObject_ memory family.
  3. */
  4.  
  5. #ifndef Py_PYMEM_H
  6. #define Py_PYMEM_H
  7.  
  8. #include "pyport.h"
  9.  
  10. #ifdef __cplusplus
  11. extern "C" {
  12. #endif
  13.  
  14. /* BEWARE:
  15.  
  16.    Each interface exports both functions and macros.  Extension modules should
  17.    use the functions, to ensure binary compatibility across Python versions.
  18.    Because the Python implementation is free to change internal details, and
  19.    the macros may (or may not) expose details for speed, if you do use the
  20.    macros you must recompile your extensions with each Python release.
  21.  
  22.    Never mix calls to PyMem_ with calls to the platform malloc/realloc/
  23.    calloc/free.  For example, on Windows different DLLs may end up using
  24.    different heaps, and if you use PyMem_Malloc you'll get the memory from the
  25.    heap used by the Python DLL; it could be a disaster if you free()'ed that
  26.    directly in your own extension.  Using PyMem_Free instead ensures Python
  27.    can return the memory to the proper heap.  As another example, in
  28.    PYMALLOC_DEBUG mode, Python wraps all calls to all PyMem_ and PyObject_
  29.    memory functions in special debugging wrappers that add additional
  30.    debugging info to dynamic memory blocks.  The system routines have no idea
  31.    what to do with that stuff, and the Python wrappers have no idea what to do
  32.    with raw blocks obtained directly by the system routines then.
  33. */
  34.  
  35. /*
  36.  * Raw memory interface
  37.  * ====================
  38.  */
  39.  
  40. /* Functions
  41.  
  42.    Functions supplying platform-independent semantics for malloc/realloc/
  43.    free.  These functions make sure that allocating 0 bytes returns a distinct
  44.    non-NULL pointer (whenever possible -- if we're flat out of memory, NULL
  45.    may be returned), even if the platform malloc and realloc don't.
  46.    Returned pointers must be checked for NULL explicitly.  No action is
  47.    performed on failure (no exception is set, no warning is printed, etc).
  48. */
  49.  
  50. PyAPI_FUNC(void *) PyMem_Malloc(size_t);
  51. PyAPI_FUNC(void *) PyMem_Realloc(void *, size_t);
  52. PyAPI_FUNC(void) PyMem_Free(void *);
  53.  
  54. /* Starting from Python 1.6, the wrappers Py_{Malloc,Realloc,Free} are
  55.    no longer supported. They used to call PyErr_NoMemory() on failure. */
  56.  
  57. /* Macros. */
  58. #ifdef PYMALLOC_DEBUG
  59. /* Redirect all memory operations to Python's debugging allocator. */
  60. #define PyMem_MALLOC        PyObject_MALLOC
  61. #define PyMem_REALLOC        PyObject_REALLOC
  62.  
  63. #else    /* ! PYMALLOC_DEBUG */
  64.  
  65. /* PyMem_MALLOC(0) means malloc(1). Some systems would return NULL
  66.    for malloc(0), which would be treated as an error. Some platforms
  67.    would return a pointer with no memory behind it, which would break
  68.    pymalloc. To solve these problems, allocate an extra byte. */
  69. #define PyMem_MALLOC(n)         malloc((n) ? (n) : 1)
  70. #define PyMem_REALLOC(p, n)     realloc((p), (n) ? (n) : 1)
  71.  
  72. #endif    /* PYMALLOC_DEBUG */
  73.  
  74. /* In order to avoid breaking old code mixing PyObject_{New, NEW} with
  75.    PyMem_{Del, DEL} and PyMem_{Free, FREE}, the PyMem "release memory"
  76.    functions have to be redirected to the object deallocator. */
  77. #define PyMem_FREE               PyObject_FREE
  78.  
  79. /*
  80.  * Type-oriented memory interface
  81.  * ==============================
  82.  *
  83.  * These are carried along for historical reasons.  There's rarely a good
  84.  * reason to use them anymore (you can just as easily do the multiply and
  85.  * cast yourself).
  86.  */
  87.  
  88. #define PyMem_New(type, n) \
  89.     ( (type *) PyMem_Malloc((n) * sizeof(type)) )
  90. #define PyMem_NEW(type, n) \
  91.     ( (type *) PyMem_MALLOC((n) * sizeof(type)) )
  92.  
  93. #define PyMem_Resize(p, type, n) \
  94.     ( (p) = (type *) PyMem_Realloc((p), (n) * sizeof(type)) )
  95. #define PyMem_RESIZE(p, type, n) \
  96.     ( (p) = (type *) PyMem_REALLOC((p), (n) * sizeof(type)) )
  97.  
  98. /* In order to avoid breaking old code mixing PyObject_{New, NEW} with
  99.    PyMem_{Del, DEL} and PyMem_{Free, FREE}, the PyMem "release memory"
  100.    functions have to be redirected to the object deallocator. */
  101. #define PyMem_Del        PyObject_Free
  102. #define PyMem_DEL        PyObject_FREE
  103.  
  104. #ifdef __cplusplus
  105. }
  106. #endif
  107.  
  108. #endif /* !Py_PYMEM_H */
  109.