Added words about what PyArena_Malloc() does.

tim-one · tim-one · commit 6fd92dc44f6b · 2006-03-02T21:14:45.000Z
diff --git a/Include/pyarena.h b/Include/pyarena.h
@@ -35,11 +35,23 @@ extern "C" {
   PyAPI_FUNC(PyArena *) PyArena_New(void);
   PyAPI_FUNC(void) PyArena_Free(PyArena *);
 
-  PyAPI_FUNC(void *) PyArena_Malloc(PyArena *, size_t);
+  /* Mostly like malloc(), return the address of a block of memory spanning
+   * `size` bytes, or return NULL (without setting an exception) if enough
+   * new memory can't be obtained.  Unlike malloc(0), PyArena_Malloc() with
+   * size=0 does not guarantee to return a unique pointer (the pointer
+   * returned may equal one or more other pointers obtained from
+   * PyArena_Malloc()).
+   * Note that pointers obtained via PyArena_Malloc() must never be passed to
+   * the system free() or realloc(), or to any of Python's similar memory-
+   * management functions.  PyArena_Malloc()-obtained pointers remain valid
+   * until PyArena_Free(ar) is called, at which point all pointers obtained
+   * from the arena `ar` become invalid simultaneously.
+   */
+  PyAPI_FUNC(void *) PyArena_Malloc(PyArena *, size_t size);
 
-  /* This routines isn't a proper arena allocation routine.  It takes
-     a PyObject* and records it so that it can be DECREFed when the
-     arena is freed.
+  /* This routine isn't a proper arena allocation routine.  It takes
+   * a PyObject* and records it so that it can be DECREFed when the
+   * arena is freed.
    */
   PyAPI_FUNC(int) PyArena_AddPyObject(PyArena *, PyObject *);
 
diff --git a/Python/pyarena.c b/Python/pyarena.c
@@ -150,7 +150,7 @@ PyArena_Malloc(PyArena *arena, size_t size)
                 arena->total_blocks++;
                 arena->total_block_size += arena->a_cur->ab_size;
                 if (arena->a_cur->ab_size > DEFAULT_BLOCK_SIZE)
-                  arena->total_big_blocks++;
+                        ++arena->total_big_blocks;
 #endif
 	}
 	return p;

Original file line number	Diff line number	Diff line change
`@@ -150,7 +150,7 @@ PyArena_Malloc(PyArena *arena, size_t size)`
`150`	`150`	`arena->total_blocks++;`
`151`	`151`	`arena->total_block_size += arena->a_cur->ab_size;`
`152`	`152`	`if (arena->a_cur->ab_size > DEFAULT_BLOCK_SIZE)`
`153`		`- arena->total_big_blocks++;`
	`153`	`+ ++arena->total_big_blocks;`
`154`	`154`	`#endif`
`155`	`155`	`}`
`156`	`156`	`return p;`