Skip to content

Commit 402b73f

Browse files
larryhastingslarryhastings
committed
Backported PyCapsule from 3.1, and converted most uses of
CObject to PyCapsule.
1 parent 53ff86e commit 402b73f

40 files changed

+1048
-127
lines changed

‎Doc/c-api/capsule.rst‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
.. highlightlang:: c
2+
3+
.. _capsules:
4+
5+
Capsules
6+
--------
7+
8+
.. index:: object: Capsule
9+
10+
Refer to :ref:`using-capsules` for more information on using these objects.
11+
12+
13+
.. ctype:: PyCapsule
14+
15+
This subtype of :ctype:`PyObject` represents an opaque value, useful for C
16+
extension modules who need to pass an opaque value (as a :ctype:`void\*`
17+
pointer) through Python code to other C code. It is often used to make a C
18+
function pointer defined in one module available to other modules, so the
19+
regular import mechanism can be used to access C APIs defined in dynamically
20+
loaded modules.
21+
22+
.. ctype:: PyCapsule_Destructor
23+
24+
The type of a destructor callback for a capsule. Defined as::
25+
26+
typedef void (*PyCapsule_Destructor)(PyObject *);
27+
28+
See :cfunc:`PyCapsule_New` for the semantics of PyCapsule_Destructor
29+
callbacks.
30+
31+
32+
.. cfunction:: int PyCapsule_CheckExact(PyObject *p)
33+
34+
Return true if its argument is a :ctype:`PyCapsule`.
35+
36+
37+
.. cfunction:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
38+
39+
Create a :ctype:`PyCapsule` encapsulating the *pointer*. The *pointer*
40+
argument may not be *NULL*.
41+
42+
On failure, set an exception and return *NULL*.
43+
44+
The *name* string may either be *NULL* or a pointer to a valid C string. If
45+
non-*NULL*, this string must outlive the capsule. (Though it is permitted to
46+
free it inside the *destructor*.)
47+
48+
If the *destructor* argument is not *NULL*, it will be called with the
49+
capsule as its argument when it is destroyed.
50+
51+
If this capsule will be stored as an attribute of a module, the *name* should
52+
be specified as ``modulename.attributename``. This will enable other modules
53+
to import the capsule using :cfunc:`PyCapsule_Import`.
54+
55+
56+
.. cfunction:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name)
57+
58+
Retrieve the *pointer* stored in the capsule. On failure, set an exception
59+
and return *NULL*.
60+
61+
The *name* parameter must compare exactly to the name stored in the capsule.
62+
If the name stored in the capsule is *NULL*, the *name* passed in must also
63+
be *NULL*. Python uses the C function :cfunc:`strcmp` to compare capsule
64+
names.
65+
66+
67+
.. cfunction:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
68+
69+
Return the current destructor stored in the capsule. On failure, set an
70+
exception and return *NULL*.
71+
72+
It is legal for a capsule to have a *NULL* destructor. This makes a *NULL*
73+
return code somewhat ambiguous; use :cfunc:`PyCapsule_IsValid` or
74+
:cfunc:`PyErr_Occurred` to disambiguate.
75+
76+
77+
.. cfunction:: void* PyCapsule_GetContext(PyObject *capsule)
78+
79+
Return the current context stored in the capsule. On failure, set an
80+
exception and return *NULL*.
81+
82+
It is legal for a capsule to have a *NULL* context. This makes a *NULL*
83+
return code somewhat ambiguous; use :cfunc:`PyCapsule_IsValid` or
84+
:cfunc:`PyErr_Occurred` to disambiguate.
85+
86+
87+
.. cfunction:: const char* PyCapsule_GetName(PyObject *capsule)
88+
89+
Return the current name stored in the capsule. On failure, set an exception
90+
and return *NULL*.
91+
92+
It is legal for a capsule to have a *NULL* name. This makes a *NULL* return
93+
code somewhat ambiguous; use :cfunc:`PyCapsule_IsValid` or
94+
:cfunc:`PyErr_Occurred` to disambiguate.
95+
96+
97+
.. cfunction:: void* PyCapsule_Import(const char *name, int no_block)
98+
99+
Import a pointer to a C object from a capsule attribute in a module. The
100+
*name* parameter should specify the full name to the attribute, as in
101+
``module.attribute``. The *name* stored in the capsule must match this
102+
string exactly. If *no_block* is true, import the module without blocking
103+
(using :cfunc:`PyImport_ImportModuleNoBlock`). If *no_block* is false,
104+
import the module conventionally (using :cfunc:`PyImport_ImportModule`).
105+
106+
Return the capsule's internal *pointer* on success. On failure, set an
107+
exception and return *NULL*. However, if :cfunc:`PyCapsule_Import` failed to
108+
import the module, and *no_block* was true, no exception is set.
109+
110+
.. cfunction:: int PyCapsule_IsValid(PyObject *capsule, const char *name)
111+
112+
Determines whether or not *capsule* is a valid capsule. A valid capsule is
113+
non-*NULL*, passes :cfunc:`PyCapsule_CheckExact`, has a non-*NULL* pointer
114+
stored in it, and its internal name matches the *name* parameter. (See
115+
:cfunc:`PyCapsule_GetPointer` for information on how capsule names are
116+
compared.)
117+
118+
In other words, if :cfunc:`PyCapsule_IsValid` returns a true value, calls to
119+
any of the accessors (any function starting with :cfunc:`PyCapsule_Get`) are
120+
guaranteed to succeed.
121+
122+
Return a nonzero value if the object is valid and matches the name passed in.
123+
Return 0 otherwise. This function will not fail.
124+
125+
.. cfunction:: int PyCapsule_SetContext(PyObject *capsule, void *context)
126+
127+
Set the context pointer inside *capsule* to *context*.
128+
129+
Return 0 on success. Return nonzero and set an exception on failure.
130+
131+
.. cfunction:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
132+
133+
Set the destructor inside *capsule* to *destructor*.
134+
135+
Return 0 on success. Return nonzero and set an exception on failure.
136+
137+
.. cfunction:: int PyCapsule_SetName(PyObject *capsule, const char *name)
138+
139+
Set the name inside *capsule* to *name*. If non-*NULL*, the name must
140+
outlive the capsule. If the previous *name* stored in the capsule was not
141+
*NULL*, no attempt is made to free it.
142+
143+
Return 0 on success. Return nonzero and set an exception on failure.
144+
145+
.. cfunction:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
146+
147+
Set the void pointer inside *capsule* to *pointer*. The pointer may not be
148+
*NULL*.
149+
150+
Return 0 on success. Return nonzero and set an exception on failure.

