Future...ception(3pm)

✨ Future::Exception — the glow-up manual 💖

okay bestie, gather round, because we're talking about Future::Exception — it's literally an exception type for failed Futures. that's it. that's the whole vibe. 🦋

---

🌸 SYNOPSIS 🌸

here's how you actually use it, copy-paste ready:

use Scalar::Util qw( blessed );
use Syntax::Keyword::Try;

try {
   my $f = ...;
   my @result = $f->result;
   ...
}
catch {
   if( blessed($@) and $@->isa( "Future::Exception" ) {
      print STDERR "The ", $@->category, " failed: ", $@->message, "\n";
   }
}

(yes the missing paren is canon, don't @ me, it's in the original fr fr 😭)

---

💅 DESCRIPTION 💅

so here's the tea. when you call the get method on a Future that has failed, it throws an exception, because it needs to tell you the whole thing went sideways. and a failed future isn't just sad and empty — it can be carrying a failure category name, plus other details, plus the failure message. so in that case the exception it throws is an instance of Future::Exception, specifically so all those lil values are reachable. 🎀

⚠️ now listen up because this is important: do NOT go matching on exact class names. that's not the move. rely on inheritance instead, okay?

why? because a later version of this implementation might dynamically create subclasses whose names are derived from the Future failure category string, to help with type matching. so like, the class name could shift on you. that's why the SYNOPSIS uses ->isa — it checks the whole family tree, not just the one name. iconic behaviour, honestly. 👑

---

🌈 CONSTRUCTOR 🌈

🧚 from_future

$e = Future::Exception->from_future( $f );

constructs a brand new Future::Exception that wraps the given failed future. one job, does it well, slay. ✨

---

💖 ACCESSORS 💖

$message  = $e->message;
$category = $e->category;
@details  = $e->details;

and ALSO — and this is the part that's lowkey so convenient — the object will stringify to return the message value. which means it just ~works~ for the super common stuff: printing it, regexp testing it, or whatever other behaviours you're into. no extra steps, no .message needed, it just is the message when you treat it like a string. obsessed. 🫶

---

🔥 METHODS 🔥

⭐ throw

Future::Exception->throw( $message, $category, @details );

since version 0.41. 📌

constructs a new exception object and throws it using die(). and heads up — this method will not return, because it raises the exception directly. it's not coming back. it's gone. 💀

one more detail: if $message does not end in a linefeed, then the calling file and line number get appended to it — in the exact same way that die() does. so your error messages come pre-decorated with the receipts. 📍

🦋 as_future

$f = $e->as_future;

hands you back a brand new Future object, sitting in a failed state, matching the exception. round trip. main character energy. ✨

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> — the legend themselves 💜

---

and that's the whole page, bestie!! this was Future...ception(3pm) from the perl v5.40.1 era, dated 2025-09-22 — yes the title really does say Future...ception with the ellipsis, that's not a typo, that's branding. 🎀 go forth and catch your exceptions correctly, and remember: ->isa, never a class-name equality check. periodt. 💅