Add opaque_pyobject.rst

doc/index.rst

@@ -62,6 +62,7 @@ Pages
    deprecate
    python_ir
    runtime
+   opaque_pyobject
 
 
 Links
@@ -101,11 +102,12 @@ Table of Contents
    cpyext
    cython
    cffi
+   gilectomy
    remove_c_api
    performance
    split_include
    pyhandle
    deprecate
    python_ir
    runtime
-
+   opaque_pyobject

doc/opaque_pyobject.rst

@@ -0,0 +1,34 @@
+=========================
+Opaque PyObject structure
+=========================
+
+A blocker issue for many :ref:`optimization ideas <optim-ideas>` is that the
+``PyObject`` structure fields are exposed in the public C API. Example::
+
+    PyObject *
+    PyUnicode_FromObject(PyObject *obj)
+    {
+        ...
+        PyErr_Format(PyExc_TypeError,
+                     "Can't convert '%.100s' object to str implicitly",
+                     Py_TYPE(obj)->tp_name);
+        return NULL;
+    }
+
+with::
+
+    #define Py_TYPE(ob)           (_PyObject_CAST(ob)->ob_type)
+    #define _PyObject_CAST(op)    ((PyObject*)(op))
+
+The issue is that ``obj->ob_type`` is accessed directly. It prevents to
+implement :ref:`Tagged pointers <tagged-pointer>` for example.
+
+By the way, ``Py_TYPE()`` returns a :ref:`borrowed reference <borrowed-ref>`
+which is another kind of problem.
+
+In the long term, ``PyObject`` structure should be opaque. Accessing
+``ob_refcnt`` and ``ob_type`` fields should always go through functions.
+
+XXX which functions?
+
+XXX how to convert old code to these new functions?