NAME
Ekorn::Pipeline::Feed - one run, fed values as they arrive
SYNOPSIS
use Ekorn::Pipeline;
my $feed = Ekorn::Pipeline->new(@stages)->feed;
# Wherever values arrive: a library's callback, an event, a stage
for my $value (@values) {
my @results = $feed->push($value); # what came out of it
last if defined $feed->ended; # a stage stopped the run
}
my @rest = $feed->close unless defined $feed->ended; # the flushes'
DESCRIPTION
A feed is one run of a pipeline's stages, which you give values as they arrive, rather than all at once, as a pushed run takes them, or when a result is wanted, as an iterator asks its source. It's made by "feed" in Ekorn::Pipeline, not by calling new.
Each "push" runs its values through the stages, and returns what came out of them, there and then. "close" says no more values are coming: the flushes are called, and what they give is returned, and then the ends. Between the two, the run goes on as a run does, with its gather stages' state kept from one push to the next, so take(5) takes five values from all that are pushed, and batch(3) fills its batches across pushes. Fed the same values, a feed gives what $pipeline->(@values) gives, in the same order, but a push at a time.
That's what makes it possible to run a pipeline where the values don't come from you:
A library that calls you back, for each row, record, line or file it finds, or an event loop, for each message. The callback pushes, and when a stage has stopped the run, as
takedoes, it tells the library to stop.A stage with a branch of its own: a stage made with Ekorn::Pipeline::Gather can make a feed for each run, and push its values into another pipeline, closing it in its flush and finishing it in its end. A tee, running each value through a branch of stages for their side effects and passing it on unchanged, is one; a stage running each key's values through a run of its own is another. The user guide, Ekorn::Pipeline::Manual::HowTo, builds both.
A writer that's given values as a program makes them, and batches, counts or commits them through stages, its flushes and ends seeing the run through however it ends.
How a feed ends
A feed's run ends in one of four ways, and "ended" says how, once it has:
"close": the flushes are called, then the ends, each told
done, orstoppedif a flush's stop cut its input short.endedgivesdone: the input was read to its end, as an iterator'sendedsays once its source has run out.A stop, from a stage, a flush or a sink, such as
take's: it ends the run in the push that meets it. The values it carries go on, the flushes of the stages after it are called, then every end, and that push returns all of it.endedgivesstopped.A stage, a flush or an end that dies: the push or close dies with it, named as a run names it, and each end is told
died.endedgivesdied."finish", or letting the feed go: no flush is called, and each end is told
stopped, ordoneif its input had run out.endedgivesstopped.
Once the run has ended, however it ended, a push or a close croaks, so values can't go nowhere unnoticed. So a caller feeding values as they arrive asks ended after each push, and stops when it's defined.
A feed has no context of its own. Its stages and ends see the context of the code pushing into it, through "run_context" in Ekorn::Pipeline: none, pushed from outside any run, or, pushed from a stage, that stage's run's, such as a statement's columns. So a stage that feeds a branch passes its run's context on to it. A push, a close or a finish from inside the feed's own run, such as from one of its stages, croaks: a stage can push into another pipeline's feed, but not its own.
METHODS
new
Feeds are made by "feed" in Ekorn::Pipeline, not by calling new.
push
my @results = $feed->push(@values);
my $results = $feed->push(@values); # the same, as an array reference
Runs @values through the stages, each through every stage before the next, and returns what came out of them, in order: a list, or, in scalar context, an array reference. A value a stage drops gives nothing, and one a stage turns into several gives them all. A value held back, as batch holds values, comes out of a later push, or of "close". A sink's result isn't among them: "close" gives it.
If a stage stops the run, the push returns what came out before the stop, the values the stop carried, through the stages after it, and what the flushes after it give; the values after the one that met the stop are dropped. If a stage dies, the push dies with it.
close
my @rest = $feed->close;
my $rest = $feed->close; # the same, as an array reference
Ends the input, as a source running out does: calls the flushes, in order, and returns what they give, through the stages after them, and a sink's result, in a list, or, in scalar context, an array reference, as an iterator's all does at the end of its run. Then the ends are called.
finish
$feed->finish;
Ends the run now, as from outside, if it hasn't ended: nothing waiting goes on, no flush is called, and each end is told how the run ended from where it stands: stopped, if its input hadn't run out. After a run has ended, it does nothing. A feed let go before it's closed is finished as the last reference to it goes, as an iterator let go is.
ended
my $how = $feed->ended;
Returns how the run ended: done, stopped or died, as "How a feed ends" describes; while it's open, nothing.
DIAGNOSTICS
- Expected a feed still open, but its run has ended: %s
-
A "push" or "close" came after the feed's run had ended, for the reason given: it was closed; it was finished; a stage stopped it; or it died. Ask "ended" after each push, and stop pushing once it's defined.
- Expected no %s of a feed from inside its own run
-
A "push", "close" or "finish" was called from inside the feed's own run: from one of its stages, flushes or ends. It's reported as that stage's error.
SEE ALSO
Ekorn::Pipeline, Ekorn::Pipeline::Iterator, Ekorn::Pipeline::Gather
AUTHOR
Iain Campbell <cpanic@cpan.org>
LICENSE
Copyright (c) 2024-2026 by Iain Campbell.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.