home *** CD-ROM | disk | FTP | other *** search
/ PC World 2001 April / PCWorld_2001-04_cd.bin / Software / TemaCD / webclean / !!!python!!! / BeOpen-Python-2.0.exe / PYMEM.H < prev    next >
Encoding:
C/C++ Source or Header  |  2000-09-01  |  5.2 KB  |  171 lines
  1.  
  2. /* Lowest-level memory allocation interface */
  3.  
  4. #ifndef Py_PYMEM_H
  5. #define Py_PYMEM_H
  6.  
  7. #include "pyport.h"
  8.  
  9. #ifdef __cplusplus
  10. extern "C" {
  11. #endif
  12.  
  13. /*
  14.  * Core memory allocator
  15.  * =====================
  16.  */
  17.  
  18. /* To make sure the interpreter is user-malloc friendly, all memory
  19.    APIs are implemented on top of this one.
  20.  
  21.    The PyCore_* macros can be defined to make the interpreter use a
  22.    custom allocator. Note that they are for internal use only. Both
  23.    the core and extension modules should use the PyMem_* API.
  24.  
  25.    See the comment block at the end of this file for two scenarios
  26.    showing how to use this to use a different allocator. */
  27.  
  28. #ifndef PyCore_MALLOC_FUNC
  29. #undef PyCore_REALLOC_FUNC
  30. #undef PyCore_FREE_FUNC
  31. #define PyCore_MALLOC_FUNC      malloc
  32. #define PyCore_REALLOC_FUNC     realloc
  33. #define PyCore_FREE_FUNC        free
  34. #endif
  35.  
  36. #ifndef PyCore_MALLOC_PROTO
  37. #undef PyCore_REALLOC_PROTO
  38. #undef PyCore_FREE_PROTO
  39. #define PyCore_MALLOC_PROTO    (size_t)
  40. #define PyCore_REALLOC_PROTO   (void *, size_t)
  41. #define PyCore_FREE_PROTO      (void *)
  42. #endif
  43.  
  44. #ifdef NEED_TO_DECLARE_MALLOC_AND_FRIEND
  45. extern void *PyCore_MALLOC_FUNC PyCore_MALLOC_PROTO;
  46. extern void *PyCore_REALLOC_FUNC PyCore_REALLOC_PROTO;
  47. extern void PyCore_FREE_FUNC PyCore_FREE_PROTO;
  48. #endif
  49.  
  50. #ifndef PyCore_MALLOC
  51. #undef PyCore_REALLOC
  52. #undef PyCore_FREE
  53. #define PyCore_MALLOC(n)        PyCore_MALLOC_FUNC(n)
  54. #define PyCore_REALLOC(p, n)    PyCore_REALLOC_FUNC((p), (n))
  55. #define PyCore_FREE(p)          PyCore_FREE_FUNC(p)
  56. #endif
  57.  
  58. /* BEWARE:
  59.  
  60.    Each interface exports both functions and macros. Extension modules
  61.    should normally use the functions for ensuring binary compatibility
  62.    of the user's code across Python versions. Subsequently, if the
  63.    Python runtime switches to its own malloc (different from standard
  64.    malloc), no recompilation is required for the extensions.
  65.  
  66.    The macro versions trade compatibility for speed. They can be used
  67.    whenever there is a performance problem, but their use implies
  68.    recompilation of the code for each new Python release. The Python
  69.    core uses the macros because it *is* compiled on every upgrade.
  70.    This might not be the case with 3rd party extensions in a custom
  71.    setup (for example, a customer does not always have access to the
  72.    source of 3rd party deliverables). You have been warned! */
  73.  
  74. /*
  75.  * Raw memory interface
  76.  * ====================
  77.  */
  78.  
  79. /* Functions */
  80.  
  81. /* Function wrappers around PyCore_MALLOC and friends; useful if you
  82.    need to be sure that you are using the same memory allocator as
  83.    Python.  Note that the wrappers make sure that allocating 0 bytes
  84.    returns a non-NULL pointer, even if the underlying malloc
  85.    doesn't. Returned pointers must be checked for NULL explicitly.
  86.    No action is performed on failure. */
  87. extern DL_IMPORT(void *) PyMem_Malloc(size_t);
  88. extern DL_IMPORT(void *) PyMem_Realloc(void *, size_t);
  89. extern DL_IMPORT(void) PyMem_Free(void *);
  90.  
  91. /* Starting from Python 1.6, the wrappers Py_{Malloc,Realloc,Free} are
  92.    no longer supported. They used to call PyErr_NoMemory() on failure. */
  93.  
  94. /* Macros */
  95. #define PyMem_MALLOC(n)         PyCore_MALLOC(n)
  96. #define PyMem_REALLOC(p, n)     PyCore_REALLOC((void *)(p), (n))
  97. #define PyMem_FREE(p)           PyCore_FREE((void *)(p))
  98.  
  99. /*
  100.  * Type-oriented memory interface
  101.  * ==============================
  102.  */
  103.  
  104. /* Functions */
  105. #define PyMem_New(type, n) \
  106.     ( (type *) PyMem_Malloc((n) * sizeof(type)) )
  107. #define PyMem_Resize(p, type, n) \
  108.     ( (p) = (type *) PyMem_Realloc((p), (n) * sizeof(type)) )
  109. #define PyMem_Del(p) PyMem_Free(p)
  110.  
  111. /* Macros */
  112. #define PyMem_NEW(type, n) \
  113.     ( (type *) PyMem_MALLOC(_PyMem_EXTRA + (n) * sizeof(type)) )
  114. #define PyMem_RESIZE(p, type, n) \
  115.     if ((p) == NULL) \
  116.         (p) = (type *)(PyMem_MALLOC( \
  117.                     _PyMem_EXTRA + (n) * sizeof(type))); \
  118.     else \
  119.         (p) = (type *)(PyMem_REALLOC((p), \
  120.                     _PyMem_EXTRA + (n) * sizeof(type)))
  121. #define PyMem_DEL(p) PyMem_FREE(p)
  122.  
  123. /* PyMem_XDEL is deprecated. To avoid the call when p is NULL,
  124.    it is recommended to write the test explicitly in the code.
  125.    Note that according to ANSI C, free(NULL) has no effect. */
  126.  
  127. #ifdef __cplusplus
  128. }
  129. #endif
  130.  
  131. /* SCENARIOS
  132.  
  133.    Here are two scenarios by Vladimir Marangozov (the author of the
  134.    memory allocation redesign).
  135.  
  136.    1) Scenario A
  137.  
  138.    Suppose you want to use a debugging malloc library that collects info on
  139.    where the malloc calls originate from. Assume the interface is:
  140.  
  141.    d_malloc(size_t n, char* src_file, unsigned long src_line) c.s.
  142.  
  143.    In this case, you would define (for example in config.h) :
  144.  
  145.    #define PyCore_MALLOC_FUNC      d_malloc
  146.    ...
  147.    #define PyCore_MALLOC_PROTO    (size_t, char *, unsigned long)
  148.    ...
  149.    #define NEED_TO_DECLARE_MALLOC_AND_FRIEND
  150.  
  151.    #define PyCore_MALLOC(n)    PyCore_MALLOC_FUNC((n), __FILE__, __LINE__)
  152.    ...
  153.  
  154.    2) Scenario B
  155.  
  156.    Suppose you want to use malloc hooks (defined & initialized in a 3rd party
  157.    malloc library) instead of malloc functions.  In this case, you would
  158.    define:
  159.  
  160.    #define PyCore_MALLOC_FUNC    (*malloc_hook)
  161.    ...
  162.    #define NEED_TO_DECLARE_MALLOC_AND_FRIEND
  163.  
  164.    and ignore the previous definitions about PyCore_MALLOC_FUNC, etc.
  165.  
  166.  
  167. */
  168.  
  169.  
  170. #endif /* !Py_PYMEM_H */
  171.