iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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?
This commit is contained in:
Thomas Heller 2002-07-30 16:41:04 +00:00
parent b6612d3812
commit 10d37607c9
1 changed files with 36 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
pep-0298.txt
View File

@ -1,8 +1,8 @@
PEP: 298
Title: The Safe Buffer Interface
Title: The Fixed Buffer Interface
Version: $Revision$
Last-Modified: $Date$
Author: theller@python.net (Thomas Heller)
Author: Thomas Heller <theller@python.net>
Status: Draft
Type: Standards Track
Created: 26-Jul-2002
@ -13,9 +13,9 @@ Post-History:
Abstract
This PEP proposes an extension to the buffer interface called the
'safe buffer interface'.
'fixed buffer interface'.
The safe buffer interface fixes the flaws of the 'old' buffer
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]:
@ -28,7 +28,7 @@ Abstract
Specification
The safe buffer interface exposes new functions which return the
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.
@ -37,7 +37,7 @@ Specification
never reallocate or resize the memory block are allowed to
implement this interface.
The safe buffer interface omits the memory segment model which is
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.
@ -46,16 +46,16 @@ Implementation
Define a new flag in Include/object.h:
/* PyBufferProcs contains bf_getsafereadbuffer
and bf_getsafewritebuffer */
#define Py_TPFLAGS_HAVE_GETSAFEBUFFER (1L<<15)
/* PyBufferProcs contains bf_getfixedreadbuffer
and bf_getfixedwritebuffer */
#define Py_TPFLAGS_HAVE_GETFIXEDBUFFER (1L<<15)
This flag would be included in Py_TPFLAGS_DEFAULT:
#define Py_TPFLAGS_DEFAULT ( \
....
Py_TPFLAGS_HAVE_GETSAFEBUFFER | \
Py_TPFLAGS_HAVE_GETFIXEDBUFFER | \
....
0)
@ -63,27 +63,27 @@ Implementation
Extend the PyBufferProcs structure by new fields in
Include/object.h:
typedef size_t (*getsafereadbufferproc)(PyObject *, void **);
typedef size_t (*getsafewritebufferproc)(PyObject *, void **);
typedef size_t (*getfixedreadbufferproc)(PyObject *, void **);
typedef size_t (*getfixedwritebufferproc)(PyObject *, void **);
typedef struct {
getreadbufferproc bf_getreadbuffer;
getwritebufferproc bf_getwritebuffer;
getsegcountproc bf_getsegcount;
getcharbufferproc bf_getcharbuffer;
/* safe buffer interface functions */
getsafereadbufferproc bf_getsafereadbufferproc;
getsafewritebufferproc bf_getsafewritebufferproc;
/* fixed buffer interface functions */
getfixedreadbufferproc bf_getfixedreadbufferproc;
getfixedwritebufferproc bf_getfixedwritebufferproc;
} PyBufferProcs;
The new fields are present if the Py_TPFLAGS_HAVE_GETSAFEBUFFER
The new fields are present if the Py_TPFLAGS_HAVE_GETFIXEDBUFFER
flag is set in the object's type.
The Py_TPFLAGS_HAVE_GETSAFEBUFFER flag implies the
The Py_TPFLAGS_HAVE_GETFIXEDBUFFER flag implies the
Py_TPFLAGS_HAVE_GETCHARBUFFER flag.
The getsafereadbufferproc and getsafewritebufferproc functions
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
- either because an error occurs or no memory block is exposed -
@ -91,21 +91,21 @@ Implementation
The return value is undefined in these cases and should not be
used.
Usually the getsafewritebufferproc and getsafereadbufferproc
Usually the getfixedwritebufferproc and getfixedreadbufferproc
functions aren't called directly, they are called through
convenience functions declared in Include/abstract.h:
int PyObject_AsSafeReadBuffer(PyObject *obj,
int PyObject_AsFixedReadBuffer(PyObject *obj,
void **buffer,
size_t *buffer_len);
int PyObject_AsSafeWriteBuffer(PyObject *obj,
int PyObject_AsFixedWriteBuffer(PyObject *obj,
void **buffer,
size_t *buffer_len);
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
bytes. On failure, or if the fixed buffer interface is not
implemented by obj, they return -1 and set an exception.
@ -124,21 +124,30 @@ Reference Implementation
Additional Notes/Comments
Python strings, Unicode strings, mmap objects, and maybe other
types would expose the safe buffer interface, but the array type
types would expose the fixed buffer interface, but the array type
would *not*, because its memory block may be reallocated during
its lifetime.
Community Feedback
Greg Ewing doubts the safe buffer interface is needed at all, he
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.
(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. On the
other hand, locking may lead to deadlocks.
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'.
References