[Python-checkins] CVS: python/dist/src/Doc/api api.tex,1.56.2.16,1.56.2.17
Fred L. Drake
fdrake@weyr.cnri.reston.va.us
Mon, 6 Mar 2000 12:04:12 -0500 (EST)
Update of /projects/cvsroot/python/dist/src/Doc/api
In directory weyr:/home/fdrake/projects/python/Doc-152p2/api
Modified Files:
Tag: release152p1-patches
api.tex
Log Message:
Some additional reorganization of stuff in the buffer section in the
last chapter; still not complete.
Index: api.tex
===================================================================
RCS file: /projects/cvsroot/python/dist/src/Doc/api/api.tex,v
retrieving revision 1.56.2.16
retrieving revision 1.56.2.17
diff -C2 -r1.56.2.16 -r1.56.2.17
*** api.tex 2000/03/03 16:32:47 1.56.2.16
--- api.tex 2000/03/06 17:04:08 1.56.2.17
***************
*** 3248,3251 ****
--- 3248,3252 ----
\sectionauthor{Vladimir Marangozov}{Vladimir.Marangozov@inrialpes.fr}
+
\section{Overview \label{memoryOverview}}
***************
*** 3321,3324 ****
--- 3322,3326 ----
the I/O buffer escapes completely the Python memory manager.
+
\section{Memory Interface \label{memoryInterface}}
***************
*** 3508,3522 ****
\section{Mapping Object Structures \label{mapping-structs}}
! PyMappingMethods
\section{Number Object Structures \label{number-structs}}
! PyNumberMethods
\section{Sequence Object Structures \label{sequence-structs}}
! PySequenceMethods
--- 3510,3533 ----
\section{Mapping Object Structures \label{mapping-structs}}
! \begin{ctypedesc}{PyMappingMethods}
! Structure used to hold pointers to the functions used to implement the
! mapping protocol for an extension type.
! \end{ctypedesc}
\section{Number Object Structures \label{number-structs}}
! \begin{ctypedesc}{PyNumberMethods}
! Structure used to hold pointers to the functions an extension type
! uses to implement the number protocol.
! \end{ctypedesc}
\section{Sequence Object Structures \label{sequence-structs}}
! \begin{ctypedesc}{PySequenceMethods}
! Structure used to hold pointers to the functions which an object uses
! to implement the sequence protocol.
! \end{ctypedesc}
***************
*** 3526,3531 ****
The buffer interface exports a model where an object can expose its
internal data as a set of chunks of data, each chunk 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
--- 3537,3542 ----
The buffer interface exports a model where an object can expose its
internal data as a set of chunks of data, each chunk 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
***************
*** 3534,3568 ****
a \ctype{PyBufferProcs} structure.
! \emph{Note:} it is very important that your
\ctype{PyTypeObject} structure uses \code{Py_TPFLAGS_DEFAULT} for the
! value of the \member{tp_flags} member. This tells the Python runtime
! that your \ctype{PyBufferProcs} structure contains the
! \member{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.
!
\begin{ctypedesc}{PyBufferProcs}
! \code{PyBufferProcs} defines a set of slots for a Python type
! object. These slots are used to implement the ``buffer interface.''
! The first slot in the \ctype{PyBufferProcs} structure is
! \member{bf_getreadbuffer}, which has type
\ctype{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. The read-buffer
! function is allowed to raise an exception and return
! \code{-1}. Callers should test for \NULL{} before using the slot and
! should check for an exception after calling the function. The
! \var{segment} which is passed must be zero or positive, and strictly
! less than the number of segments returned by the
! \member{bf_getsegcount} slot function.
The next slot is \member{bf_getwritebuffer} having type
\ctype{getwritebufferproc}. This slot may be \NULL{} if the object
! does not allow writing into its returned buffers. If the slot function
! is present, it is allowed to raise an exception and return \code{-1}.
! The \var{segment} follows the same restrictions as for
! \member{bf_getreadbuffer}.
The third slot is \member{bf_getsegcount}, with type
--- 3545,3569 ----
a \ctype{PyBufferProcs} structure.
! \emph{Note:} It is very important that your
\ctype{PyTypeObject} structure uses \code{Py_TPFLAGS_DEFAULT} for the
! value of the \member{tp_flags} member rather than \code{0}. This
! tells the Python runtime that your \ctype{PyBufferProcs} structure
! contains the \member{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.
\begin{ctypedesc}{PyBufferProcs}
! Structure used to hold the function pointers which define an
! implementation of the buffer protocol.
! The first slot is \member{bf_getreadbuffer}, of type
\ctype{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 \member{bf_getwritebuffer} having type
\ctype{getwritebufferproc}. This slot may be \NULL{} if the object
! does not allow writing into its returned buffers.
The third slot is \member{bf_getsegcount}, with type
***************
*** 3570,3592 ****
inform the caller how many segments the object contains. Simple
objects such as \ctype{PyString_Type} and
! \ctype{PyBuffer_Type} objects contain a single segment. The
! \var{lenp} parameter may be \NULL{}. If not, then the implementation
! should store the total size of all buffer segments into \code{*lenp}.
! The last slot is \member{bf_getcharbuffer}, which has type
! \ctype{getcharbufferproc}. This slot will only be present if the
\code{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in
! \member{tp_flags} of the object's \ctype{PyTypeObject}. Before using
this slot, the caller should test whether it is present by using the
! \cfunction{PyType_HasFeature()} macro. Assuming the slot is present,
! then it may be \NULL{} indicating that the object's contents cannot be
! used a \emph{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 \member{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.
\emph{Note:} The current policy seems to state that these characters
--- 3571,3592 ----
inform the caller how many segments the object contains. Simple
objects such as \ctype{PyString_Type} and
! \ctype{PyBuffer_Type} objects contain a single segment.
! The last slot is \member{bf_getcharbuffer}, of type
! \ctype{getcharbufferproc}. This slot will only be present if the
\code{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in
! \member{tp_flags} of the object's \ctype{PyTypeObject}. Before using
this slot, the caller should test whether it is present by using the
! \cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()} function.
! If present, it may be \NULL, indicating that the object's contents
! cannot be used as \emph{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
! \member{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.
\emph{Note:} The current policy seems to state that these characters
***************
*** 3595,3600 ****
--- 3595,3614 ----
\end{ctypedesc}
+ \begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER}
+ Flag bit set in the type structure to indicate that the
+ \member{bf_getcharbuffer} slot is known. This being set does not
+ indicate that the object supports the buffer interface or that the
+ \member{bf_getcharbuffer} slot is non-\NULL.
+ \end{datadesc}
+
\begin{ctypedesc}[getreadbufferproc]{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
+ \code{-1}. The \var{segment} which is passed must be zero or
+ positive, and strictly less than the number of segments returned by
+ the \member{bf_getsegcount} slot function. On success, returns
+ \code{0} and sets \code{*\var{ptrptr}} to a pointer to the buffer
+ memory.
\end{ctypedesc}
***************
*** 3615,3618 ****
--- 3629,3636 ----
\begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc)
(PyObject *self, int *lenp)}
+ Return the number of memory segments which comprise the buffer. If
+ \var{lenp} is not \NULL, the implementation must report the sum of the
+ sizes (in bytes) of all segments in \code{*\var{lenp}}.
+ The function cannot fail.
\end{ctypedesc}