‎Doc/c-api/cobject.rst‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,11 @@ CObjects
77

88
.. index:: object: CObject
99

10-
Refer to :ref:`using-cobjects` for more information on using these objects.
1110

11+
.. warning::
12+
13+
The CObject API is deprecated as of Python 2.7. Please switch to the new
14+
:ref:`capsules` API.
1215

1316
.. ctype:: PyCObject
1417

‎Doc/c-api/concrete.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,7 @@ Other Objects
100100
descriptor.rst
101101
slice.rst
102102
weakref.rst
103+
capsule.rst
103104
cobject.rst
104105
cell.rst
105106
gen.rst

‎Doc/data/refcounts.dat‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,45 @@ PyBuffer_FromReadWriteMemory:int:size::
5555
PyBuffer_New:PyObject*::+1:
5656
PyBuffer_New:int:size::
5757

58+
PyCapsule_GetContext:void *:::
59+
PyCapsule_GetContext:PyObject*:self:0:
60+
61+
PyCapsule_GetDestructor:void (*)(PyObject *):::
62+
PyCapsule_GetDestructor:PyObject*:self:0:
63+
64+
PyCapsule_GetName:const char *:::
65+
PyCapsule_GetName:PyObject*:self:0:
66+
67+
PyCapsule_GetPointer:void*:::
68+
PyCapsule_GetPointer:PyObject*:self:0:
69+
PyCapsule_GetPointer:const char *:name::
70+
71+
PyCapsule_Import:void *:::
72+
PyCapsule_Import:const char *:name::
73+
PyCapsule_Import:int:no_block::
74+
75+
PyCapsule_New:PyObject*::+1:
76+
PyCapsule_New:void*:pointer::
77+
PyCapsule_New:const char *:name::
78+
PyCapsule_New::void (* destructor)(PyObject* )::
79+
80+
PyCapsule_SetContext:int:::
81+
PyCapsule_SetContext:PyObject*:self:0:
82+
PyCapsule_SetContext:void *:context::
83+
84+
PyCapsule_SetDestructor:int:::
85+
PyCapsule_SetDestructor:PyObject*:self:0:
86+
PyCapsule_SetDestructor:void (*)(PyObject *):destructor::
87+
88+
PyCapsule_SetName:int:::
89+
PyCapsule_SetName:PyObject*:self:0:
90+
PyCapsule_SetName:const char *:name::
91+
92+
PyCapsule_SetPointer:int:::
93+
PyCapsule_SetPointer:PyObject*:self:0:
94+
PyCapsule_SetPointer:void*:pointer::
95+
96+
5897
PyCObject_AsVoidPtr:void*:::
5998
PyCObject_AsVoidPtr:PyObject*:self:0:
6099

