[Python-checkins] cpython (merge 3.3 -> default): Closing #18668: Properly document setting m_size in PyModuleDef
eli.bendersky
python-checkins at python.org
Wed Aug 7 14:54:59 CEST 2013
http://hg.python.org/cpython/rev/9877c25d9556
changeset: 85062:9877c25d9556
parent: 85060:89ce323357db
parent: 85061:698fd628b001
user: Eli Bendersky <eliben at gmail.com>
date: Wed Aug 07 05:54:28 2013 -0700
summary:
Closing #18668: Properly document setting m_size in PyModuleDef
files:
Doc/c-api/module.rst | 14 ++++++++++----
1 files changed, 10 insertions(+), 4 deletions(-)
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -189,16 +189,22 @@
.. c:member:: Py_ssize_t m_size
- If the module object needs additional memory, this should be set to the
- number of bytes to allocate; a pointer to the block of memory can be
- retrieved with :c:func:`PyModule_GetState`. If no memory is needed, set
- this to ``-1``.
+ Some modules allow re-initialization (calling their ``PyInit_*`` function
+ more than once). These modules should keep their state in a per-module
+ memory area that can be retrieved with :c:func:`PyModule_GetState`.
This memory should be used, rather than static globals, to hold per-module
state, since it is then safe for use in multiple sub-interpreters. It is
freed when the module object is deallocated, after the :c:member:`m_free`
function has been called, if present.
+ Setting ``m_size`` to a positive value specifies the size of the additional
+ memory required by the module. Setting it to ``-1`` means that the module can
+ not be re-initialized because it has global state. Setting it to ``0`` is
+ forbidden.
+
+ See :PEP:`3121` for more details.
+
.. c:member:: PyMethodDef* m_methods
A pointer to a table of module-level functions, described by
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list