/usr/share/gap/pkg/io/doc/chap5.txt is in gap-io 4.5.1+ds-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 |
[1X5 [33X[0;0YObject serialisation (Pickling)[133X[101X
[33X[0;0YThe idea of [21Xobject serialisation[121X is that one wants to store nearly arbitrary
[5XGAP[105X objects to disk or transfer them over the network. To this end, one
wants to convert them to a byte stream that is platform independent and can
later be converted back to a copy of the same object in memory, be it in the
same [5XGAP[105X process or another one maybe even on another machine. The main
problem here are the vast amount of different types occurring in [5XGAP[105X and the
possibly highly self-referential structure of [5XGAP[105X objects.[133X
[33X[0;0YThe [5XIO[105X package contains a framework to implement object serialisation and
implementations for most of the basic data types in [5XGAP[105X. The framework is
easily extendible to other types and takes complete care of self-references
and corresponding problems. It builds upon the buffered I/O functions
described in Section [14X4[114X. We start by describing the user interface.[133X
[1X5.1 [33X[0;0YResult objects[133X[101X
[33X[0;0YThe following static objects are used to report about success or failure of
the (un-)pickling operations:[133X
[1X5.1-1 IO_Error[101X
[33X[1;0Y[29X[2XIO_Error[102X[32X global variable[133X
[33X[0;0YThis object is returned if an error occurs.[133X
[1X5.1-2 IO_Nothing[101X
[33X[1;0Y[29X[2XIO_Nothing[102X[32X global variable[133X
[33X[0;0YThis object is returned when there is nothing to return, for example if an
unpickler (see [2XIO_Unpickle[102X ([14X5.2-2[114X)) encounters the end of a file.[133X
[1X5.1-3 IO_OK[101X
[33X[1;0Y[29X[2XIO_OK[102X[32X global variable[133X
[33X[0;0YThis object is returned if everything went well and there is no other
canonical value to return to indicate this.[133X
[33X[0;0YThe only thing you can do with these special values is to compare them to
each other and to other objects.[133X
[1X5.2 [33X[0;0YPickling and unpickling[133X[101X
[1X5.2-1 IO_Pickle[101X
[33X[1;0Y[29X[2XIO_Pickle[102X( [3Xf[103X, [3Xob[103X ) [32X operation[133X
[6XReturns:[106X [33X[0;10Y[10XIO_OK[110X or [10XIO_Error[110X[133X
[33X[0;0YThe argument [3Xf[103X must be an open, writable [10XFile[110X object. The object [3Xob[103X can be
an arbitrary [5XGAP[105X object. The operation [21Xpickles[121X or [21Xserialises[121X the object [3Xob[103X
and writes the result into the [10XFile[110X object [3Xf[103X. If everything is OK, the
unique value [10XIO_OK[110X is returned and otherwise the unique value [10XIO_Error[110X. The
resulting byte stream can be read again using the operation [2XIO_Unpickle[102X
([14X5.2-2[114X) and is platform- and architecture independent. Especially the
question whether a system has 32 bit or 64 bit wide words and the question
of endianess does not matter.[133X
[33X[0;0YNote that not all of [5XGAP[105X's object types are supported but it is relatively
easy to extend the system. This package supports in particular boolean
values, integers, permutations, rational numbers, finite field elements,
cyclotomics, strings, polynomials, rational functions, lists, records,
compressed vectors and matrices over finite fields (objects are uncompressed
in the byte stream but recompressed during unpickling), and straight line
programs.[133X
[33X[0;0YSelf-referential objects built from records and lists are handled correctly
and are restored completely with the same self-references during unpickling.[133X
[1X5.2-2 IO_Unpickle[101X
[33X[1;0Y[29X[2XIO_Unpickle[102X( [3Xf[103X ) [32X operation[133X
[6XReturns:[106X [33X[0;10Y[10XIO_Error[110X or a [5XGAP[105X object[133X
[33X[0;0YThe argument [3Xf[103X must be an open, readable [10XFile[110X object. The operation reads
from [3Xf[103X and [21Xunpickles[121X the next object. If an error occurs, the unique value
[10XIO_Error[110X is returned. If the [10XFile[110X object is at end of file, the value
[10XIO_Nothing[110X is returned. Note that these two values are not picklable,
because of their special meaning as return values of this operation here.[133X
[1X5.2-3 IO_ClearPickleCache[101X
[33X[1;0Y[29X[2XIO_ClearPickleCache[102X( ) [32X function[133X
[6XReturns:[106X [33X[0;10YNothing[133X
[33X[0;0YThis function clears the [21Xpickle cache[121X. This cache stores all object pickled
in the current recursive call to [2XIO_Pickle[102X ([14X5.2-1[114X) and is necessary to
handle self-references. Usually it is not necessary to call this function
explicitly. Only in the rare case (that should not happen) that a pickling
or unpickling operation enters a break loop which is left by the user, the
pickle cache has to be cleared explicitly using this function for later
calls to [2XIO_Pickle[102X ([14X5.2-1[114X) and [2XIO_Unpickle[102X ([14X5.2-2[114X) to work![133X
[1X5.3 [33X[0;0YExtending the pickling framework[133X[101X
[33X[0;0YThe framework can be extended for other [5XGAP[105X object types as follows:[133X
[33X[0;0YFor pickling, a method for the operation [2XIO_Pickle[102X ([14X5.2-1[114X) has to be
installed which does the work. If the object to be pickled has subobjects,
then the first action of the method is to call the function [10XIO_AddToPickled[110X
with the object as argument. This will put it into the pickle cache and take
care of self-references. Arbitrary subobjects can then be pickled using
recursive calls to the operation [2XIO_Pickle[102X ([14X5.2-1[114X) handing down the same
[10XFile[110X object into the recursion. The method must either return [10XIO_Error[110X in
case of an error or [10XIO_OK[110X if everything goes well. Before returning, a
method that has called [10XIO_AddToPickled[110X must call the function
[10XIO_FinalizePickled[110X without arguments [13Xunder all circumstances[113X. If this call
is missing, global data for the pickling procedure becomes corrupt![133X
[33X[0;0YEvery pickling method must first write a 4 byte magic value such that later
during unpickling of the byte stream the right unpickling method can be
called (see below). Then it can write arbitrary data, however, this data
should be platform- and architecture independent, and it must be possible to
unpickle it later without [21Xlookahead[121X.[133X
[33X[0;0YPickling methods should usually not go into a break loop, because after
leaving the user has to call [2XIO_ClearPickleCache[102X ([14X5.2-3[114X) explicitly![133X
[33X[0;0YUnpickling is implemented as follows: For every 4 byte magic value there
must be a function bound to that value in the record [10XIO_Unpicklers[110X. If the
unpickling operation [2XIO_Unpickle[102X ([14X5.2-2[114X) encounters that magic value, it
calls the corresponding unpickling function. This function just gets one
[10XFile[110X object as argument. Since the magic value is already read, it can
immediately start with reading and rebuilding the serialised object in
memory. The method has to take care to restore the object including its type
completely.[133X
[33X[0;0YIf an object type has subobjects, the unpickling function has to first
create a skeleton of the object without its subobjects, then call
[10XIO_AddToUnpickled[110X on this skeleton, [13Xbefore[113X unpickling subobjects. If things
are not done in this order, the handling of self-references down in the
recursion will not work! An unpickling function that has called
[10XIO_AddToUnpickled[110X at the beginning has to call [10XIO_FinalizeUnpickled[110X without
arguments before returning [13Xunder all circumstances[113X! If this call is missing,
global data for the unpickling procedure becomes corrupt![133X
[33X[0;0YOf course, unpickling functions can recursively call [2XIO_Unpickle[102X ([14X5.2-2[114X) to
unpickle subobjects. Apart from this, unpickling functions can use arbitrary
reading functions on the [10XFile[110X object. However, they should only read
sequentially and never move the current file position pointer otherwise. An
unpickling function should return the newly created object or the value
[10XIO_Error[110X if an error occurred. They should never go into a break loop,
because after leaving the user has to call [2XIO_ClearPickleCache[102X ([14X5.2-3[114X)
explicitly![133X
[33X[0;0YPerhaps the best way to learn how to extend the framework is to study the
code for the basic [5XGAP[105X objects in the file [11Xpkg/io/gap/pickle.gi[111X.[133X
|