summaryrefslogtreecommitdiffstats
path: root/Doc/c-api/memory.rst
diff options
context:
space:
mode:
authorGeorg Brandl <georg@python.org>2010-10-06 10:11:56 (GMT)
committerGeorg Brandl <georg@python.org>2010-10-06 10:11:56 (GMT)
commit60203b41b03d03361754d264543d5fbe6259eb25 (patch)
tree005d0d6be6437244ae360ebc0d65fa7b149a8093 /Doc/c-api/memory.rst
parent64a41edb039afee683d69bd6f72e3709ff11bd93 (diff)
downloadcpython-60203b41b03d03361754d264543d5fbe6259eb25.zip
cpython-60203b41b03d03361754d264543d5fbe6259eb25.tar.gz
cpython-60203b41b03d03361754d264543d5fbe6259eb25.tar.bz2
Migrate to Sphinx 1.0 C language constructs.
Diffstat (limited to 'Doc/c-api/memory.rst')
-rw-r--r--Doc/c-api/memory.rst48
1 files changed, 24 insertions, 24 deletions
diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst
index 81d7cd9..b80b3d5 100644
--- a/Doc/c-api/memory.rst
+++ b/Doc/c-api/memory.rst
@@ -47,8 +47,8 @@ API functions listed in this document.
single: free()
To avoid memory corruption, extension writers should never try to operate on
-Python objects with the functions exported by the C library: :cfunc:`malloc`,
-:cfunc:`calloc`, :cfunc:`realloc` and :cfunc:`free`. This will result in mixed
+Python objects with the functions exported by the C library: :c:func:`malloc`,
+:c:func:`calloc`, :c:func:`realloc` and :c:func:`free`. This will result in mixed
calls between the C allocator and the Python memory manager with fatal
consequences, because they implement different algorithms and operate on
different heaps. However, one may safely allocate and release memory blocks
@@ -94,65 +94,65 @@ behavior when requesting zero bytes, are available for allocating and releasing
memory from the Python heap:
-.. cfunction:: void* PyMem_Malloc(size_t n)
+.. c:function:: void* PyMem_Malloc(size_t n)
- Allocates *n* bytes and returns a pointer of type :ctype:`void\*` to the
+ Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
allocated memory, or *NULL* if the request fails. Requesting zero bytes returns
- a distinct non-*NULL* pointer if possible, as if :cfunc:`PyMem_Malloc(1)` had
+ a distinct non-*NULL* pointer if possible, as if :c:func:`PyMem_Malloc(1)` had
been called instead. The memory will not have been initialized in any way.
-.. cfunction:: void* PyMem_Realloc(void *p, size_t n)
+.. c:function:: void* PyMem_Realloc(void *p, size_t n)
Resizes the memory block pointed to by *p* to *n* bytes. The contents will be
unchanged to the minimum of the old and the new sizes. If *p* is *NULL*, the
- call is equivalent to :cfunc:`PyMem_Malloc(n)`; else if *n* is equal to zero,
+ call is equivalent to :c:func:`PyMem_Malloc(n)`; else if *n* is equal to zero,
the memory block is resized but is not freed, and the returned pointer is
non-*NULL*. Unless *p* is *NULL*, it must have been returned by a previous call
- to :cfunc:`PyMem_Malloc` or :cfunc:`PyMem_Realloc`. If the request fails,
- :cfunc:`PyMem_Realloc` returns *NULL* and *p* remains a valid pointer to the
+ to :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`. If the request fails,
+ :c:func:`PyMem_Realloc` returns *NULL* and *p* remains a valid pointer to the
previous memory area.
-.. cfunction:: void PyMem_Free(void *p)
+.. c:function:: void PyMem_Free(void *p)
Frees the memory block pointed to by *p*, which must have been returned by a
- previous call to :cfunc:`PyMem_Malloc` or :cfunc:`PyMem_Realloc`. Otherwise, or
- if :cfunc:`PyMem_Free(p)` has been called before, undefined behavior occurs. If
+ previous call to :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`. Otherwise, or
+ if :c:func:`PyMem_Free(p)` has been called before, undefined behavior occurs. If
*p* is *NULL*, no operation is performed.
The following type-oriented macros are provided for convenience. Note that
*TYPE* refers to any C type.
-.. cfunction:: TYPE* PyMem_New(TYPE, size_t n)
+.. c:function:: TYPE* PyMem_New(TYPE, size_t n)
- Same as :cfunc:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of
- memory. Returns a pointer cast to :ctype:`TYPE\*`. The memory will not have
+ Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of
+ memory. Returns a pointer cast to :c:type:`TYPE\*`. The memory will not have
been initialized in any way.
-.. cfunction:: TYPE* PyMem_Resize(void *p, TYPE, size_t n)
+.. c:function:: TYPE* PyMem_Resize(void *p, TYPE, size_t n)
- Same as :cfunc:`PyMem_Realloc`, but the memory block is resized to ``(n *
- sizeof(TYPE))`` bytes. Returns a pointer cast to :ctype:`TYPE\*`. On return,
+ Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n *
+ sizeof(TYPE))`` bytes. Returns a pointer cast to :c:type:`TYPE\*`. On return,
*p* will be a pointer to the new memory area, or *NULL* in the event of
failure. This is a C preprocessor macro; p is always reassigned. Save
the original value of p to avoid losing memory when handling errors.
-.. cfunction:: void PyMem_Del(void *p)
+.. c:function:: void PyMem_Del(void *p)
- Same as :cfunc:`PyMem_Free`.
+ Same as :c:func:`PyMem_Free`.
In addition, the following macro sets are provided for calling the Python memory
allocator directly, without involving the C API functions listed above. However,
note that their use does not preserve binary compatibility across Python
versions and is therefore deprecated in extension modules.
-:cfunc:`PyMem_MALLOC`, :cfunc:`PyMem_REALLOC`, :cfunc:`PyMem_FREE`.
+:c:func:`PyMem_MALLOC`, :c:func:`PyMem_REALLOC`, :c:func:`PyMem_FREE`.
-:cfunc:`PyMem_NEW`, :cfunc:`PyMem_RESIZE`, :cfunc:`PyMem_DEL`.
+:c:func:`PyMem_NEW`, :c:func:`PyMem_RESIZE`, :c:func:`PyMem_DEL`.
.. _memoryexamples:
@@ -201,8 +201,8 @@ allocators operating on different heaps. ::
free(buf1); /* Fatal -- should be PyMem_Del() */
In addition to the functions aimed at handling raw memory blocks from the Python
-heap, objects in Python are allocated and released with :cfunc:`PyObject_New`,
-:cfunc:`PyObject_NewVar` and :cfunc:`PyObject_Del`.
+heap, objects in Python are allocated and released with :c:func:`PyObject_New`,
+:c:func:`PyObject_NewVar` and :c:func:`PyObject_Del`.
These will be explained in the next chapter on defining and implementing new
object types in C.