diff --git a/pep-3118.txt b/pep-3118.txt index 97438b153..741c63558 100644 --- a/pep-3118.txt +++ b/pep-3118.txt @@ -156,7 +156,7 @@ error). The first variable is the "exporting" object. The second argument is the address to a bufferinfo structure. If view is ``NULL``, then no information is returned but a lock on the memory is still obtained. In this case, the corresponding releasebuffer should also -be called with ``NULL``. +be called with ``NULL``. The third argument indicates what kind of buffer the consumer is prepared to deal with and therefore what kind of buffer the exporter @@ -490,46 +490,42 @@ simple 1-d memory-view object). Its C-structure is :: typedef struct { PyObject_HEAD PyObject *base; - int ndims; - Py_ssize_t *starts; /* slice starts */ - Py_ssize_t *stops; /* slice stops */ - Py_ssize_t *steps; /* slice steps */ + PyBuffer view; } PyMemoryViewObject; -This is functionally similar to the current buffer object except only -a reference to base is kept. The actual memory for base must be -re-grabbed using the buffer-protocol, whenever it is actually -needed (after which it is immediately released). +This is functionally similar to the current buffer object except a +reference to base is kept and the memory view is not re-grabbed. +Thus, this memory view object holds on to the memory of base until it +is deleted. -The getbuffer and releasebuffer for this object use the underlying -base object (adjusted as needed using the slice information). If the -number of dimensions of the base object (or the strides or the size) -has changed when a new view is requested, then the getbuffer will -trigger an error. Methods on the MemoryView object will allow -manual locking and unlocking of the underlying buffer. +The getbuffer and releasebuffer for this object increments and +decrements the lock on base, but passes on the contents of view to the +caller. -This memory-view object will support mult-dimensional slicing and be +This memory-view object will support multi-dimensional slicing and be the first object provided with Python to do so. Slices of the -memory-view object are other memory-view objects. When an "element" -from the memory-view is returned it is always a bytes object whose -format should be interpreted by the format attribute of the memoryview -object. The struct module can be used to "decode" the bytes in Python -if desired. +memory-view object are other memory-view objects with the same base +but with a different view of the base object. + +When an "element" from the memory-view is returned it is always a +bytes object whose format should be interpreted by the format +attribute of the memoryview object. The struct module can be used to +"decode" the bytes in Python if desired. Or the contents can be +passed to a NumPy array or other object consuming the buffer protocol. The Python name will be -``__builtin__.memory`` +``__builtin__.memoryview`` Methods: -| ``lock`` -| ``unlock`` | ``__getitem__`` (will support multi-dimensional slicing) | ``__setitem__`` (will support multi-dimensional slicing) -| ``tobytes`` (obtain a bytes-object of everything in the memory). +| ``tobytes`` (obtain a new bytes-object of a copy of the memory). | ``tolist`` (obtain a "nested" list of the memory. Everything is interpreted into standard Python objects - as the struct module unpack would do). + as the struct module unpack would do -- in fact + it uses struct.unpack to accomplish it). Attributes (taken from the memory of the base object): @@ -552,25 +548,36 @@ description. :: - int PyObject_GetContiguous(PyObject *obj, void **buf, Py_ssize_t *len, - char **format, int writeable, char fortran) + PyObject * PyMemoryView_GetContiguous(PyObject *obj, int buffertype, + char fort) -Return a contiguous chunk of memory representing the buffer. If a -copy is made then return 1. If no copy was needed return 0. If an -error occurred in probing the buffer interface, then return -1. The -contiguous chunk of memory is pointed to by ``*buf`` and the length of -that memory is ``*len``. If writeable is 1, then the returned memory -must be writeable or else an error is raised. Otherwise, the memory -may or may not be writeable. If the object is multi-dimensional, then -if fortran is 'F', the first dimension of the underlying array will -vary the fastest in the buffer. If fortran is 'C', then the last -dimension will vary the fastest (C-style contiguous). If fortran is -'A', then it does not matter and you will get whatever the object -decides is more efficient. If a copy is made, then the memory must be -freed by calling ``PyMem_Free``. +Return a memoryview object to a contiguous chunk of memory represented +by obj. If a copy must be made (because the memory pointed to by obj +is not contiguous), then a new bytes object will be created and become +the base object for the returned memory view object. -PyObject_ReleaseBuffer must be called on obj after you are done with the -memory even if a copy is made. +The buffertype argument can be PyBUF_READ, PyBUF_WRITE, +PyBUF_UPDATEIFCOPY to determine whether the returned buffer should be +READONLY, WRITEABLE, or set to update the original buffer if a copy +must be made. If buffertype is PyBUF_WRITE and the buffer is not +contiguous an error will be raised. In this circumstance, the user +can use PyBUF_UPDATEIFCOPY to ensure that a a writeable temporary +contiguous buffer is returned. The contents of this contiguous buffer +will be copied back into the original object after the memoryview +object is deleted as long as the original object is writeable and +allows setting its memory to "readonly". If this is not allowed by +the original object, then a BufferError is raised. + +If the object is multi-dimensional, then if fortran is 'F', the first +dimension of the underlying array will vary the fastest in the buffer. +If fortran is 'C', then the last dimension will vary the fastest +(C-style contiguous). If fortran is 'A', then it does not matter and +you will get whatever the object decides is more efficient. If a copy +is made, then the memory must be freed by calling ``PyMem_Free``. + +You receive a new reference to the memoryview object which will also +hold a lock on the objects data area (this lock will be released when +the memoryview object is deleted). ::