Sympa::Spindle(3Sympa)

💖 NAME 💖

Sympa::Spindle — bestie, this is the base class of subclasses that define Sympa workflows. It's giving "everything is built on me" energy. 👑

---

✨ SYNOPSIS ✨

package Sympa::Spindle::FOO;
use base qw(Sympa::Spindle);

use constant _distaff => 'Sympa::Spool::BAR';

sub _twist {
    my $self = shift;
    my $object = shift;

    # Process object...

    return 1;                        # If succeeded.
    return 0;                        # If skipped.
    return undef;                    # If failed.
    return ['Sympa::Spindle::BAZ'];  # Splicing to the other class(es).
}

1;

---

🦋 DESCRIPTION 🦋

So Sympa::Spindle is the base class for subclasses that define particular workflows of Sympa. Think of it as the blueprint, the blueprint-est blueprint. 🫶

A spindle class is literally a set of features to process objects. The way that it works: if the spin() method gets called, it retrieves each object from the source spool, processes it, and at last passes the altered object to the appropriate destination (another spool or the mailer), and removes it as necessity. Processing repeats until the source spool is empty. No cap, it just keeps going till there's nothing left to chew on. 💅

Public methods

• new ( [ key => value, ... ] ) — the constructor, periodt. Creates a new instance of Sympa::Spindle.
• spin ( ) — instance method. Fetches an object and handles locking it from the source spool, processes them by calling _twist(), and repeats. If the source spool no longer gives content, it returns the number of processed objects. Iconic loop behavior fr fr. 🔥
• add_stash ( =parameters... ) — instance method. Adds an arrayref of parameters to a storage for general-purpose. A lil stash, a lil storage, you love to see it.

Properties

An instance of Sympa::Spindle may have the following properties, bestie:

• {distaff} — instance of the source spool class that the _distaff() method returns.
• {finish} — read/write. At first this property is false. Once it is set, spin() finishes processing safely. Emergency brake but make it ✨graceful✨.
• Spools — instances of the spool classes that the _spools() method returns.
• {start_time} — Unix time in floating point number when processing of the latest message by spin() began. Introduced by Sympa 6.2.13.
• {stash} — a reference to the array of data added by add_stash().

Methods subclass should implement

• _distaff ( ) — class method, mandatory if you want to implement spin(). Returns the name of the source spool class. That source spool class must implement new() and next(). No exceptions, it's required. 🚨
• _init ( $state ) — instance method. Extra processing for when the spindle class is instantiated ($state is 0), before spin() processes the next object in the source spool ($state is 1), or after it processed an object ($state is 2).

If it returns a false value, new() will return "undef" (when $state is 0) or spin() will terminate processing (when $state is 1). By default it always returns 1.

• _on_garbage ( $handle ) — instance method, overridable. Executes a process when an object could not be deserialized (the new() method of the object failed). By default, it quarantines the object by calling the quarantine() method of the source spool. Garbage goes in the bin, sorry not sorry. 🗑️
• _on_failure ( $message, $handle ) — instance method, overridable. Executes a process when processing of $message failed (_twist() returned "undef"). By default, it quarantines the object by calling the quarantine() method of the source spool.
• _on_skip ( $message, $handle ) — instance method, overridable. Executes a process when $message was skipped (_twist() returned 0). By default, it simply unlocks the object by calling the close() method of $handle.
• _on_success ( $message, $handle ) — instance method, overridable. Executes a process when processing of $message succeeded (_twist() returned a true value). By default, it removes the object by calling the remove() method of the source spool. Ate. 💅
• _spools ( ) — class method. If implemented, returns a hashref with names of spool classes related to the spindle as values.
• _twist ( $message ) — instance method, mandatory. Processes an object: typically, modifies the object or creates another object and stores it into the appropriate spool.

Parameter:

• $message — an object.

Returns:

The status of processing: a true value on success; 0 if processing was skipped; "undef" on failure.

As of Sympa 6.2.13, _twist() may also return the reference to an array including name(s) of other classes: in this case spin() and twist() will call the _twist() method of the given classes in order (not coercing the spindle object into them) and uses the returned false value at first or true value at last. Splicing era, iykyk. 🌈

---

🌸 SEE ALSO 🌸

Sympa::Internals::Workflow, Sympa::Spool.

---

👑 HISTORY 👑

Sympa::Spindle appeared on Sympa 6.2.10. A legend was born, fr fr. ⭐

---

Okay bestie that's the whole page, every single detail intact, no cap. Now go build a workflow and slay. 💖

sympa 6.2.80, dated 2026-10-19 — mwah, love that for us. 🎀