/ 
PAGI-FastAPI-v1.1.0
/ PAGI::FastAPI::Queue

NAME

PAGI::FastAPI::Queue - Pluggable Async Message Queue Facade for PAGI::FastAPI

VERSION

Version v1.1.0

SYNOPSIS

use PAGI::FastAPI::Queue;
use PAGI::FastAPI::Depends qw(Depends);

my $queue = PAGI::FastAPI::Queue->new; # Defaults to the Memory driver

$app->post('/jobs',
    dependencies => [ Depends($queue->dep, key => 'queue') ],
    handler      => async sub ($c) {
        await $c->stash->{queue}->push('emails', { to => 'a@b.com' });
        return { queued => 1 };
    },
);

# Selecting a driver by short name (resolved under
# PAGI::FastAPI::Queue::Driver::*) or by fully-qualified class name
my $q1 = PAGI::FastAPI::Queue->new(driver => 'Memory');
my $q2 = PAGI::FastAPI::Queue->new(
    driver  => 'PAGI::FastAPI::Queue::Driver::Memory',
    options => {},
);

DESCRIPTION

PAGI::FastAPI is an asynchronous application programming interface (API) for interacting with the PAGI::FastAPI::Queue::Driver storage mechanism. It offers an easy way to perform operations such as push, pop, and size, and has included PAGI::FastAPI::Queue::Driver::Memory implementation by default in the API.

Developers may create their implementations of the PAGI::FastAPI::Queue::Driver storage mechanism for other systems such as SQS, or queue on the database level. Developers can create a new driver by extending from the PAGI::FastAPI::Queue::Driver::* API and using the class name either in the shortened form or in the long form. A companion Redis driver is available using PAGI::FastAPI::Queue::Driver::Redis.

Unlike PAGI::FastAPI::Middleware::RateLimit, which is working with an instance of object, PAGI::FastAPI::Queue expects name (a string) of the driver and creates an instance from the given class.

METHODS

new(%options)

Constructs a new queue facade.

  • driver - (Optional) Scalar string naming the driver to use. Defaults to 'Memory'. A bare name (no ::) is resolved as PAGI::FastAPI::Queue::Driver::$name; a string already prefixed with PAGI::FastAPI::Queue::Driver:: is used as-is. Dies if the resulting class cannot be loaded.

  • options - (Optional) HashRef of constructor arguments forwarded to the driver class's new(). Defaults to {}.

dep()

Returns a zero-argument closure that resolves to this PAGI::FastAPI::Queue instance, suitable for use with PAGI::FastAPI::Depends:

Depends($queue->dep, key => 'queue')

push($topic, $payload)

Pushes $payload (any scalar) onto the end of $topic. Returns a Future resolving to the underlying driver's result (true on success).

pop($topic)

Removes and returns a Future resolving to the item at the front of $topic, or undef if the topic is empty or unknown.

size($topic = undef)

Returns a Future resolving to the number of pending items in $topic. If $topic is omitted (or undef), resolves to the total number of pending items across all topics.

SEE ALSO

PAGI::FastAPI::Queue::Driver, PAGI::FastAPI::Queue::Driver::Memory, PAGI::FastAPI::Depends

AUTHOR

Mohammad Sajid Anwar, <mohammad.anwar at yahoo.com>

REPOSITORY

https://github.com/manwar/PAGI-FastAPI

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/manwar/PAGI-FastAPI/issues. I will be notified and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc PAGI::FastAPI::Queue

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright (C) 2026 Mohammad Sajid Anwar.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License (2.0).