[Python-checkins] python/nondist/peps pep-0298.txt,1.1,1.2

theller@users.sourceforge.net theller@users.sourceforge.net
Tue, 30 Jul 2002 09:41:07 -0700


Update of /cvsroot/python/python/nondist/peps
In directory usw-pr-cvs1:/tmp/cvs-serv19526

Modified Files:
	pep-0298.txt 
Log Message:
Rename the 'safe buffer interface' to 'fixed buffer interface',
and give Scott Gilert credit for it.

Change the author line to the new style.
Small other changes.

Barry, can you run pep2html on it, and change the PEP index to the new
name?


Index: pep-0298.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0298.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** pep-0298.txt	29 Jul 2002 18:22:09 -0000	1.1
--- pep-0298.txt	30 Jul 2002 16:41:04 -0000	1.2
***************
*** 1,7 ****
  PEP: 298
! Title: The Safe Buffer Interface
  Version: $Revision$
  Last-Modified: $Date$
! Author: theller@python.net (Thomas Heller)
  Status: Draft
  Type: Standards Track
--- 1,7 ----
  PEP: 298
! Title: The Fixed Buffer Interface
  Version: $Revision$
  Last-Modified: $Date$
! Author: Thomas Heller <theller@python.net>
  Status: Draft
  Type: Standards Track
***************
*** 14,20 ****
  
      This PEP proposes an extension to the buffer interface called the
!     'safe buffer interface'.
  
!     The safe buffer interface fixes the flaws of the 'old' buffer
      interface as defined in Python versions up to and including 2.2,
      see [1]:
--- 14,20 ----
  
      This PEP proposes an extension to the buffer interface called the
!     'fixed buffer interface'.
  
!     The fixed buffer interface fixes the flaws of the 'old' buffer
      interface as defined in Python versions up to and including 2.2,
      see [1]:
***************
*** 29,33 ****
  Specification
  
!     The safe buffer interface exposes new functions which return the
      size and the pointer to the internal memory block of any python
      object which chooses to implement this interface.
--- 29,33 ----
  Specification
  
!     The fixed buffer interface exposes new functions which return the
      size and the pointer to the internal memory block of any python
      object which chooses to implement this interface.
***************
*** 38,42 ****
      implement this interface.
  
!     The safe buffer interface omits the memory segment model which is
      present in the old buffer interface - only a single memory block
      can be exposed.
--- 38,42 ----
      implement this interface.
  
!     The fixed buffer interface omits the memory segment model which is
      present in the old buffer interface - only a single memory block
      can be exposed.
***************
*** 47,53 ****
      Define a new flag in Include/object.h:
  
!         /* PyBufferProcs contains bf_getsafereadbuffer
!            and bf_getsafewritebuffer */
!         #define Py_TPFLAGS_HAVE_GETSAFEBUFFER (1L<<15)
  
  
--- 47,53 ----
      Define a new flag in Include/object.h:
  
!         /* PyBufferProcs contains bf_getfixedreadbuffer
!            and bf_getfixedwritebuffer */
!         #define Py_TPFLAGS_HAVE_GETFIXEDBUFFER (1L<<15)
  
  
***************
*** 56,60 ****
          #define Py_TPFLAGS_DEFAULT  ( \
                               ....
!                              Py_TPFLAGS_HAVE_GETSAFEBUFFER | \
                               ....
                              0)
--- 56,60 ----
          #define Py_TPFLAGS_DEFAULT  ( \
                               ....
!                              Py_TPFLAGS_HAVE_GETFIXEDBUFFER | \
                               ....
                              0)
***************
*** 64,69 ****
      Include/object.h:
  
!         typedef size_t (*getsafereadbufferproc)(PyObject *, void **);
!         typedef size_t (*getsafewritebufferproc)(PyObject *, void **);
  
          typedef struct {
--- 64,69 ----
      Include/object.h:
  
!         typedef size_t (*getfixedreadbufferproc)(PyObject *, void **);
!         typedef size_t (*getfixedwritebufferproc)(PyObject *, void **);
  
          typedef struct {
***************
*** 72,88 ****
                  getsegcountproc bf_getsegcount;
                  getcharbufferproc bf_getcharbuffer;
!                 /* safe buffer interface functions */
!                 getsafereadbufferproc bf_getsafereadbufferproc;
!                 getsafewritebufferproc bf_getsafewritebufferproc;
          } PyBufferProcs;
  
  
!     The new fields are present if the Py_TPFLAGS_HAVE_GETSAFEBUFFER
      flag is set in the object's type.
  
!     The Py_TPFLAGS_HAVE_GETSAFEBUFFER flag implies the
      Py_TPFLAGS_HAVE_GETCHARBUFFER flag.
  
!     The getsafereadbufferproc and getsafewritebufferproc functions
      return the size in bytes of the memory block on success, and fill
      in the passed void * pointer on success.  If these functions fail
--- 72,88 ----
                  getsegcountproc bf_getsegcount;
                  getcharbufferproc bf_getcharbuffer;
!                 /* fixed buffer interface functions */
!                 getfixedreadbufferproc bf_getfixedreadbufferproc;
!                 getfixedwritebufferproc bf_getfixedwritebufferproc;
          } PyBufferProcs;
  
  
