diff --git a/pep-0574.rst b/pep-0574.rst index 1755f6a51..ed3f13ef7 100644 --- a/pep-0574.rst +++ b/pep-0574.rst @@ -227,16 +227,17 @@ Consumer API class Pickler: def __init__(self, file, protocol=None, ..., buffer_callback=None): """ - If *buffer_callback* is not None, then it is called with a list - of out-of-band buffer views when deemed necessary (this could be - once every buffer, or only after a certain size is reached, - or once at the end, depending on implementation details). The - callback should arrange to store or transmit those buffers without - changing their order. - If *buffer_callback* is None (the default), buffer views are serialized into *file* as part of the pickle stream. + If *buffer_callback* is not None, then it can be called any number + of times with a buffer view. If the callback returns a false value + (such as None), the given buffer is out-of-band; otherwise the + buffer is serialized in-band, i.e. inside the pickle stream. + + The callback should arrange to store or transmit out-of-band buffers + without changing their order. + It is an error if *buffer_callback* is not None and *protocol* is None or smaller than 5. """ @@ -281,20 +282,29 @@ Three new opcodes are introduced: it on the stack. * ``READONLY_BUFFER`` makes a readonly view of the top of the stack. -When pickling encounters a ``PickleBuffer``, there can be four cases: +When pickling encounters a ``PickleBuffer``, that buffer can be considered +in-band or out-of-band depending on the following conditions: -* If a ``buffer_callback`` is given and the ``PickleBuffer`` is writable, - the ``PickleBuffer`` is given to the callback and a ``NEXT_BUFFER`` opcode - is appended to the pickle stream. -* If a ``buffer_callback`` is given and the ``PickleBuffer`` is readonly, - the ``PickleBuffer`` is given to the callback and a ``NEXT_BUFFER`` opcode - is appended to the pickle stream, followed by a ``READONLY_BUFFER`` opcode. -* If no ``buffer_callback`` is given and the ``PickleBuffer`` is writable, - it is serialized into the pickle stream as if it were a ``bytearray`` object. -* If no ``buffer_callback`` is given and the ``PickleBuffer`` is readonly, - it is serialized into the pickle stream as if it were a ``bytes`` object. +* if no ``buffer_callback`` is given, the buffer is in-band; +* if a ``buffer_callback`` is given, it is called with the buffer. If the + callback returns a true value, the buffer is in-band; if the callback + returns a false value, the buffer is out-of-band. -The distinction between readonly and writable buffers is explained below +An in-band buffer is serialized as follows: + +* If the buffer is writable, it is serialized into the pickle stream as if + it were a ``bytearray`` object. +* If the buffer is readonly, it is serialized into the pickle stream as if + it were a ``bytes`` object. + +An out-of-band buffer is serialized as follows: + +* If the buffer is writable, a ``NEXT_BUFFER`` opcode is appended to the + pickle stream. +* If the buffer is readonly, a ``NEXT_BUFFER`` opcode is appended to the + pickle stream, followed by a ``READONLY_BUFFER`` opcode. + +The distinction between readonly and writable buffers is motivated below (see "Mutability").