摘要

本 PEP 提议标准化一个新的 pickle 协议版本，以及随附的 API 以充分利用它

1. 一个新的 pickle 协议版本 (5) 以涵盖带外数据缓冲区所需的额外元数据。
2. 一种新的 PickleBuffer 类型，用于 __reduce_ex__ 实现以返回带外数据缓冲区。
3. 在 pickle 时添加一个新的 buffer_callback 参数，用于处理带外数据缓冲区。
4. 在 unpickle 时添加一个新的 buffers 参数，用于提供带外数据缓冲区。

本 PEP 保证未修改的 API 的行为不变。

基本原理

pickle 协议最初设计于 1995 年，用于在磁盘上持久化任意 Python 对象。1995 年的存储介质性能可能使得在将临时数据写入磁盘之前复制时，关注 RAM 带宽等性能指标变得无关紧要。

如今，pickle 协议在许多应用程序中得到了越来越多的使用，其中大部分数据从未持久化到磁盘（或者，即使持久化，也使用可移植格式而不是 Python 特定格式）。相反，pickle 被用于在同一台机器或多台机器上的进程之间传输数据和命令。这些应用程序有时会处理非常大的数据（例如 Numpy 数组或 Pandas 数据帧），需要进行传输。对于这些应用程序，pickle 目前是浪费的，因为它对要序列化的数据施加了虚假的内存复制。

事实上，标准 multiprocessing 模块使用 pickle 进行序列化，因此在将大数据发送到另一个进程时也会遇到此问题。

第三方 Python 库，例如 Dask [1]、PyArrow [4] 和 IPyParallel [3]，已经开始实现替代的序列化方案，明确目标是避免大数据上的复制。实现新的序列化方案很困难，并且通常会导致通用性降低（因为许多 Python 对象支持 pickle 但不支持新的序列化方案）。回退到 pickle 来处理不支持的类型是一个选项，但这样你就会回到你最初想要避免的虚假内存复制。例如，dask 能够避免 Numpy 数组及其内置容器（例如包含 Numpy 数组的列表或字典）的内存复制，但如果一个大型 Numpy 数组是用户定义对象的属性，dask 将用户定义对象序列化为 pickle 流，从而导致内存复制。

这些第三方序列化工作的共同主题是生成对象元数据流（其中包含关于要序列化对象的类似 pickle 的信息）和用于大型对象有效负载的单独的零拷贝缓冲区对象流。请注意，在此方案中，整数等小对象可以与元数据流一起转储。改进可以包括根据大型数据的类型和布局进行机会性压缩，就像 dask 所做的那样。

本 PEP 旨在使 pickle 能够以一种将大数据作为单独的零拷贝缓冲区流处理的方式使用，从而让应用程序以最佳方式处理这些缓冲区。

示例

为了简化示例并避免需要了解第三方库，我们这里将重点放在 bytearray 对象上（但对于更复杂的对象，如 Numpy 数组，问题在概念上是相同的）。与大多数对象一样，bytearray 对象不能立即被 pickle 模块理解，因此必须指定其分解方案。

以下是 bytearray 对象当前如何分解以进行 pickle 的方式

>>> b.__reduce_ex__(4)
(<class 'bytearray'>, (b'abc',), None)

这是因为 bytearray.__reduce_ex__ 的实现基本上如下：

class bytearray:

   def __reduce_ex__(self, protocol):
      if protocol == 4:
         return type(self), bytes(self), None
      # Legacy code for earlier protocols omitted

反过来，它生成以下 pickle 代码

>>> pickletools.dis(pickletools.optimize(pickle.dumps(b, protocol=4)))
    0: \x80 PROTO      4
    2: \x95 FRAME      30
   11: \x8c SHORT_BINUNICODE 'builtins'
   21: \x8c SHORT_BINUNICODE 'bytearray'
   32: \x93 STACK_GLOBAL
   33: C    SHORT_BINBYTES b'abc'
   38: \x85 TUPLE1
   39: R    REDUCE
   40: .    STOP

（上面对 pickletools.optimize 的调用仅旨在通过删除 MEMOIZE 操作码使 pickle 流更具可读性）

我们可以注意到关于 bytearray 的有效负载（字节序列 b'abc'）的几点：

• bytearray.__reduce_ex__ 通过从 bytearray 的数据实例化一个新的 bytes 对象来产生第一次复制。
• pickle.dumps 在 SHORT_BINBYTES 操作码之后将该 bytes 对象的内容插入 pickle 流时产生第二次复制。
• 此外，在反序列化 pickle 流时，当遇到 SHORT_BINBYTES 操作码时会创建一个临时 bytes 对象（导致数据复制）。

我们真正想要的是以下内容：

• bytearray.__reduce_ex__ 产生一个 bytearray 数据的 视图。
• pickle.dumps 不会尝试将该数据复制到 pickle 流中，而是将缓冲区视图传递给其调用者（调用者可以决定如何最有效地处理该缓冲区）。
• 在反序列化时，pickle.loads 分别获取 pickle 流和缓冲区视图，并将缓冲区视图直接传递给 bytearray 构造函数。

我们看到上述功能需要几个条件

• __reduce__ 或 __reduce_ex__ 必须能够返回 某种东西 来指示可序列化的无复制缓冲区视图。
• pickle 协议必须能够表示对此类缓冲区视图的引用，指示 unpickler 可能需要从带外获取实际缓冲区。
• pickle.Pickler API 必须为其调用者提供一种在序列化时接收此类缓冲区视图的方法。
• pickle.Unpickler API 必须类似地允许其调用者提供反序列化所需的缓冲区视图。
• 为了兼容性，pickle 协议还必须能够包含此类缓冲区视图的直接序列化，以便如果当前的 pickle API 使用不涉及内存复制，则无需修改。

