diff --git a/pep-3123.txt b/pep-3123.txt index 1946e1e6e..ae9856e2d 100644 --- a/pep-3123.txt +++ b/pep-3123.txt @@ -14,7 +14,7 @@ Abstract ======== Python currently relies on undefined C behavior, with its -usage of PyObject_HEAD. This PEP proposes to change that +usage of ``PyObject_HEAD``. This PEP proposes to change that into standard C. Rationale @@ -43,18 +43,18 @@ code has undefined behavior:: } The problem here is that the storage is both accessed as -if it where struct PyObject, and as struct FooObject. +if it where struct ``PyObject``, and as struct ``FooObject``. Historically, compilers did not have any problems with this code. However, modern compilers use that clause as an -optimization opportunity, finding that f->ob_refcnt and -o->ob_refcnt cannot possibly refer to the same memory, and +optimization opportunity, finding that ``f->ob_refcnt`` and +``o->ob_refcnt`` cannot possibly refer to the same memory, and that therefore the function should return 0, without having to fetch the value of ob_refcnt at all in the return -statement. For GCC, Python now uses -fno-strict-aliasing +statement. For GCC, Python now uses ``-fno-strict-aliasing`` to work around that problem; with other compilers, it may just see undefined behavior. Even with GCC, using --fno-strict-aliasing may pessimize the generated code +``-fno-strict-aliasing`` may pessimize the generated code unnecessarily. Specification @@ -63,12 +63,12 @@ Specification Standard C has one specific exception to its aliasing rules precisely designed to support the case of Python: a value of a struct type may also be accessed through a pointer to the first field. E.g. if a -struct starts with an int, the struct\* may also be cast to an int\*, -allowing to write int values into the first field. +struct starts with an ``int``, the ``struct *`` may also be cast to +an ``int *``, allowing to write int values into the first field. -For Python, PyObject_HEAD and PyObject_VAR_HEAD will be changed +For Python, ``PyObject_HEAD`` and ``PyObject_VAR_HEAD`` will be changed to not list all fields anymore, but list a single field of type -PyObject/PyVarObject:: +``PyObject``/``PyVarObject``:: typedef struct _object { _PyObject_HEAD_EXTRA @@ -92,14 +92,14 @@ as its first field; variable-sized objects PyVarObject. E.g.:: PyObject *start, *stop, *step; } PySliceObject; - typedef struct{ + typedef struct { PyVarObject ob_base; PyObject **ob_item; Py_ssize_t allocated; } PyListObject; -The above definitions of PyObject_HEAD is normative, so extension -authors MAY either use the macro, or put the ob_base field explicitly +The above definitions of ``PyObject_HEAD`` are normative, so extension +authors MAY either use the macro, or put the ``ob_base`` field explicitly into their structs. As a convention, the base field SHOULD be called ob_base. However, all @@ -112,7 +112,7 @@ ob_type, ob_refcnt, and ob_size, macros:: #define Py_Refcnt(o) (((PyObject*)(o))->ob_refcnt) #define Py_Size(o) (((PyVarObject*)(o))->ob_size) -are added. E.g. the code blocks:: +are added. E.g. the code blocks :: #define PyList_CheckExact(op) ((op)->ob_type == &PyList_Type) @@ -124,12 +124,12 @@ needs to be changed to:: return Py_Type(func)->tp_name; -For initialization of type objects, the current sequence:: +For initialization of type objects, the current sequence :: PyObject_HEAD_INIT(NULL) 0, /* ob_size */ -becomes incorrect, and must be replaced with +becomes incorrect, and must be replaced with :: PyVarObject_HEAD_INIT(NULL, 0) @@ -137,9 +137,9 @@ Compatibility with Python 2.6 ============================= To support modules that compile with both Python 2.6 and Python 3.0, -the Py_* macros is added to Python 2.6. The macros Py_INCREF -and Py_DECREF will be changed to cast their argument to PyObject\*, -so that module authors can also explicitly declare the ob_base +the ``Py_*`` macros are added to Python 2.6. The macros ``Py_INCREF`` +and ``Py_DECREF`` will be changed to cast their argument to ``PyObject *``, +so that module authors can also explicitly declare the ``ob_base`` field in modules designed for Python 2.6. Copyright