GNU Info

(python2.1-api.info)Buffer Object Structures

---

Next: Supporting Cyclic Garbarge Collection Prev: Sequence Object Structures Up: Defining New Object Types

---

Enter node , (file) or (file)node

Buffer Object Structures
========================

This manual section was written by Greg J. Stein <greg@lyra.org>.
The buffer interface exports a model where an object can expose its
internal data as a set of chunks of data, where each chunk is specified
as a pointer/length pair.  These chunks are called "segments" and are
presumed to be non-contiguous in memory.

If an object does not export the buffer interface, then its
`tp_as_buffer' member in the `PyTypeObject' structure should be `NULL'.
Otherwise, the `tp_as_buffer' will point to a `PyBufferProcs'
structure.

*Note:* It is very important that your `PyTypeObject' structure uses
`Py_TPFLAGS_DEFAULT' for the value of the `tp_flags' member rather than
`0'.  This tells the Python runtime that your `PyBufferProcs' structure
contains the `bf_getcharbuffer' slot. Older versions of Python did not
have this member, so a new Python interpreter using an old extension
needs to be able to test for its presence before using it.

`PyBufferProcs'
     Structure used to hold the function pointers which define an
     implementation of the buffer protocol.

     The first slot is `bf_getreadbuffer', of type `getreadbufferproc'.
     If this slot is `NULL', then the object does not support reading
     from the internal data.  This is non-sensical, so implementors
     should fill this in, but callers should test that the slot
     contains a non-`NULL' value.

     The next slot is `bf_getwritebuffer' having type
     `getwritebufferproc'. This slot may be `NULL' if the object does
     not allow writing into its returned buffers.

     The third slot is `bf_getsegcount', with type `getsegcountproc'.
     This slot must not be `NULL' and is used to inform the caller how
     many segments the object contains.  Simple objects such as
     `PyString_Type' and `PyBuffer_Type' objects contain a single
     segment.

     The last slot is `bf_getcharbuffer', of type `getcharbufferproc'.
     This slot will only be present if the
     `Py_TPFLAGS_HAVE_GETCHARBUFFER' flag is present in the `tp_flags'
     field of the object's `PyTypeObject'.  Before using this slot, the
     caller should test whether it is present by using the
     `PyType_HasFeature()'  function.  If present, it may be `NULL',
     indicating that the object's contents cannot be used as _8-bit
     characters_.  The slot function may also raise an error if the
     object's contents cannot be interpreted as 8-bit characters.  For
     example, if the object is an array which is configured to hold
     floating point values, an exception may be raised if a caller
     attempts to use `bf_getcharbuffer' to fetch a sequence of 8-bit
     characters.  This notion of exporting the internal buffers as
     "text" is used to distinguish between objects that are binary in
     nature, and those which have character-based content.

     *Note:* The current policy seems to state that these characters
     may be multi-byte characters. This implies that a buffer size of N
     does not mean there are N characters present.

`Py_TPFLAGS_HAVE_GETCHARBUFFER'
     Flag bit set in the type structure to indicate that the
     `bf_getcharbuffer' slot is known.  This being set does not
     indicate that the object supports the buffer interface or that the
     `bf_getcharbuffer' slot is non-`NULL'.

`int (*getreadbufferproc) (PyObject *self, int segment, void **ptrptr)'
     Return a pointer to a readable segment of the buffer.  This
     function is allowed to raise an exception, in which case it must
     return `-1'.  The SEGMENT which is passed must be zero or
     positive, and strictly less than the number of segments returned by
     the `bf_getsegcount' slot function.  On success, it returns the
     length of the buffer memory, and sets `*PTRPTR' to a pointer to
     that memory.

`int (*getwritebufferproc) (PyObject *self, int segment, void **ptrptr)'
     Return a pointer to a writable memory buffer in `*PTRPTR', and the
     length of that segment as the function return value.  The memory
     buffer must correspond to buffer segment SEGMENT.  Must return
     `-1' and set an exception on error.  `TypeError' should be raised
     if the object only supports read-only buffers, and `SystemError'
     should be raised when SEGMENT specifies a segment that doesn't
     exist.

`int (*getsegcountproc) (PyObject *self, int *lenp)'
     Return the number of memory segments which comprise the buffer.  If
     LENP is not `NULL', the implementation must report the sum of the
     sizes (in bytes) of all segments in `*LENP'.  The function cannot
     fail.

`int (*getcharbufferproc) (PyObject *self, int segment, const char **ptrptr)'