view release on metacpan or  search on metacpan

lib/Dancer2/Manual.pod  view on Meta::CPAN

In Danceyland, we never want our visitors to wait in line! Sometimes, a
task can take a long time, like fetching data from an external service.
Asynchronous programming allows you to handle these tasks in the
background, keeping your app responsive.

Dancer2 supports asynchronous programming to help you manage I/O-bound
operations more efficiently.

=head2 Why Choose Async Over Blocking?

With async programming, you can handle long-running tasks without
blocking the rest of your app. This is useful for:

=over 4

=item *

Fetching data from an external API.

=item *

Handling large uploads or downloads.

=item *

Sending notifications or emails.

=back

=head2 Choosing the Right PSGI Server

To use asynchronous programming in Dancer2, your app must be running on
a PSGI server that supports event loops, like L<Twiggy>. Such servers can
handle async tasks, unlike traditional PSGI servers that utilize forking
to handle multiple parallel tasks.

=head2 Sending Content Asynchronously

Dancer2 provides keywords for implementing asynchronous code.

=head3 content

The C<content> keyword sets the response content from within a delayed
response.

=head3 delayed

Some events at Danceyland, like the grand parade, are worth watching but
take some time to complete. Similarly, Dancer2 offers the C<delayed> keyword
to initiate an asynchronous response, allowing you to deliver long-running
results, or handling long-running operations.

=head2 done

Once everything is set, you can use C<done> to finalize and send the
response to the visitor.

=head2 flush

To send parts of the response incrementally, C<flush> allows streaming
content to the client in a delayed response without closing the connection.

=head2 Example: Asynchronous HTTP Request

Here’s how you can fetch data asynchronously in Dancer2. Instead of
waiting for a response, the request runs in the background and delivers
the result when it’s ready:

    use Dancer2;
    use Future::HTTP;

    get '/fetch-ride-status' => sub {
        delayed {
            content 'The grand parade is starting!';
            flush;

            http_get('http://parade-status.com/api/v1/floats')->then( sub {
                my ($body, $headers) = @_;
                content $body;
                flush;
            });

            content 'The grand parade is finished!';
            done;
        };
    };

In this example, we fetch the status of a ride asynchronously using
C<http_get>. The C<delayed> keyword defers the response until the
background request completes. The C<$resume> callback is used to send
the content back to the visitor once the request finishes.

For a deeper dive, check out these fantastic articles on async programming
in Dancer2: L<https://advent.perldancer.org/2020/22> and
L<https://advent.perldancer.org/2020/23>.

=head1 AUTHOR

Dancer Core Developers

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Alexis Sukrieh.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut