.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CPS::Governor::Deferred 3pm"
.TH CPS::Governor::Deferred 3pm "2022-06-30" "perl v5.34.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"
"CPS::Governor::Deferred" \- iterate at some later point
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use CPS qw( gkforeach );
\& use CPS::Governor::Deferred;
\&
\& my $gov = CPS::Governor::Deferred\->new;
\&
\& gkforeach( $gov, [ 1 .. 10 ],
\&    sub { 
\&       my ( $item, $knext ) = @_;
\&
\&       print "A$item ";
\&       goto &$knext;
\&    },
\&    sub {},
\& );
\&
\& gkforeach( $gov, [ 1 .. 10 ],
\&    sub {
\&       my ( $item, $knext ) = @_;
\&
\&       print "B$item ";
\&       goto &$knext;
\&    },
\&    sub {},
\& );
\&
\& $gov\->flush;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This CPS::Governor allows the functions using it to delay their iteration
until some later point when the containing program invokes it. This allows two
main advantages:
.IP "\(bu" 4
CPU-intensive operations may be split apart and mixed with other \s-1IO\s0 operations
.IP "\(bu" 4
Multiple control functions may be executed in pseudo-parallel, interleaving
iterations of each giving a kind of concurrency
.PP
These are achieved by having the governor store a list of code references that
need to be invoked, rather than invoking them immediately. These references
can then be invoked later, perhaps by using an idle watcher in an event
framework.
.PP
Because each code reference hasn't yet been invoked by the time the \f(CW\*(C`again\*(C'\fR
method is called, the original caller is free to store more pending references
with the governor. This allows multiple control functions to be interleaved,
as in the \f(CW\*(C`A\*(C'\fR and \f(CW\*(C`B\*(C'\fR example above.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .SS "$gov = CPS::Governor::Deferred\->new( %args )"
.el .SS "\f(CW$gov\fP = CPS::Governor::Deferred\->new( \f(CW%args\fP )"
.IX Subsection "$gov = CPS::Governor::Deferred->new( %args )"
Returns a new instance of a \f(CW\*(C`CPS::Governor::Deferred\*(C'\fR object. Requires no
parameters but may take any of the following to adjust its default behaviour:
.IP "defer_after => \s-1INT\s0" 8
.IX Item "defer_after => INT"
If given some positive number, \f(CW$n\fR then the first \f(CW\*(C`$n\-1\*(C'\fR invocations of the
\&\f(CW\*(C`again\*(C'\fR method will in fact be executed immediately. Thereafter they will be
enqueued in the normal mechanism. This gives the effect that longrunning loops
will be executed in batches of \f(CW$n\fR.
.Sp
If not supplied then every invocation of \f(CW\*(C`again\*(C'\fR will use the queueing
mechanism.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$pending = $gov\->is_pending"
.el .SS "\f(CW$pending\fP = \f(CW$gov\fP\->is_pending"
.IX Subsection "$pending = $gov->is_pending"
Returns true if at least one code reference has been stored that hasn't yet
been invoked.
.ie n .SS "$gov\->prod"
.el .SS "\f(CW$gov\fP\->prod"
.IX Subsection "$gov->prod"
Invokes all of the currently-stored code references, in the order they were
stored. If any new references are stored by these, they will not yet be
invoked, but will be available for the next time this method is called.
.ie n .SS "$gov\->flush"
.el .SS "\f(CW$gov\fP\->flush"
.IX Subsection "$gov->flush"
Repeatedly calls \f(CW\*(C`prod\*(C'\fR until no more code references are pending.
.SH "SUBCLASS METHODS"
.IX Header "SUBCLASS METHODS"
The following methods are used internally to implement the functionality,
which may be useful to implementors of subclasses.
.ie n .SS "$gov\->later( $code, @args )"
.el .SS "\f(CW$gov\fP\->later( \f(CW$code\fP, \f(CW@args\fP )"
.IX Subsection "$gov->later( $code, @args )"
Used to enqueue the \f(CW$code\fR ref to be invoked later with the given \f(CW@args\fR,
once it is determined this should be deferred (rather than being invoked
immediately in the case of the first few invocations when \f(CW\*(C`defer_after\*(C'\fR is
set).
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>