Changes by Greg Stein (code) and GvR (design).

gvanrossum · gvanrossum · commit 36eef3c1739c · 1998-10-08T02:10:56.000Z
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.
diff --git 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 */
 
@@ -289,6 +291,37 @@ extern void Py_ReprLeave Py_PROTO((PyObject *));
 /* Flag bits for printing: */
 #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
 
