| … | |
… | |
| 139 | see if it's C<1> (true), C<0> (false) or C<undef> (error). |
139 | see if it's C<1> (true), C<0> (false) or C<undef> (error). |
| 140 | |
140 | |
| 141 | While it is possible to use an isa test, directly comparing stash pointers |
141 | While it is possible to use an isa test, directly comparing stash pointers |
| 142 | is faster and guaranteed to work. |
142 | is faster and guaranteed to work. |
| 143 | |
143 | |
|
|
144 | =head1 A GENERIC OBJECT SERIALIATION PROTOCOL |
|
|
145 | |
|
|
146 | This section explains the object serialisation protocol used by |
|
|
147 | L<CBOR::XS>. It is meant to be generic enough to support any kind of |
|
|
148 | generic object serialiser. |
|
|
149 | |
|
|
150 | This protocol is called "the Types::Serialiser object serialisation |
|
|
151 | protocol". |
|
|
152 | |
|
|
153 | =head2 ENCODING |
|
|
154 | |
|
|
155 | When the encoder encounters an object that it cannot otherwise encode (for |
|
|
156 | example, L<CBOR::XS> can encode a few special types itself, and will first |
|
|
157 | attempt to use the special C<TO_CBOR> serialisation protocol), it will |
|
|
158 | look up the C<FREEZE> method on the object. |
|
|
159 | |
|
|
160 | If it exists, it will call it with two arguments: the object to |
|
|
161 | serialise, and a constant string that indicates the name of the |
|
|
162 | serialisationformat. For example L<CBOR::XS> uses C<CBOR>, and L<JSON> and |
|
|
163 | L<JSON::XS> (or any other JSON serialiser), would use C<JSON> as second |
|
|
164 | argument. |
|
|
165 | |
|
|
166 | The C<FREEZE> method can then return zero or more values to identify the |
|
|
167 | object instance. The serialiser is then supposed to encode the class name |
|
|
168 | and all of these return values (which must be encodable in the format) |
|
|
169 | using the relevant form for perl objects. In CBOR for example, there is a |
|
|
170 | registered tag number for encoded perl objects. |
|
|
171 | |
|
|
172 | =head2 DECODING |
|
|
173 | |
|
|
174 | When the decoder then encounters such an encoded perl object, it should |
|
|
175 | look up the C<THAW> method on the stored classname, and invoke it with the |
|
|
176 | classname, the constant string to identify the format, and all the return |
|
|
177 | values returned by C<FREEZE>. |
|
|
178 | |
|
|
179 | =head2 EXAMPLES |
|
|
180 | |
|
|
181 | See the C<OBJECT SERIALISATION> section in the L<CBOR::XS> manpage for |
|
|
182 | more details, an example implementation, and code examples. |
|
|
183 | |
|
|
184 | Here is an example C<FREEZE>/C<THAW> method pair: |
|
|
185 | |
|
|
186 | sub My::Object::FREEZE { |
|
|
187 | my ($self, $serialiser) = @_; |
|
|
188 | |
|
|
189 | ($self->{type}, $self->{id}, $self->{variant}) |
|
|
190 | } |
|
|
191 | |
|
|
192 | sub My::Object::THAW { |
|
|
193 | my ($class, $serialiser, $type, $id, $variant) = @_; |
|
|
194 | |
|
|
195 | $class-<new (type => $type, id => $id, variant => $variant) |
|
|
196 | } |
|
|
197 | |
| 144 | =head1 BUGS |
198 | =head1 BUGS |
| 145 | |
199 | |
| 146 | The use of L<overload> makes this module much heavier than it should be |
200 | The use of L<overload> makes this module much heavier than it should be |
| 147 | (on my system, this module: 4kB RSS, overload: 260kB RSS). |
201 | (on my system, this module: 4kB RSS, overload: 260kB RSS). |
| 148 | |
202 | |
