First cut at repairing out-of-date comments; make alignment of macro defs
all the same within the #ifdef WITH_PYMALLOC block.
diff --git a/Include/objimpl.h b/Include/objimpl.h
index e5278d1..ed7042f 100644
--- a/Include/objimpl.h
+++ b/Include/objimpl.h
@@ -17,15 +17,17 @@
represent the object and 'typeobj' the address of the corresponding
type object. Reference count and type pointer are filled in; the
rest of the bytes of the object are *undefined*! The resulting
- expression type is 'type *'. The size of the object is actually
- determined by the tp_basicsize field of the type object.
+ expression type is 'type *'. The size of the object is determined
+ by the tp_basicsize field of the type object.
- PyObject_NewVar(type, typeobj, n) is similar but allocates a
variable-size object with n extra items. The size is computed as
tp_basicsize plus n * tp_itemsize. This fills in the ob_size field
as well.
- - PyObject_Del(op) releases the memory allocated for an object.
+ - PyObject_Del(op) releases the memory allocated for an object. It
+ does not run a destructor -- it only frees the memory. PyObject_Free
+ is identical.
- PyObject_Init(op, typeobj) and PyObject_InitVar(op, typeobj, n) are
similar to PyObject_{New, NewVar} except that they don't allocate
@@ -34,7 +36,9 @@
allocator) and initialize its object header fields.
Note that objects created with PyObject_{New, NewVar} are allocated
-using the specialized Python allocator (implemented in obmalloc.c).
+using the specialized Python allocator (implemented in obmalloc.c), if
+WITH_PYMALLOC is enabled. In addition, a special debugging allocator
+is used if PYMALLOC_DEBUG is also #defined.
In case a specific form of memory management is needed, implying that
the objects would not reside in the Python heap (for example standard
@@ -70,11 +74,16 @@
/* Functions */
-/* Wrappers that useful if you need to be sure that you are using the
- same object memory allocator as Python. These wrappers *do not* make
- sure that allocating 0 bytes returns a non-NULL pointer. Returned
- pointers must be checked for NULL explicitly; no action is performed
- on failure. */
+/* Functions to call the same malloc/realloc/free as used by Python's
+ object allocator. If WITH_PYMALLOC is enabled, these may differ from
+ the platform malloc/realloc/free. The Python object allocator is
+ designed for fast, cache-conscious allocation of many "small" objects,
+ with low hidden memory overhead. PyObject_Malloc(0) returns a unique
+ non-NULL pointer if possible. PyObject_Realloc(NULL, n) acts like
+ PyObject_Malloc(n). PyObject_Realloc(p != NULL, 0) does not return
+ NULL or free the memory at p. Returned pointers must be checked for
+ NULL explicitly; no action is performed on failure other than to return
+ NULL. */
extern DL_IMPORT(void *) PyObject_Malloc(size_t);
extern DL_IMPORT(void *) PyObject_Realloc(void *, size_t);
extern DL_IMPORT(void) PyObject_Free(void *);
@@ -89,12 +98,12 @@
DL_IMPORT(void) _PyObject_DebugDumpAddress(const void *p);
DL_IMPORT(void) _PyObject_DebugCheckAddress(const void *p);
DL_IMPORT(void) _PyObject_DebugDumpStats(void);
-#define PyObject_MALLOC _PyObject_DebugMalloc
-#define PyObject_Malloc _PyObject_DebugMalloc
-#define PyObject_REALLOC _PyObject_DebugRealloc
-#define PyObject_Realloc _PyObject_DebugRealloc
-#define PyObject_FREE _PyObject_DebugFree
-#define PyObject_Free _PyObject_DebugFree
+#define PyObject_MALLOC _PyObject_DebugMalloc
+#define PyObject_Malloc _PyObject_DebugMalloc
+#define PyObject_REALLOC _PyObject_DebugRealloc
+#define PyObject_Realloc _PyObject_DebugRealloc
+#define PyObject_FREE _PyObject_DebugFree
+#define PyObject_Free _PyObject_DebugFree
#else /* WITH_PYMALLOC && ! PYMALLOC_DEBUG */
#define PyObject_MALLOC PyObject_Malloc