clarified pickle version requirements (fixes #186)

This commit is contained in:
Wenzel Jakob 2016-04-30 23:13:03 +02:00
parent 8edfa0c10f
commit 81e0975b82
2 changed files with 9 additions and 7 deletions

View File

@ -1340,13 +1340,15 @@ An instance can now be pickled as follows:
p = Pickleable("test_value")
p.setExtra(15)
data = pickle.dumps(p, -1)
data = pickle.dumps(p, 2)
Note that only the cPickle module is supported on Python 2.7. It is also
important to request usage of the highest protocol version using the ``-1``
argument to ``dumps``. Failure to follow these two steps will lead to important
pybind11 memory allocation routines to be skipped during unpickling, which will
likely cause memory corruption and/or segmentation faults.
Note that only the cPickle module is supported on Python 2.7. The second
argument to ``dumps`` is also crucial: it selects the pickle protocol version
2, since the older version 1 is not supported. Newer versions are also fine—for
instance, specify ``-1`` to always use the latest available version. Beware:
failure to follow these instructions will cause important pybind11 memory
allocation routines to be skipped during unpickling, which will likely lead to
memory corruption and/or segmentation faults.
.. seealso::

View File

@ -14,7 +14,7 @@ p = Pickleable("test_value")
p.setExtra1(15)
p.setExtra2(48)
data = pickle.dumps(p, -1) # -1 is important (use highest protocol version)
data = pickle.dumps(p, 2) # Must use pickle protocol >= 2
print("%s %i %i" % (p.value(), p.extra1(), p.extra2()))
p2 = pickle.loads(data)