!     The new fields are present if the Py_TPFLAGS_HAVE_GETFIXEDBUFFER
      flag is set in the object's type.
  
!     The Py_TPFLAGS_HAVE_GETFIXEDBUFFER flag implies the
      Py_TPFLAGS_HAVE_GETCHARBUFFER flag.
  
!     The getfixedreadbufferproc and getfixedwritebufferproc functions
      return the size in bytes of the memory block on success, and fill
      in the passed void * pointer on success.  If these functions fail
***************
*** 92,104 ****
      used.
  
!     Usually the getsafewritebufferproc and getsafereadbufferproc
      functions aren't called directly, they are called through
      convenience functions declared in Include/abstract.h:
  
!         int PyObject_AsSafeReadBuffer(PyObject *obj,
                                        void **buffer,
                                        size_t *buffer_len);
  
!         int PyObject_AsSafeWriteBuffer(PyObject *obj,
                                         void **buffer,
                                         size_t *buffer_len);
--- 92,104 ----
      used.
  
!     Usually the getfixedwritebufferproc and getfixedreadbufferproc
      functions aren't called directly, they are called through
      convenience functions declared in Include/abstract.h:
  
!         int PyObject_AsFixedReadBuffer(PyObject *obj,
                                        void **buffer,
                                        size_t *buffer_len);
  
!         int PyObject_AsFixedWriteBuffer(PyObject *obj,
                                         void **buffer,
                                         size_t *buffer_len);
***************
*** 106,110 ****
      These functions return 0 on success, set buffer to the memory
      location and buffer_len to the length of the memory block in
!     bytes. On failure, or if the safe buffer interface is not
      implemented by obj, they return -1 and set an exception.
  
--- 106,110 ----
      These functions return 0 on success, set buffer to the memory
      location and buffer_len to the length of the memory block in
!     bytes. On failure, or if the fixed buffer interface is not
      implemented by obj, they return -1 and set an exception.
  
***************
*** 125,129 ****
  
      Python strings, Unicode strings, mmap objects, and maybe other
!     types would expose the safe buffer interface, but the array type
      would *not*, because its memory block may be reallocated during
      its lifetime.
--- 125,129 ----
  
      Python strings, Unicode strings, mmap objects, and maybe other
!     types would expose the fixed buffer interface, but the array type
      would *not*, because its memory block may be reallocated during
      its lifetime.
***************
*** 132,143 ****
  Community Feedback
  
!     Greg Ewing doubts the safe buffer interface is needed at all, he
      thinks the normal buffer interface could be used if the pointer is
!     (re)fetched each time it's used.
  
      Neil Hodgson wants to expose pointers to memory blocks with
      limited lifetime: do some kind of lock operation on the object,
!     retrieve the pointer, use it, and unlock the object again.  On the
!     other hand, locking may lead to deadlocks.
  
  
--- 132,152 ----
  Community Feedback
  
!     Greg Ewing doubts the fixed buffer interface is needed at all, he
      thinks the normal buffer interface could be used if the pointer is
!     (re)fetched each time it's used.  This seems to be dangerous,
!     because even innocent looking calls to the Python API like
!     Py_DECREF() may trigger execution of arbitrary Python code.
  
      Neil Hodgson wants to expose pointers to memory blocks with
      limited lifetime: do some kind of lock operation on the object,
!     retrieve the pointer, use it, and unlock the object again.  While
!     the author sees the need for this, it cannot be addressed by this
!     proposal.  Beeing required to call a function after not using the
!     pointer received by the getfixedbufferprocs seems too error prone.
! 
! 
! Credits
! 
!     Scott Gilbert came up with the name 'fixed buffer interface'.