生产者 API

我们引入了一种新类型 pickle.PickleBuffer，它可以从任何支持缓冲区的对象实例化，并且专门用于从 __reduce__ 实现返回

class bytearray:

   def __reduce_ex__(self, protocol):
      if protocol >= 5:
         return type(self), (PickleBuffer(self),), None
      # Legacy code for earlier protocols omitted

PickleBuffer 是一个简单的包装器，不具备所有 memoryview 的语义和功能，但在启用协议 5 或更高版本时，pickle 模块会专门识别它。尝试使用 pickle 协议版本 4 或更早版本序列化 PickleBuffer 将会报错。

pickle 模块只会考虑 PickleBuffer 的原始 数据。任何类型特定的 元数据 (例如形状或数据类型) 必须由该类型的 __reduce__ 实现单独返回，就像目前的情况一样。

消费者 API

pickle.Pickler.__init__ 和 pickle.dumps 增加了额外的 buffer_callback 参数

class Pickler:
   def __init__(self, file, protocol=None, ..., buffer_callback=None):
      """
      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.
      """

def pickle.dumps(obj, protocol=None, *, ..., buffer_callback=None):
   """
   See above for *buffer_callback*.
   """

pickle.Unpickler.__init__ 和 pickle.loads 增加了额外的 buffers 参数

class Unpickler:
   def __init__(file, *, ..., buffers=None):
      """
      If *buffers* is not None, it should be an iterable of buffer-enabled
      objects that is consumed each time the pickle stream references
      an out-of-band buffer view.  Such buffers have been given in order
      to the *buffer_callback* of a Pickler object.

      If *buffers* is None (the default), then the buffers are taken
      from the pickle stream, assuming they are serialized there.
      It is an error for *buffers* to be None if the pickle stream
      was produced with a non-None *buffer_callback*.
      """

def pickle.loads(data, *, ..., buffers=None):
   """
   See above for *buffers*.
   """

协议变更

引入了三个新的操作码

• BYTEARRAY8 从 pickle 流中紧随其后的数据创建一个 bytearray 并将其推送到堆栈上（就像 BINBYTES8 对 bytes 对象所做的那样）；
• NEXT_BUFFER 从 buffers 可迭代对象中获取一个缓冲区并将其推送到堆栈。
• READONLY_BUFFER 对堆栈顶部创建一个只读视图。

当 pickling 遇到 PickleBuffer 时，该缓冲区可以被视为带内或带外，具体取决于以下条件：

• 如果没有给出 buffer_callback，则缓冲区是带内的；
• 如果给定了 buffer_callback，则使用缓冲区调用它。如果回调返回一个真值，则缓冲区是带内的；如果回调返回一个假值，则缓冲区是带外的。

带内缓冲区序列化如下

• 如果缓冲区是可写的，则将其序列化到 pickle 流中，就像它是一个 bytearray 对象一样。
• 如果缓冲区是只读的，则将其序列化到 pickle 流中，就像它是一个 bytes 对象一样。

带外缓冲区序列化如下

• 如果缓冲区是可写的，则将 NEXT_BUFFER 操作码附加到 pickle 流中。
• 如果缓冲区是只读的，则将 NEXT_BUFFER 操作码附加到 pickle 流中，后跟一个 READONLY_BUFFER 操作码。

可读写缓冲区和只读缓冲区之间的区别将在下面解释（参见“可变性”）。

副作用

注意事项

class ndarray:

   def __reduce_ex__(self, protocol):
      if protocol == 5:
         return numpy.frombuffer, (PickleBuffer(self), self.dtype)
      # Legacy code for earlier protocols omitted

>>> import numpy as np
>>> a = np.zeros(10)
>>> a[0]
0.0
>>> buffers = []
>>> data = pickle.dumps(a, protocol=5, buffer_callback=buffers.append)
>>> b = pickle.loads(data, buffers=buffers)
>>> b[0] = 42
>>> a[0]
42.0

被拒绝的替代方案

class MyPickle(pickle.Pickler):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.buffers = []

    def persistent_id(self, obj):
        if type(obj) is not bytearray:
            return None
        else:
            index = len(self.buffers)
            self.buffers.append(obj)
            return ('bytearray', index)


class MyUnpickle(pickle.Unpickler):

    def __init__(self, *args, buffers, **kwargs):
        super().__init__(*args, **kwargs)
        self.buffers = buffers

    def persistent_load(self, pid):
        type_tag, index = pid
        if type_tag == 'bytearray':
            return self.buffers[index]
        else:
            assert 0  # unexpected type

实施

PEP 最初由作者在其 GitHub fork [6] 中实现。后来它被合并到 Python 3.8 [7] 中。

Python 3.6 和 3.7 的向后移植版本可从 PyPI 下载 [8]。

对 pickle 协议 5 和带外缓冲区的支持已添加到 Numpy [11] 中。

对 pickle 协议 5 和带外缓冲区的支持已添加到 Apache Arrow Python 绑定 [9] 中。

相关工作

Dask.distributed 实现了一个自定义的零拷贝序列化，并支持回退到 pickle [2]。

PyArrow 为少数选定类型实现了基于组件的零拷贝序列化 [5]。

PEP 554 提议在单个进程中托管多个解释器，并提供将缓冲区在解释器之间传输作为通信方案的规定。

致谢

感谢以下人员的早期反馈：Alyssa Coghlan、Olivier Grisel、Stefan Krah、MinRK、Matt Rocklin、Eric Snow。

感谢 Pierre Glaser 和 Olivier Grisel 对实现进行实验。

参考资料

版权

本文档已进入公共领域。