Pipeline(3)

💖 Pipeline — the generic pipeline interface bestie 💖

okay so this is a page from the User Contributed Perl Documentation (that's the manual it lives in, Pipeline(3), section 3, iykyk) and it's genuinely one of my faves. grab a boba, we're doing this 🧋✨

---

🌸 NAME 🌸

Pipeline — the generic pipeline interface. that's it, that's the name, iconic.

---

✨ SYNOPSIS ✨

  use Pipeline;
  my $pipeline = Pipeline->new();
  $pipeline->add_segment( @segments );
  $pipeline->dispatch();

like... look at that. three lines and you're already running a whole pipeline. we love a low-effort queen 💅

---

🦋 DESCRIPTION 🦋

so "Pipelines" are a mechanism to process data. that's the whole vibe. they're designed to be plugged together so that fairly complex operations end up acting in a fairly straightforward manner — cleanly, and simply. no chaos, no mess, just vibes 🌈

---

🎀 USING THE PIPELINE MODULE 🎀

ngl, using the generic pipeline module is fairly simple, bestie. here's the tea:

• you instantiate a Pipeline object by using the new() constructor. that's your entry point, your main character moment.
• segments can be added to the pipeline with the add_segment method.
• the store that the Pipeline will use can be set by calling the store() method later on. if a store is not set by the time a pipeline is executing, then it will use a store of the type Pipeline::Store::Simple. (default queen behaviour 🫶)
• to start the pipeline running, call the dispatch() method on your Pipeline object.

and here's the important lore: if a segment returns a Pipeline::Production object, then the pipeline will be terminated early and the production will be returned to the user. periodt, we're done here.

but — and this is the part people forget 😭 — regardless of when the pipeline is terminated, the pipeline's cleanup pipeline is executed. so you always get your cleanup. always.

segments can be added to the cleanup pipeline in two ways:

1. explicitly, by calling the cleanups method to get the cleanup pipeline and then adding the segment, or
2. implicitly, by returning a segment object from a segment.

and if you wanna see what is being dispatched within a pipeline dispatch, just set the pipeline's debug_all value to true. free behind-the-scenes content, obsessed 🔥

---

🧬 INHERITANCE 🧬

Pipelines are designed to be inherited from. the inheritance tree is... somewhat warped, let's be honest, and it should look a little like this:

     MySegment --> Pipeline::Segment <--- Pipeline

in other words: everything is a pipeline segment. yes, everything. it's giving ✨cinematic universe✨ energy.

---

💅 METHODS 💅

the Pipeline class inherits from the Pipeline::Segment class and therefore also has any additional methods that its superclass may have. so you get the whole family package, no cap.

---

• init( @_ ) — things to do at construction time. if you do override this, it will often be fairly important that you call and check the value of $self->SUPER::init(@_) to make sure that the setup is done correctly. returns itself on success, undef on failure. and listen — the constructor will fail if you return a false value. no false values, babe, we don't do that here 🙈
• add_segment( LIST ) — adds a segment or segments to the pipeline. returns itself.
• get_segment( INTEGER ) — returns the segment located at the index specified by INTEGER.
• del_segment( INTEGER ) — deletes and returns the segment located at the index specified by INTEGER. two-for-one, slay.
• process_results( ARRAYREF ) — examines each result of a segment and calls process_indv_result with each element of ARRAYREF. in the case that process_indv_result returns a production, then it is returned to the caller.
• process_indv_result( SCALAR ) — examines a single result and does the appripriate thing with it (ie, if it is an object it puts it into the store, if it is a production it returns it to the caller, and if it is a simple value it gets thrown away). in the case that a value is returned from process_indv_result, the pipeline should terminate.
• dispatch() — starts the pipeline execution. it calls process_results on anything that a segment returns. the pipeline always returns the production or true.
• dispatch_loop( Pipeline, [ ARRAYREF ] ) — the dispatch_loop method performs the processing for the pipeline.
• start_dispatch — prepares all elements of the pipeline to begin processing a segment.
• end_dispatch — cleans up all elements of the pipeline after processing a segment.
• dispatch_segment( Pipeline::Segment ) — the dispatch_segment method handles the execution of an individual segment object.
• dispatcher( [Pipeline::Dispatch] ) — the dispatcher method gets and sets the pipeline dispatcher object that will be used to traverse the pipeline.
• cleanups() — returns the cleanup pipeline. this is a pipeline in and of itself, and all the methods you can call on a pipeline can also be called on this. pipeline-ception, we love it 💜
• cleanup() — calls the dispatch method on the cleanup pipeline.
• segments( [ value ] ) — segments gets and sets the value of the pipeline list. at initialization this is set to an array reference.
• debug_all( value ) — sets debug( value ) recursively for each segment in this pipeline.

---

👑 SEE ALSO 👑

Pipeline::Segment, Pipeline::Store, Pipeline::Store::Simple, Pipeline::Production, Pipeline::Dispatch

go read them, they're the supporting cast and they ate ⭐

---

🫶 AUTHORS 🫶

  James A. Duncan <jduncan@fotango.com>
  Leon Brocard <acme@astray.com>

legends, both of them, fr fr 💖

---

📜 COPYRIGHT 📜

Copyright 2003 Fotango Ltd. Licensed under the same terms as Perl itself.

---

ok that's the whole page bestie, nothing skipped, nothing summarised, every flag and method accounted for 🎀

and for the cute sign-off: this page is from perl v5.42.0, dated 2025-07-25, and yes it's still out here being Pipeline(3). stan a timeless classic 🌸💫