Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit b173f78

Browse files
benjaminpbenjaminp
committed
add a replacement API for PyCObject, PyCapsule #5630
All stdlib modules with C-APIs now use this. Patch by Larry Hastings
1 parent c679fd8 commit b173f78

37 files changed

Lines changed: 943 additions & 149 deletions

‎Doc/c-api/capsule.rst‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
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+
.. cfunction:: PyObject* PyCapsule_New(void* pointer, const char* name, PyCapsule_Destructor destructor)
37+
38+
Create a :ctype:`PyCapsule` encapsulating the *pointer*. The *pointer*
39+
argument may not be *NULL*.
40+
41+
The *name* string may either be *NULL* or a pointer to a valid
42+
C string. If non-*NULL*, this string must outlive the capsule.
43+
(Though it is permitted to free it inside the *destructor*.)
44+
45+
If the *destructor* argument is not *NULL*,
46+
it will be called with the capsule ``PyObject *`` when it is destroyed.
47+
48+
If this capsule will be stored as an attribute of a module, it
49+
is strongly suggested that the *name* string be specified as::
50+
51+
modulename.attributename
52+
53+
This will enable other modules to import the capsule
54+
using :cfunc:`PyCapsule_Import`.
55+
56+
Return a valid capsule on success.
57+
On failure, set an exception and return *NULL*.
58+
59+
60+
.. cfunction:: void* PyCapsule_GetPointer(PyObject* capsule, const char* name)
61+
62+
Retrieve the *pointer* stored in the capsule.
63+
64+
The *name* parameter must compare exactly to the name stored in the capsule.
65+
If the name stored in the capsule is *NULL*, the *name* passed in must
66+
also be *NULL*. If the name stored in the capsule is non-*NULL*,
67+
the *name* passed in must also be non-*NULL*, and must match the name
68+
stored in the capsule. Python uses the C function *strcmp* to compare
69+
capsule names.
70+
71+
Return the internal *pointer* on success.
72+
On failure, set an exception and return *NULL*.
73+
74+
75+
.. cfunction:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject* capsule)
76+
77+
Return the current *destructor* stored in the capsule.
78+
On failure, set an exception and return *NULL*.
79+
80+
It is legal for a capsule to have a *NULL* destructor.
81+
This makes a *NULL* return code somewhat ambiguous;
82+
use :cfunc:`PyCapsule_IsValid` or :cfunc:`PyErr_Occurred` to disambugate.
83+
84+
85+
.. cfunction:: void* PyCapsule_GetContext(PyObject* capsule)
86+
87+
Return the current *context* stored in the capsule.
88+
On failure, set an exception and return *NULL*.
89+
90+
It is legal for a capsule to have a *NULL* context.
91+
This makes a *NULL* return code somewhat ambiguous;
92+
use :cfunc:`PyCapsule_IsValid` or :cfunc:`PyErr_Occurred` to disambugate.
93+
94+
95+
.. cfunction:: const char* PyCapsule_GetName(PyObject* capsule)
96+
97+
Return the current *name* stored in the capsule.
98+
On failure, set an exception and return *NULL*.
99+
100+
It is legal for a capsule to have a *NULL* name.
101+
This makes a *NULL* return code somewhat ambiguous;
102+
use :cfunc:`PyCapsule_IsValid` or :cfunc:`PyErr_Occurred` to disambugate.
103+
104+
105+
.. cfunction:: void* PyCapsule_Import(const char* name, int no_block)
106+
107+
Import a pointer to a C object from a ``capsule`` attribute in a module.
108+
The *name* parameter should specify the full name to the attribute, as
109+
in *"module.attribute"*.
110+
The *name* stored in the capsule must match this string exactly.
111+
If *no_block* is true, import the module without blocking
112+
(using :cfunc:`PyImport_ImportModuleNoBlock`).
113+
If *no_block* is false, import the module conventionally
114+
(using :cfunc:`PyImport_ImportModule`).
115+
116+
Return the capsule's internal *pointer* on success.
117+
On failure, set an exception and return *NULL*.
118+
Exception: if *PyCapsule_Import* failed to import the module,
119+
and *no_block* was true, no exception is set.
120+
121+
.. cfunction:: int PyCapsule_IsValid(PyObject* capsule, const char* name)
122+
123+
Determines whether or not a :ctype:`PyObject \*` is a valid capsule.
124+
A valid capsule is non-*NULL*, passes :cfunc:`PyCapsule_CheckExact`,
125+
has a non-NULL *pointer*, and its internal name matches the
126+
*name* parameter. (See :cfunc:`PyCapsule_GetPointer` for
127+
information on how capsule names are compared.)
128+
129+
In other words, if :cfunc:`PyCapsule_IsValid` returns a true value,
130+
calls to any of the accessors (any function starting
131+
with :cfunc:`PyCapsule_Get`) are guaranteed to succeed.
132+
133+
Return a nonzero value if the object is valid and matches the name
134+
passed in.
135+
Return 0 otherwise.
136+
This function will not fail.
137+
138+
.. cfunction:: int PyCapsule_SetContext(PyObject* capsule, void* context)
139+
140+
Set the context pointer inside *capsule* to *context*.
141+
142+
Return 0 on success.
143+
Return nonzero and set an exception on failure.
144+
145+
.. cfunction:: int PyCapsule_SetDestructor(PyObject* capsule, void (*)(PyObject *) destructor)
146+
147+
Set the destructor inside *capsule* to *destructor*.
148+
149+
Return 0 on success.
150+
Return nonzero and set an exception on failure.
151+
152+
.. cfunction:: int PyCapsule_SetName(PyObject* capsule, const char* name)
153+
154+
Set the name inside *capsule* to *name*. If non-*NULL*, the name
155+
must outlive the capsule. If the previous *name* stored in the
156+
capsule was not *NULL*, no attempt is made to free it.
157+
158+
Return 0 on success.
159+
Return nonzero and set an exception on failure.
160+
161+
.. cfunction:: int PyCapsule_SetPointer(PyObject* capsule, void* pointer)
162+
163+
Set the void pointer inside *capsule* to *pointer*. The pointer
164+
may not be *NULL*.
165+
166+
Return 0 on success.
167+
Return nonzero and set an exception on failure.
168+

