From 36eef3c1739cdec3956e5ad86b5887985d249302 Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Thu, 8 Oct 1998 02:10:56 +0000 Subject: Changes by Greg Stein (code) and GvR (design). Add a new member to the PyBufferProcs struct, bf_getcharbuffer. For backward compatibility, this member should only be used (this includes testing for NULL!) when the flag Py_TPFLAGS_HAVE_GETCHARBUFFER is set in the type structure, below. Note that if its flag is not set, we may be looking at an extension module compiled for 1.5.1, which will have garbage at the bf_getcharbuffer member (because the struct wasn't as long then). If the flag is one, the pointer may still be NULL. The function found at this member is used in a similar manner as bf_getreadbuffer, but it is known to point to 8-bit character data. (See discussion in getargs.c checked in later.) As a general feature for extending the type structure and the various structures that (may) hang off it in a backwards compatible way, we rename the tp_xxx4 "spare" slot to tp_flags. In 1.5.1 and before, this slot was always zero. In 1.5.1, it may contain various flags indicating extra fields that weren't present in 1.5.1. The only flag defined so far is for the bf_getcharbuffer member of the PyBufferProcs struct. Note that the new spares (tp_xxx5 - tp_xxx8), once they become used, should also be protected by a flag (or flags) in tp_flags. --- Include/object.h | 37 +++++++++++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/Include/object.h b/Include/object.h index c6e3823..136e202 100644 --- a/Include/object.h +++ b/Include/object.h @@ -149,6 +149,7 @@ typedef int(*objobjargproc) Py_PROTO((PyObject *, PyObject *, PyObject *)); typedef int (*getreadbufferproc) Py_PROTO((PyObject *, int, void **)); typedef int (*getwritebufferproc) Py_PROTO((PyObject *, int, void **)); typedef int (*getsegcountproc) Py_PROTO((PyObject *, int *)); +typedef int (*getcharbufferproc) Py_PROTO((PyObject *, int, const char **)); typedef struct { binaryfunc nb_add; @@ -196,6 +197,7 @@ typedef struct { getreadbufferproc bf_getreadbuffer; getwritebufferproc bf_getwritebuffer; getsegcountproc bf_getsegcount; + getcharbufferproc bf_getcharbuffer; } PyBufferProcs; @@ -240,8 +242,8 @@ typedef struct _typeobject { /* Functions to access object as input/output buffer */ PyBufferProcs *tp_as_buffer; - /* Space for future expansion */ - long tp_xxx4; + /* Flags to define presence of optional/expanded features */ + long tp_flags; char *tp_doc; /* Documentation string */ @@ -290,6 +292,37 @@ extern void Py_ReprLeave Py_PROTO((PyObject *)); #define Py_PRINT_RAW 1 /* No string quotes etc. */ /* + +Type flags (tp_flags) + +These flags are used to extend the type structure in a backwards-compatible +fashion. Extensions can use the flags to indicate (and test) when a given +type structure contains a new feature. The Python core will use these when +introducing new functionality between major revisions (to avoid mid-version +changes in the PYTHON_API_VERSION). + +Arbitration of the flag bit positions will need to be coordinated among +all extension writers who publically release their extensions (this will +be fewer than you might expect!).. + +Python 1.5.2 introduced the bf_getcharbuffer slot into PyBufferProcs. + +Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value. + +Code can use PyType_HasFeature(type_ob, flag_value) to test whether the +given type object has a specified feature. + +*/ + +/* PyBufferProcs contains bf_getcharbuffer */ +#define Py_TPFLAGS_HAVE_GETCHARBUFFER (1L<<0) + +#define Py_TPFLAGS_DEFAULT (Py_TPFLAGS_HAVE_GETCHARBUFFER) + +#define PyType_HasFeature(t,f) (((t)->tp_flags & (f)) != 0) + + +/* 123456789-123456789-123456789-123456789-123456789-123456789-123456789-12 The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement -- cgit v0.12