History

add hg and python

cinap_lenrek committed 15 years ago

Commit 4bb9e221 parent 987265c3706 files · +1228772 −-233Browse files

Showing the changes to sys/src/cmd/python/Include/objimpl.h (1 of 3706 files). Show all

Unified · Split

sys/src/cmd/python/Include/objimpl.h+336−0
@@ -0,0 +1,336 @@
1+/* The PyObject_ memory family: high-level object memory interfaces.
2+ See pymem.h for the low-level PyMem_ family.
3+*/
4+
5+#ifndef Py_OBJIMPL_H
6+#define Py_OBJIMPL_H
7+
8+#include "pymem.h"
9+
10+#ifdef __cplusplus
11+extern "C" {
12+#endif
13+
14+/* BEWARE:
15+
16+ Each interface exports both functions and macros. Extension modules should
17+ use the functions, to ensure binary compatibility across Python versions.
18+ Because the Python implementation is free to change internal details, and
19+ the macros may (or may not) expose details for speed, if you do use the
20+ macros you must recompile your extensions with each Python release.
21+
22+ Never mix calls to PyObject_ memory functions with calls to the platform
23+ malloc/realloc/ calloc/free, or with calls to PyMem_.
24+*/
25+
26+/*
27+Functions and macros for modules that implement new object types.
28+
29+ - PyObject_New(type, typeobj) allocates memory for a new object of the given
30+ type, and initializes part of it. 'type' must be the C structure type used
31+ to represent the object, and 'typeobj' the address of the corresponding
32+ type object. Reference count and type pointer are filled in; the rest of
33+ the bytes of the object are *undefined*! The resulting expression type is
34+ 'type *'. The size of the object is determined by the tp_basicsize field
35+ of the type object.
36+
37+ - PyObject_NewVar(type, typeobj, n) is similar but allocates a variable-size
38+ object with room for n items. In addition to the refcount and type pointer
39+ fields, this also fills in the ob_size field.
40+
41+ - PyObject_Del(op) releases the memory allocated for an object. It does not
42+ run a destructor -- it only frees the memory. PyObject_Free is identical.
43+
44+ - PyObject_Init(op, typeobj) and PyObject_InitVar(op, typeobj, n) don't
45+ allocate memory. Instead of a 'type' parameter, they take a pointer to a
46+ new object (allocated by an arbitrary allocator), and initialize its object
47+ header fields.
48+
49+Note that objects created with PyObject_{New, NewVar} are allocated using the
50+specialized Python allocator (implemented in obmalloc.c), if WITH_PYMALLOC is
51+enabled. In addition, a special debugging allocator is used if PYMALLOC_DEBUG
52+is also #defined.
53+
54+In case a specific form of memory management is needed (for example, if you
55+must use the platform malloc heap(s), or shared memory, or C++ local storage or
56+operator new), you must first allocate the object with your custom allocator,
57+then pass its pointer to PyObject_{Init, InitVar} for filling in its Python-
58+specific fields: reference count, type pointer, possibly others. You should
59+be aware that Python no control over these objects because they don't
60+cooperate with the Python memory manager. Such objects may not be eligible
61+for automatic garbage collection and you have to make sure that they are
62+released accordingly whenever their destructor gets called (cf. the specific
63+form of memory management you're using).
64+
65+Unless you have specific memory management requirements, use
66+PyObject_{New, NewVar, Del}.
67+*/
68+
69+/*
70+ * Raw object memory interface
71+ * ===========================
72+ */
73+
74+/* Functions to call the same malloc/realloc/free as used by Python's
75+ object allocator. If WITH_PYMALLOC is enabled, these may differ from
76+ the platform malloc/realloc/free. The Python object allocator is
77+ designed for fast, cache-conscious allocation of many "small" objects,
78+ and with low hidden memory overhead.
79+
80+ PyObject_Malloc(0) returns a unique non-NULL pointer if possible.
81+
82+ PyObject_Realloc(NULL, n) acts like PyObject_Malloc(n).
83+ PyObject_Realloc(p != NULL, 0) does not return NULL, or free the memory
84+ at p.
85+
86+ Returned pointers must be checked for NULL explicitly; no action is
87+ performed on failure other than to return NULL (no warning it printed, no
88+ exception is set, etc).
89+
90+ For allocating objects, use PyObject_{New, NewVar} instead whenever
91+ possible. The PyObject_{Malloc, Realloc, Free} family is exposed
92+ so that you can exploit Python's small-block allocator for non-object
93+ uses. If you must use these routines to allocate object memory, make sure
94+ the object gets initialized via PyObject_{Init, InitVar} after obtaining
95+ the raw memory.
96+*/
97+PyAPI_FUNC(void *) PyObject_Malloc(size_t);
98+PyAPI_FUNC(void *) PyObject_Realloc(void *, size_t);
99+PyAPI_FUNC(void) PyObject_Free(void *);
100+
101+
102+/* Macros */
103+#ifdef WITH_PYMALLOC
104+#ifdef PYMALLOC_DEBUG /* WITH_PYMALLOC && PYMALLOC_DEBUG */
105+PyAPI_FUNC(void *) _PyObject_DebugMalloc(size_t nbytes);
106+PyAPI_FUNC(void *) _PyObject_DebugRealloc(void *p, size_t nbytes);
107+PyAPI_FUNC(void) _PyObject_DebugFree(void *p);
108+PyAPI_FUNC(void) _PyObject_DebugDumpAddress(const void *p);
109+PyAPI_FUNC(void) _PyObject_DebugCheckAddress(const void *p);
110+PyAPI_FUNC(void) _PyObject_DebugMallocStats(void);
111+#define PyObject_MALLOC _PyObject_DebugMalloc
112+#define PyObject_Malloc _PyObject_DebugMalloc
113+#define PyObject_REALLOC _PyObject_DebugRealloc
114+#define PyObject_Realloc _PyObject_DebugRealloc
115+#define PyObject_FREE _PyObject_DebugFree
116+#define PyObject_Free _PyObject_DebugFree
117+
118+#else /* WITH_PYMALLOC && ! PYMALLOC_DEBUG */
119+#define PyObject_MALLOC PyObject_Malloc
120+#define PyObject_REALLOC PyObject_Realloc
121+#define PyObject_FREE PyObject_Free
122+#endif
123+
124+#else /* ! WITH_PYMALLOC */
125+#define PyObject_MALLOC PyMem_MALLOC
126+#define PyObject_REALLOC PyMem_REALLOC
127+#define PyObject_FREE PyMem_FREE
128+
129+#endif /* WITH_PYMALLOC */
130+
131+#define PyObject_Del PyObject_Free
132+#define PyObject_DEL PyObject_FREE
133+
134+/* for source compatibility with 2.2 */
135+#define _PyObject_Del PyObject_Free
136+
137+/*
138+ * Generic object allocator interface
139+ * ==================================
140+ */
141+
142+/* Functions */
143+PyAPI_FUNC(PyObject *) PyObject_Init(PyObject *, PyTypeObject *);
144+PyAPI_FUNC(PyVarObject *) PyObject_InitVar(PyVarObject *,
145+ PyTypeObject *, Py_ssize_t);
146+PyAPI_FUNC(PyObject *) _PyObject_New(PyTypeObject *);
147+PyAPI_FUNC(PyVarObject *) _PyObject_NewVar(PyTypeObject *, Py_ssize_t);
148+
149+#define PyObject_New(type, typeobj) \
150+ ( (type *) _PyObject_New(typeobj) )
151+#define PyObject_NewVar(type, typeobj, n) \
152+ ( (type *) _PyObject_NewVar((typeobj), (n)) )
153+
154+/* Macros trading binary compatibility for speed. See also pymem.h.
155+ Note that these macros expect non-NULL object pointers.*/
156+#define PyObject_INIT(op, typeobj) \
157+ ( (op)->ob_type = (typeobj), _Py_NewReference((PyObject *)(op)), (op) )
158+#define PyObject_INIT_VAR(op, typeobj, size) \
159+ ( (op)->ob_size = (size), PyObject_INIT((op), (typeobj)) )
160+
161+#define _PyObject_SIZE(typeobj) ( (typeobj)->tp_basicsize )
162+
163+/* _PyObject_VAR_SIZE returns the number of bytes (as size_t) allocated for a
164+ vrbl-size object with nitems items, exclusive of gc overhead (if any). The
165+ value is rounded up to the closest multiple of sizeof(void *), in order to
166+ ensure that pointer fields at the end of the object are correctly aligned
167+ for the platform (this is of special importance for subclasses of, e.g.,
168+ str or long, so that pointers can be stored after the embedded data).
169+
170+ Note that there's no memory wastage in doing this, as malloc has to
171+ return (at worst) pointer-aligned memory anyway.
172+*/
173+#if ((SIZEOF_VOID_P - 1) & SIZEOF_VOID_P) != 0
174+# error "_PyObject_VAR_SIZE requires SIZEOF_VOID_P be a power of 2"
175+#endif
176+
177+#define _PyObject_VAR_SIZE(typeobj, nitems) \
178+ (size_t) \
179+ ( ( (typeobj)->tp_basicsize + \
180+ (nitems)*(typeobj)->tp_itemsize + \
181+ (SIZEOF_VOID_P - 1) \
182+ ) & ~(SIZEOF_VOID_P - 1) \
183+ )
184+
185+#define PyObject_NEW(type, typeobj) \
186+( (type *) PyObject_Init( \
187+ (PyObject *) PyObject_MALLOC( _PyObject_SIZE(typeobj) ), (typeobj)) )
188+
189+#define PyObject_NEW_VAR(type, typeobj, n) \
190+( (type *) PyObject_InitVar( \
191+ (PyVarObject *) PyObject_MALLOC(_PyObject_VAR_SIZE((typeobj),(n)) ),\
192+ (typeobj), (n)) )
193+
194+/* This example code implements an object constructor with a custom
195+ allocator, where PyObject_New is inlined, and shows the important
196+ distinction between two steps (at least):
197+ 1) the actual allocation of the object storage;
198+ 2) the initialization of the Python specific fields
199+ in this storage with PyObject_{Init, InitVar}.
200+
201+ PyObject *
202+ YourObject_New(...)
203+ {
204+ PyObject *op;
205+
206+ op = (PyObject *) Your_Allocator(_PyObject_SIZE(YourTypeStruct));
207+ if (op == NULL)
208+ return PyErr_NoMemory();
209+
210+ PyObject_Init(op, &YourTypeStruct);
211+
212+ op->ob_field = value;
213+ ...
214+ return op;
215+ }
216+
217+ Note that in C++, the use of the new operator usually implies that
218+ the 1st step is performed automatically for you, so in a C++ class
219+ constructor you would start directly with PyObject_Init/InitVar
220+*/
221+
222+/*
223+ * Garbage Collection Support
224+ * ==========================
225+ */
226+
227+/* C equivalent of gc.collect(). */
228+PyAPI_FUNC(Py_ssize_t) PyGC_Collect(void);
229+
230+/* Test if a type has a GC head */
231+#define PyType_IS_GC(t) PyType_HasFeature((t), Py_TPFLAGS_HAVE_GC)
232+
233+/* Test if an object has a GC head */
234+#define PyObject_IS_GC(o) (PyType_IS_GC((o)->ob_type) && \
235+ ((o)->ob_type->tp_is_gc == NULL || (o)->ob_type->tp_is_gc(o)))
236+
237+PyAPI_FUNC(PyVarObject *) _PyObject_GC_Resize(PyVarObject *, Py_ssize_t);
238+#define PyObject_GC_Resize(type, op, n) \
239+ ( (type *) _PyObject_GC_Resize((PyVarObject *)(op), (n)) )
240+
241+/* for source compatibility with 2.2 */
242+#define _PyObject_GC_Del PyObject_GC_Del
243+
244+/* GC information is stored BEFORE the object structure. */
245+typedef union _gc_head {
246+ struct {
247+ union _gc_head *gc_next;
248+ union _gc_head *gc_prev;
249+ Py_ssize_t gc_refs;
250+ } gc;
251+ long double dummy; /* force worst-case alignment */
252+} PyGC_Head;
253+
254+extern PyGC_Head *_PyGC_generation0;
255+
256+#define _Py_AS_GC(o) ((PyGC_Head *)(o)-1)
257+
258+#define _PyGC_REFS_UNTRACKED (-2)
259+#define _PyGC_REFS_REACHABLE (-3)
260+#define _PyGC_REFS_TENTATIVELY_UNREACHABLE (-4)
261+
262+/* Tell the GC to track this object. NB: While the object is tracked the
263+ * collector it must be safe to call the ob_traverse method. */
264+#define _PyObject_GC_TRACK(o) do { \
265+ PyGC_Head *g = _Py_AS_GC(o); \
266+ if (g->gc.gc_refs != _PyGC_REFS_UNTRACKED) \
267+ Py_FatalError("GC object already tracked"); \
268+ g->gc.gc_refs = _PyGC_REFS_REACHABLE; \
269+ g->gc.gc_next = _PyGC_generation0; \
270+ g->gc.gc_prev = _PyGC_generation0->gc.gc_prev; \
271+ g->gc.gc_prev->gc.gc_next = g; \
272+ _PyGC_generation0->gc.gc_prev = g; \
273+ } while (0);
274+
275+/* Tell the GC to stop tracking this object.
276+ * gc_next doesn't need to be set to NULL, but doing so is a good
277+ * way to provoke memory errors if calling code is confused.
278+ */
279+#define _PyObject_GC_UNTRACK(o) do { \
280+ PyGC_Head *g = _Py_AS_GC(o); \
281+ assert(g->gc.gc_refs != _PyGC_REFS_UNTRACKED); \
282+ g->gc.gc_refs = _PyGC_REFS_UNTRACKED; \
283+ g->gc.gc_prev->gc.gc_next = g->gc.gc_next; \
284+ g->gc.gc_next->gc.gc_prev = g->gc.gc_prev; \
285+ g->gc.gc_next = NULL; \
286+ } while (0);
287+
288+PyAPI_FUNC(PyObject *) _PyObject_GC_Malloc(size_t);
289+PyAPI_FUNC(PyObject *) _PyObject_GC_New(PyTypeObject *);
290+PyAPI_FUNC(PyVarObject *) _PyObject_GC_NewVar(PyTypeObject *, Py_ssize_t);
291+PyAPI_FUNC(void) PyObject_GC_Track(void *);
292+PyAPI_FUNC(void) PyObject_GC_UnTrack(void *);
293+PyAPI_FUNC(void) PyObject_GC_Del(void *);
294+
295+#define PyObject_GC_New(type, typeobj) \
296+ ( (type *) _PyObject_GC_New(typeobj) )
297+#define PyObject_GC_NewVar(type, typeobj, n) \
298+ ( (type *) _PyObject_GC_NewVar((typeobj), (n)) )
299+
300+
301+/* Utility macro to help write tp_traverse functions.
302+ * To use this macro, the tp_traverse function must name its arguments
303+ * "visit" and "arg". This is intended to keep tp_traverse functions
304+ * looking as much alike as possible.
305+ */
306+#define Py_VISIT(op) \
307+ do { \
308+ if (op) { \
309+ int vret = visit((PyObject *)(op), arg); \
310+ if (vret) \
311+ return vret; \
312+ } \
313+ } while (0)
314+
315+/* This is here for the sake of backwards compatibility. Extensions that
316+ * use the old GC API will still compile but the objects will not be
317+ * tracked by the GC. */
318+#define PyGC_HEAD_SIZE 0
319+#define PyObject_GC_Init(op)
320+#define PyObject_GC_Fini(op)
321+#define PyObject_AS_GC(op) (op)
322+#define PyObject_FROM_GC(op) (op)
323+
324+
325+/* Test if a type supports weak references */
326+#define PyType_SUPPORTS_WEAKREFS(t) \
327+ (PyType_HasFeature((t), Py_TPFLAGS_HAVE_WEAKREFS) \
328+ && ((t)->tp_weaklistoffset > 0))
329+
330+#define PyObject_GET_WEAKREFS_LISTPTR(o) \
331+ ((PyObject **) (((char *) (o)) + (o)->ob_type->tp_weaklistoffset))
332+
333+#ifdef __cplusplus
334+}
335+#endif
336+#endif /* !Py_OBJIMPL_H */