CPS::G...eferred(3pm)

✨ CPS::Governor::Deferred ✨

okay bestie, welcome to CPS::Governor::Deferred — that's a Perl module, part of the CPS fam, living its best life in section 3pm of the user-contributed Perl docs 💅

the whole vibe: iterate at some later point. not now. later. whenever the containing program says so 🦋

---

🌸 SYNOPSIS 🌸

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;

---

💖 DESCRIPTION 💖

so here's the tea ☕ — this CPS::Governor lets the functions using it delay their iteration until some later point, specifically the point where the containing program invokes it. and that gives you two absolutely iconic advantages:

• CPU-intensive operations may be split apart and mixed with other IO operations 🔥
• Multiple control functions may be executed in pseudo-parallel, interleaving iterations of each, giving a kind of concurrency 👑

the way it pulls this off is lowkey genius: the governor stores a list of code references that need to be invoked, instead of invoking them immediately. then those references can get invoked later — maybe by an idle watcher in an event framework, iykyk ✨

and because each code reference hasn't been invoked yet by the time the again method is called, the original caller is free to store more pending references with the governor. that's literally what lets multiple control functions interleave, like the A and B example up there 🎀

---

🫶 CONSTRUCTOR 🫶

$gov = CPS::Governor::Deferred->new( %args )

returns a shiny new instance of a CPS::Governor::Deferred object 🌈 requires no parameters, but it may take any of the following to adjust its default behaviour:

• defer_after => INT — if you give it some positive number, $n, then the first $n-1 invocations of the again method will in fact be executed immediately. after that, they get enqueued in the normal mechanism. the effect? longrunning loops get executed in batches of $n 🍓

if you don't supply it, then every single invocation of again will use the queueing mechanism. no shortcuts, no cap.

---

💅 METHODS 💅

$pending = $gov->is_pending

returns true if at least one code reference has been stored that hasn't yet been invoked 👀

$gov->prod

invokes all of the currently-stored code references, in the order they were stored. and if any new references get stored by those, they will not be invoked yet — nope, they'll just be available for the next time this method is called 🙈

$gov->flush

repeatedly calls prod until no more code references are pending. periodt 💅

---

🧚 SUBCLASS METHODS 🧚

these next ones are used internally to implement the functionality, and they may be useful to implementors of subclasses ✨

$gov->later( $code, @args )

used to enqueue the $code ref to be invoked later with the given @args, once it's been determined that this should be deferred — rather than being invoked immediately, which is what happens in the case of the first few invocations when defer_after is set 🌸

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk>

---

ngl bestie, that's the whole page 💀 no skipped sections, no missing flags, we ate and left no crumbs 🍽️✨

this was perl v5.34.0, dated 2022-06-30 — mwah, go forth and defer responsibly 🎀💖🦋