.\" 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 "Storable 3pm"
.TH Storable 3pm "2020-11-09" "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"
Coro::Storable \- offer a more fine\-grained Storable interface
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Coro::Storable;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements a few functions from the Storable module in a way
so that it cede's more often. Some applications (such as the Deliantra
game server) sometimes need to load large Storable objects without
blocking the server for a long time.
.PP
This is being implemented by using a perlio layer that feeds only small
amounts of data (4096 bytes per call) into Storable, and \f(CW\*(C`Coro::cede\*(C'\fR'ing
regularly (at most 100 times per second by default, though).
.PP
As Storable is not reentrant, this module also wraps most functions of the
Storable module so that only one freeze or thaw is done at any one moment
(and recursive invocations are not currently supported).
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .IP "$ref = thaw $pst" 4
.el .IP "\f(CW$ref\fR = thaw \f(CW$pst\fR" 4
.IX Item "$ref = thaw $pst"
Retrieve an object from the given \f(CW$pst\fR, which must have been created with
\&\f(CW\*(C`Coro::Storable::freeze\*(C'\fR or \f(CW\*(C`Storable::store_fd\*(C'\fR/\f(CW\*(C`Storable::store\*(C'\fR
(sorry, but Storable uses incompatible formats for disk/mem objects).
.Sp
This function will cede regularly.
.ie n .IP "$pst = freeze $ref" 4
.el .IP "\f(CW$pst\fR = freeze \f(CW$ref\fR" 4
.IX Item "$pst = freeze $ref"
Freeze the given scalar into a Storable object. It uses the same format as
\&\f(CW\*(C`Storable::store_fd\*(C'\fR.
.Sp
This functino will cede regularly.
.ie n .IP "$pst = nfreeze $ref" 4
.el .IP "\f(CW$pst\fR = nfreeze \f(CW$ref\fR" 4
.IX Item "$pst = nfreeze $ref"
Same as \f(CW\*(C`freeze\*(C'\fR but is compatible to \f(CW\*(C`Storable::nstore_fd\*(C'\fR (note the
\&\f(CW\*(C`n\*(C'\fR).
.ie n .IP "$pst = blocking_freeze $ref" 4
.el .IP "\f(CW$pst\fR = blocking_freeze \f(CW$ref\fR" 4
.IX Item "$pst = blocking_freeze $ref"
Same as \f(CW\*(C`freeze\*(C'\fR but is guaranteed to block. This is useful e.g. in
\&\f(CW\*(C`Coro::Util::fork_eval\*(C'\fR when you want to serialise a data structure
for use with the \f(CW\*(C`thaw\*(C'\fR function for this module. You cannot use
\&\f(CW\*(C`Storable::freeze\*(C'\fR for this as Storable uses incompatible formats for
memory and file images, and this module uses file images.
.ie n .IP "$pst = blocking_nfreeze $ref" 4
.el .IP "\f(CW$pst\fR = blocking_nfreeze \f(CW$ref\fR" 4
.IX Item "$pst = blocking_nfreeze $ref"
Same as \f(CW\*(C`blocking_freeze\*(C'\fR but uses \f(CW\*(C`nfreeze\*(C'\fR internally.
.ie n .IP "$guard = guard" 4
.el .IP "\f(CW$guard\fR = guard" 4
.IX Item "$guard = guard"
Acquire the Storable lock, for when you want to call Storable yourself.
.Sp
Note that this module already wraps all Storable functions, so there is
rarely the need to do this yourself.
.SH "AUTHOR/SUPPORT/CONTACT"
.IX Header "AUTHOR/SUPPORT/CONTACT"
.Vb 2
\&   Marc A. Lehmann <schmorp@schmorp.de>
\&   http://software.schmorp.de/pkg/Coro.html
.Ve