‎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 3.1. 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
@@ -101,6 +101,7 @@ Other Objects
101101
descriptor.rst
102102
slice.rst
103103
weakref.rst
104+
capsule.rst
104105
cobject.rst
105106
cell.rst
106107
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 & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1075,7 +1075,7 @@ already if the symbol ``__cplusplus`` is defined (all recent C++ compilers
10751075
define this symbol).
10761076

10771077

1078-
.. _using-cobjects:
1078+
.. _using-capsules:
10791079

10801080
Providing a C API for an Extension Module
10811081
=========================================
@@ -1111,23 +1111,40 @@ avoid name clashes with other extension modules (as discussed in section
11111111
other extension modules must be exported in a different way.
11121112

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

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

1127+
Whichever method you choose, it's important to name your Capsules properly.
1128+
The function :cfunc:`PyCapsule_New` takes a name parameter
1129+
(:ctype:`const char \*`); you're permitted to pass in a *NULL* name, but
1130+
we strongly encourage you to specify a name. Properly named Capsules provide
1131+
a degree of runtime type-safety; there is no feasible way to tell one unnamed
1132+
Capsule from another.
1133+
1134+
In particular, Capsules used to expose C APIs should be given a name following
1135+
this convention::
1136+
1137+
modulename.attributename
1138+
1139+
The convenience function :cfunc:`PyCapsule_Import` makes it easy to
1140+
load a C API provided via a Capsule, but only if the Capsule's name
1141+
matches this convention. This behavior gives C API users a high degree
1142+
of certainty that the Capsule they load contains the correct C API.
1143+
11271144
The following example demonstrates an approach that puts most of the burden on
11281145
the writer of the exporting module, which is appropriate for commonly used
11291146
library modules. It stores all C API pointers (just one in the example!) in an
1130-
array of :ctype:`void` pointers which becomes the value of a CObject. The header
1147+
array of :ctype:`void` pointers which becomes the value of a Capsule. The header
11311148
file corresponding to the module provides a macro that takes care of importing
11321149
the module and retrieving its C API pointers; client modules only have to call
11331150
this macro before accessing the C API.
@@ -1189,8 +1206,8 @@ function must take care of initializing the C API pointer array::
11891206
/* Initialize the C API pointer array */
11901207
PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;
11911208

1192-
/* Create a CObject containing the API pointer array's address */
1193-
c_api_object = PyCObject_FromVoidPtr((void *)PySpam_API, NULL);
1209+
/* Create a Capsule containing the API pointer array's address */
1210+
c_api_object = PyCapsule_New((void *)PySpam_API, "spam._C_API", NULL);
11941211

11951212
if (c_api_object != NULL)
11961213
PyModule_AddObject(m, "_C_API", c_api_object);
@@ -1233,21 +1250,14 @@ like this::
12331250
#define PySpam_System \
12341251
(*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])
12351252