‎Doc/extending/extending.rst‎

Lines changed: 36 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1060,7 +1060,7 @@ already if the symbol ``__cplusplus`` is defined (all recent C++ compilers
10601060
define this symbol).
10611061

10621062

1063-
.. _using-cobjects:
1063+
.. _using-capsules:
10641064

10651065
Providing a C API for an Extension Module
10661066
=========================================
@@ -1096,23 +1096,40 @@ avoid name clashes with other extension modules (as discussed in section
10961096
other extension modules must be exported in a different way.
10971097

10981098
Python provides a special mechanism to pass C-level information (pointers) from
1099-
one extension module to another one: CObjects. A CObject is a Python data type
1100-
which stores a pointer (:ctype:`void \*`). CObjects can only be created and
1099+
one extension module to another one: Capsules. A Capsule is a Python data type
1100+
which stores a pointer (:ctype:`void \*`). Capsules can only be created and
11011101
accessed via their C API, but they can be passed around like any other Python
11021102
object. In particular, they can be assigned to a name in an extension module's
11031103
namespace. Other extension modules can then import this module, retrieve the
1104-
value of this name, and then retrieve the pointer from the CObject.
1104+
value of this name, and then retrieve the pointer from the Capsule.
11051105

1106-
There are many ways in which CObjects can be used to export the C API of an
1107-
extension module. Each name could get its own CObject, or all C API pointers
1108-
could be stored in an array whose address is published in a CObject. And the
1106+
There are many ways in which Capsules can be used to export the C API of an
1107+
extension module. Each function could get its own Capsule, or all C API pointers
1108+
could be stored in an array whose address is published in a Capsule. And the
11091109
various tasks of storing and retrieving the pointers can be distributed in
11101110
different ways between the module providing the code and the client modules.
11111111

1112+
Whichever method you choose, it's important to name your Capsules properly.
1113+
The function :cfunc:`PyCapsule_New` takes a name parameter
1114+
(:ctype:`const char \*`); you're permitted to pass in a *NULL* name, but
1115+
we strongly encourage you to specify a name. Properly named Capsules provide
1116+
a degree of runtime type-safety; there is no feasible way to tell one unnamed
1117+
Capsule from another.
1118+
1119+
In particular, Capsules used to expose C APIs should be given a name following
1120+
this convention::
1121+
1122+
modulename.attributename
1123+
1124+
The convenience function :cfunc:`PyCapsule_Import` makes it easy to
1125+
load a C API provided via a Capsule, but only if the Capsule's name
1126+
matches this convention. This behavior gives C API users a high degree
1127+
of certainty that the Capsule they load contains the correct C API.
1128+
11121129
The following example demonstrates an approach that puts most of the burden on
11131130
the writer of the exporting module, which is appropriate for commonly used
11141131
library modules. It stores all C API pointers (just one in the example!) in an
1115-
array of :ctype:`void` pointers which becomes the value of a CObject. The header
1132+
array of :ctype:`void` pointers which becomes the value of a Capsule. The header
11161133
file corresponding to the module provides a macro that takes care of importing
11171134
the module and retrieving its C API pointers; client modules only have to call
11181135
this macro before accessing the C API.
@@ -1174,8 +1191,8 @@ function must take care of initializing the C API pointer array::
11741191
/* Initialize the C API pointer array */
11751192
PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;
11761193

1177-
/* Create a CObject containing the API pointer array's address */
1178-
c_api_object = PyCObject_FromVoidPtr((void *)PySpam_API, NULL);
1194+
/* Create a Capsule containing the API pointer array's address */
1195+
c_api_object = PyCapsule_New((void *)PySpam_API, "spam._C_API", NULL);
11791196

11801197
if (c_api_object != NULL)
11811198
PyModule_AddObject(m, "_C_API", c_api_object);
@@ -1217,28 +1234,14 @@ like this::
12171234
#define PySpam_System \
12181235
(*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])
12191236

