10.5 Buffer Object Structures
Keywords: api

#
10.5 Buffer Object Structures

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, returns `0` and sets `*ptrptr` to a pointer to the buffer memory.

`int (*getwritebufferproc) (PyObject *self, int segment, void **ptrptr)`
  Return a pointer to a writable memory buffer in `*ptrptr`; 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)`