1236-
/* Return -1 and set exception on error, 0 on success. */
1253+
/* Return -1 on error, 0 on success.
1254+
* PyCapsule_Import will set an exception if there's an error.
1255+
*/
12371256
static int
12381257
import_spam(void)
12391258
{
1240-
PyObject *module = PyImport_ImportModule("spam");
1241-
1242-
if (module != NULL) {
1243-
PyObject *c_api_object = PyObject_GetAttrString(module, "_C_API");
1244-
if (c_api_object == NULL)
1245-
return -1;
1246-
if (PyCObject_Check(c_api_object))
1247-
PySpam_API = (void **)PyCObject_AsVoidPtr(c_api_object);
1248-
Py_DECREF(c_api_object);
1249-
}
1250-
return 0;
1259+
PySpam_API = (void **)PyCapsule_Import("spam._C_API", 0);
1260+
return (PySpam_API != NULL) ? 0 : -1;
12511261
}
12521262

12531263
#endif
@@ -1280,11 +1290,11 @@ The main disadvantage of this approach is that the file :file:`spammodule.h` is
12801290
rather complicated. However, the basic structure is the same for each function
12811291
that is exported, so it has to be learned only once.
12821292

1283-
Finally it should be mentioned that CObjects offer additional functionality,
1293+
Finally it should be mentioned that Capsules offer additional functionality,
12841294
which is especially useful for memory allocation and deallocation of the pointer
1285-
stored in a CObject. The details are described in the Python/C API Reference
1286-
Manual in the section :ref:`cobjects` and in the implementation of CObjects (files
1287-
:file:`Include/cobject.h` and :file:`Objects/cobject.c` in the Python source
1295+
stored in a Capsule. The details are described in the Python/C API Reference
1296+
Manual in the section :ref:`capsules` and in the implementation of Capsules (files
1297+
:file:`Include/pycapsule.h` and :file:`Objects/pycapsule.c` in the Python source
12881298
code distribution).
12891299

12901300
.. rubric:: Footnotes

‎Include/Python.h‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,7 @@
8989
#include "classobject.h"
9090
#include "fileobject.h"
9191
#include "cobject.h"
92+
#include "pycapsule.h"
9293
#include "traceback.h"
9394
#include "sliceobject.h"
9495
#include "cellobject.h"

‎Include/cobject.h‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,8 @@
11

2-
/* C objects to be exported from one extension module to another.
2+
/*
33
4-
C objects are used for communication between extension modules.
5-
They provide a way for an extension module to export a C interface
6-
to other extension modules, so that extension modules can use the
7-
Python import mechanism to link to one another.
4+
The CObject module is now *deprecated* as of Python 3.1.
5+
Please use the Capsule API instead; see "pycapsule.h".
86
97
*/
108

‎Include/datetime.h‎

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

159159
} PyDateTime_CAPI;
160160

161+
#define PyDateTime_CAPSULE_NAME "datetime.datetime_CAPI"
161162

162-
/* "magic" constant used to partially protect against developer mistakes. */
163-
#define DATETIME_API_MAGIC 0x414548d5
164163

165164
#ifdef Py_BUILD_CORE
166165

@@ -186,15 +185,7 @@ typedef struct {
186185
static PyDateTime_CAPI *PyDateTimeAPI;
187186

188187
#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-
*/
188+
PyDateTimeAPI = (PyDateTime_CAPI *)PyCapsule_Import(PyDateTime_CAPSULE_NAME, 0)
198189

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

0 commit comments

Comments
 (0)