.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Tangram::Complicity 3pm" .TH Tangram::Complicity 3pm "2020-11-28" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Tangram::Complicity \- How to make Tangram\-friendly classes .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& package YourNastyXSClass; \& \& sub px_freeze { \& return [ (shift)\->gimme_as_perl ]; \& } \& \& sub px_thaw { \& my $class = shift; \& my $self = $class\->new( @_ ); \& } \& \& 1; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBTangram::Complicity\fR does not exist. To make matters worse, it isn't even implemented. This page is a big \s-1FIXME\s0 for the code it refers to. This page merely documents the \s-1API\s0 that classes must implement to be safely stored by \f(CW\*(C`Tangram::Type::Dump::flatten\*(C'\fR. .PP Note that to avoid unnecessary copying of memory structures from A to B, this method operates \*(L"in-place\*(R". .PP So, therefore it is necessary for the reference type used in the return value, to be the same as the one in the real object. This is explained later under \*(L"reftype mismatch\*(R". .PP So \- for instance, for Set::Object objects, which have a \&\f(CW\*(C`px_freeze\*(C'\fR method of: .PP .Vb 4 \& sub px_freeze { \& my $self = shift; \& return $self\->members; \& } \& \& sub px_thaw { \& my $class = shift; \& return $class\->new(@_); \& } .Ve .PP [ note: This differs from the Storable \s-1API\s0 (\f(CW\*(C`STORABLE_freeze\*(C'\fR and \&\f(CW\*(C`STORABLE_thaw\*(C'\fR). This interface is actually reasonably sane \- the Storable \s-1API\s0 required custom \s-1XS\s0 magic for Set::Object, for instance. Which has been implemented, but we've learned the lesson now :) ] .PP In essence, the \f(CW\*(C`px_freeze\*(C'\fR method means \*(L"marshall yourself to pure Perl data types\*(R". Note that different serialisation tools will treat ties, overload and magic remaining on the structure in their own way \- so, create your own type of magic (a la Pixie::Info) if you really want to hang out-of-band information off them. .SS "reftype mismatch" .IX Subsection "reftype mismatch" If you get a \f(CW\*(C`reftype mismatch\*(C'\fR error, it is because your \&\fBYourClass\->px_thaw\fR function returned a different type of reference than the one that was passed to store to \&\fBYourClass\->px_freeze\fR. .PP This restriction only applies to the return value of the constructor \&\f(CW\*(C`px_thaw\*(C'\fR, so this is usually fine. The return value from \&\f(CW\*(C`px_freeze\*(C'\fR will be wrapped in a (blessed) container of the correct reference type, regardless of its return type. .PP ie. your function is called as: .PP .Vb 1 \& %{ $object } = %{ YourClass\->px_thaw(@icicle) }; \& \& @{ $object } = @{ YourClass\->px_thaw(@icicle) }; \& \& ${ $object } = ${ YourClass\->px_thaw(@icicle) }; \& \& *{ $object } = *{ YourClass\->px_thaw(@icicle) }; \& \& my $tmp = YourClass\->px_thaw(@icicle); \& $object = sub { goto $tmp }; .Ve .PP This is an analogy, no temporary object is actually used in the scalar case, for instance; due to the use of tie. .PP The reason for this is to allow for circular and back-references in the data structure; those references that point back point to the real blessed object, so to avoid the overhead of a two-pass algorithm, this restriction is made. This is why the value is passed into STORABLE_thaw as \f(CW$_\fR[0]. For most people, it won't make a difference. .PP However, it \fIdoes\fR have the nasty side effect that serialisers that can't handle all types of pure Perl data structures (such as, all current versions of \s-1YAML\s0) are unable to store blessed scalars (eg, Set::Object's).