1220-
/* Return -1 and set exception on error, 0 on success. */
1237+
/* Return -1 on error, 0 on success.
1238+
* PyCapsule_Import will set an exception if there's an error.
1239+
*/
12211240
static int
12221241
import_spam(void)
12231242
{
1224-
PyObject *c_api_object;
1225-
PyObject *module;
1226-
1227-
module = PyImport_ImportModule("spam");
1228-
if (module == NULL)
1229-
return -1;
1230-
1231-
c_api_object = PyObject_GetAttrString(module, "_C_API");
1232-
if (c_api_object == NULL) {
1233-
Py_DECREF(module);
1234-
return -1;
1235-
}
1236-
if (PyCObject_Check(c_api_object))
1237-
PySpam_API = (void **)PyCObject_AsVoidPtr(c_api_object);
1238-
1239-
Py_DECREF(c_api_object);
1240-
Py_DECREF(module);
1241-
return 0;
1243+
PySpam_API = (void **)PyCapsule_Import("spam._C_API", 0);
1244+
return (PySpam_API != NULL) ? 0 : -1;
12421245
}
12431246

12441247
#endif
@@ -1270,11 +1273,11 @@ The main disadvantage of this approach is that the file :file:`spammodule.h` is
12701273
rather complicated. However, the basic structure is the same for each function
12711274
that is exported, so it has to be learned only once.
12721275

1273-
Finally it should be mentioned that CObjects offer additional functionality,
1276+
Finally it should be mentioned that Capsules offer additional functionality,
12741277
which is especially useful for memory allocation and deallocation of the pointer
1275-
stored in a CObject. The details are described in the Python/C API Reference
1276-
Manual in the section :ref:`cobjects` and in the implementation of CObjects (files
1277-
:file:`Include/cobject.h` and :file:`Objects/cobject.c` in the Python source
1278+
stored in a Capsule. The details are described in the Python/C API Reference
1279+
Manual in the section :ref:`capsules` and in the implementation of Capsules (files
1280+
:file:`Include/pycapsule.h` and :file:`Objects/pycapsule.c` in the Python source
12781281
code distribution).
12791282

12801283
.. rubric:: Footnotes

‎Include/Python.h‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,7 @@
107107
#include "classobject.h"
108108
#include "fileobject.h"
109109
#include "cobject.h"
110+
#include "pycapsule.h"
110111
#include "traceback.h"
111112
#include "sliceobject.h"
112113
#include "cellobject.h"

‎Include/cStringIO.h‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,12 @@ extern "C" {
1818
This would typically be done in your init function.
1919
2020
*/
21+
22+
#define PycStringIO_CAPSULE_NAME "cStringIO.cStringIO_CAPI"
23+
2124
#define PycString_IMPORT \
22-
PycStringIO = (struct PycStringIO_CAPI*)PyCObject_Import("cStringIO", \
23-
"cStringIO_CAPI")
25+
PycStringIO = ((struct PycStringIO_CAPI*)PyCapsule_Import(\
26+
PycStringIO_CAPSULE_NAME, 0))
2427

2528
/* Basic functions to manipulate cStringIO objects from C */
2629

‎Include/cobject.h‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
to other extension modules, so that extension modules can use the
77
Python import mechanism to link to one another.
88
9+
DEPRECATED - Use PyCapsule objects instead.
10+
CObject will be removed in 2.8 (if there is one).
911
*/
1012

1113
#ifndef Py_COBJECT_H

‎Include/datetime.h‎

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,8 @@ typedef struct {
158158

159159
} PyDateTime_CAPI;
160160

161+
#define PyDateTime_CAPSULE_NAME "datetime.datetime_CAPI"
162+
161163

162164
/* "magic" constant used to partially protect against developer mistakes. */
163165
#define DATETIME_API_MAGIC 0x414548d5
@@ -186,15 +188,7 @@ typedef struct {
186188
static PyDateTime_CAPI *PyDateTimeAPI = NULL;
187189

188190
#define PyDateTime_IMPORT \
189-
PyDateTimeAPI = (PyDateTime_CAPI*) PyCObject_Import("datetime", \
190-
"datetime_CAPI")
191-
192-
/* This macro would be used if PyCObject_ImportEx() was created.
193-
#define PyDateTime_IMPORT \
194-
PyDateTimeAPI = (PyDateTime_CAPI*) PyCObject_ImportEx("datetime", \
195-
"datetime_CAPI", \
196-
DATETIME_API_MAGIC)
197-
*/
191+
PyDateTimeAPI = (PyDateTime_CAPI *)PyCapsule_Import(PyDateTime_CAPSULE_NAME, 0)
198192

199193
/* Macros for type checking when not building the Python core. */
200194
#define PyDate_Check(op) PyObject_TypeCheck(op, PyDateTimeAPI->DateType)

0 commit comments

Comments
 (0)