Future...aitable(3pm)

✨ NAME ✨

Future::AsyncAwait::Awaitable — literally the interface that Future::AsyncAwait requires, bestie 💖

---

🦋 DESCRIPTION 🦋

Okay so this module is basically the receipt 📜 for what methods Future::AsyncAwait needs to find on future instances. Which future instances? The ones that come back from expressions you invoked with the await keyword, and the ones returned by functions you declared with async sub. That's the deal.

ngl, this info is mostly for the girlies who are out here implementing other module integrations, event systems, or similar stuff 👑. If you're just a regular user vibing with an existing event system, you do not need any of this. Like, at all. You're fine. Go sip your iced coffee 🍓.

Now, the methods this interface wants are all capitalised and all prefixed with AWAIT_..., so they're super unlikely to run into existing methods on a class that might have completely different semantics. No awkward name collisions, no drama. periodt 💅

🌸 Role::Tiny 🌸

If Role::Tiny is available, this module declares itself to be a role which requires all the following named methods. The thing is, the role supplies no code at all to the class you apply it to — it's purely a vibe check ✅. But it's genuinely useful for checking that you actually did implement every single one of the required methods instead of just telling yourself you did 🙈.

⭐ Conformance Test ⭐

For the implementors out there building alternative future-like classes, there's an API conformance test suite provided by Test::Future::AsyncAwait::Awaitable. Highly recommend — it's how you check that your implementation is actually suitable and not just giving main character energy 💀.

---

🎀 CONSTRUCTORS 🎀

These methods below are expected to create brand-new future instances. They use the class set by the prevailing future_class import argument if it's been set, or they default to Future if it hasn't. Simple as 🫶

AWAIT_NEW_DONE

Generate a shiny new immediate future that's successful. This future is already ready, and it has the list of values set as its result.

$f = $CLASS->AWAIT_NEW_DONE( @results );

# $f->AWAIT_IS_READY will be true
# $f->AWAIT_GET will return @results

AWAIT_NEW_FAIL

Generate a new immediate future that is failed. This one is also already ready, and invoking the AWAIT_GET method will throw the given exception. Yikes but make it synchronous 😭

$f = $CLASS->AWAIT_NEW_FAIL( $message );

# $f->AWAIT_IS_READY will be true
# $f->AWAIT_GET will throw $message

---

💜 INSTANCE METHODS 💜

AWAIT_CLONE

Generate a new pending future of the same type as an existing one — and the existing one is not modified by doing this. This will only ever be invoked on instances that are currently pending.

$new_f = $f->AWAIT_CLONE;

If the instance has any fields that are required for successful operation (think application-wide context, or event system components), those ought to be copied. But other than that, you should not copy any per-instance state — no pending callbacks, no partial results. Leave those where they are, bestie 🚫

AWAIT_DONE

Sets the success result of an existing still-pending future. Only invoked on future instances that are currently pending.

$f->AWAIT_DONE( @results );

# $f->AWAIT_IS_READY will now be true
# $f->AWAIT_GET will now return @results

AWAIT_FAIL

Sets the failure result of an existing still-pending future. Again, only invoked on future instances that are currently pending.

$f->AWAIT_FAIL( $message );

# $f->AWAIT_IS_READY will now be true
# $f->AWAIT_GET will now throw $message

AWAIT_IS_READY

Returns true if a future is ready — and just so we're clear, "ready" covers successful, failed, or cancelled 💀. Returns false if it's still pending.

$bool = $f->AWAIT_IS_READY;

AWAIT_IS_CANCELLED

Returns true if a future has already been cancelled; false if it's still pending, successful, or failed.

$bool = $f->AWAIT_IS_CANCELLED;

An implementation that doesn't support cancellation can just return a constant false here, no stress:

sub AWAIT_IS_CANCELLED { 0 }

AWAIT_GET

Yields the result of a successful future (or just the first value if you call it in scalar context). If you call it on a failed one, it throws the failure message as an exception. It will not be invoked on a pending or cancelled future — so don't worry about that case, it's not your problem ✨

@result = $f->AWAIT_GET;
$result = $f->AWAIT_GET;
$f->AWAIT_GET;

AWAIT_ON_READY

Attach a new CODE reference to be invoked when the future becomes ready — whether that's by success or by failure. Heads up though: the arguments and the context that $code gets invoked with are unspecified. So don't go assuming, iykyk 🫶

$f->AWAIT_ON_READY( $code );

AWAIT_CHAIN_CANCEL

Attach a future instance to be cancelled when another one gets cancelled.

$f1->AWAIT_CHAIN_CANCEL( $f2 );

So the way this works: when $f1 is cancelled, then $f2 is cancelled too. But — and this is the important part — there is no link from $f2 back to $f1. Whenever $f2 changes state here, nothing special happens to $f1. It's giving one-directional, and honestly, relatable 🌈

An implementation that doesn't support cancellation can simply ignore this method entirely:

sub AWAIT_CHAIN_CANCEL { }

🚨 okay lore drop: an older version of this API specification named this method AWAIT_ON_CANCEL. But that name is going to be repurposed for attaching code blocks in a later version. So yeah. Don't get attached to the old name, bestie 😭

AWAIT_ON_CANCEL

Attach a new CODE reference to be invoked when the future is cancelled.

$f->AWAIT_ON_CANCEL( $code );

An implementation that does not support cancellation can simply ignore this method too:

sub AWAIT_ON_CANCEL { }

AWAIT_WAIT

Called by the toplevel await expression in order to run the event system and wait for the instance to be ready. It should return results — or throw an exception — in the exact same manner as AWAIT_GET does.

@result = $f->AWAIT_WAIT;
$result = $f->AWAIT_WAIT;
$f->AWAIT_WAIT;

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> — we stan 💖

---

and that's the whole thing, bestie 🎀 this was perl v5.42.3, dated 2026-08-20, filed under Future...aitable(3pm). slay, go implement an event system or whatever 💅✨