← Back to branch summary

~ubuntu-branches/ubuntu/trusty/python3.4/trusty-proposed

« back to all changes in this revision

Viewing changes to Doc/c-api/capsule.rst

  • Committer: Package Import Robot
  • Author(s): Matthias Klose
  • Date: 2013-11-25 09:44:27 UTC
  • Revision ID: package-import@ubuntu.com-20131125094427-lzxj8ap5w01lmo7f
Tags: upstream-3.4~b1
Import upstream version 3.4~b1

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/c-api/capsule.rst
 
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
.. c:type:: PyCapsule
 
14
 
 
15
   This subtype of :c:type:`PyObject` represents an opaque value, useful for C
 
16
   extension modules who need to pass an opaque value (as a :c:type:`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
.. c:type:: 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 :c:func:`PyCapsule_New` for the semantics of PyCapsule_Destructor
 
29
   callbacks.
 
30
 
 
31
 
 
32
.. c:function:: int PyCapsule_CheckExact(PyObject *p)
 
33
 
 
34
   Return true if its argument is a :c:type:`PyCapsule`.
 
35
 
 
36
 
 
37
.. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
 
38
 
 
39
   Create a :c:type:`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 :c:func:`PyCapsule_Import`.
 
54
 
 
55
 
 
56
.. c:function:: 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 :c:func:`strcmp` to compare capsule
 
64
   names.
 
65
 
 
66
 
 
67
.. c:function:: 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 :c:func:`PyCapsule_IsValid` or
 
74
   :c:func:`PyErr_Occurred` to disambiguate.
 
75
 
 
76
 
 
77
.. c:function:: 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 :c:func:`PyCapsule_IsValid` or
 
84
   :c:func:`PyErr_Occurred` to disambiguate.
 
85
 
 
86
 
 
87
.. c:function:: 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 :c:func:`PyCapsule_IsValid` or
 
94
   :c:func:`PyErr_Occurred` to disambiguate.
 
95
 
 
96
 
 
97
.. c:function:: 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 :c:func:`PyImport_ImportModuleNoBlock`).  If *no_block* is false,
 
104
   import the module conventionally (using :c:func:`PyImport_ImportModule`).
 
105
 
 
106
   Return the capsule's internal *pointer* on success.  On failure, set an
 
107
   exception and return *NULL*.  However, if :c:func:`PyCapsule_Import` failed to
 
108
   import the module, and *no_block* was true, no exception is set.
 
109
 
 
110
.. c:function:: 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 :c:func:`PyCapsule_CheckExact`, has a non-*NULL* pointer
 
114
   stored in it, and its internal name matches the *name* parameter.  (See
 
115
   :c:func:`PyCapsule_GetPointer` for information on how capsule names are
 
116
   compared.)
 
117
 
 
118
   In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls to
 
119
   any of the accessors (any function starting with :c:func:`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
.. c:function:: 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
.. c:function:: 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
.. c:function:: 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
.. c:function:: 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.