Memorator - Remind of events via Minion
This document describes Memorator version 0.001.
use Minion; my $minion = Minion->new(...); use Memorator; my $memorator = Memorator->create( alert_callback => sub { my $id = shift; print "notification for id <$id>\n"; return; }, minion => $minion, name => 'memorator', # this is the default ); $minion->enqueue(memorator_process_update => { id => 'id-001', # identifier meaningful for you epoch => (time + 30), # when you want the alert attempts => 5, # how many retries before giving up } );
This module allows you to set alerts for some events you need to be warned of. It's as simple as asking an alarm to ring at a certain date/time.
The module leverages on Minion for the heavylifting. It's actually a thin API on top of it, installing two tasks which by default go under the names memorator_process_update and memorator_process_alert (although you can change the memorator part using "name").
memorator_process_update
memorator_process_alert
memorator
The interaction model is simple:
you create an object with an "alert_callback" and a minion object that will do the hard work. The "alert_callback" is where you will implement your logic for when the alert expires;
minion
you enqueue updates to set new alarms or modify existing ones, based on an identifier that is meaningful for you;
at the expiration of the alarm time, the "alert_callback" is called with the specific identifier, so that you can figure out what has to be done next.
To add a new reminder, or change an existing one, you use memorator_process_update passing a hash reference like this:
$minion->enqueue(memorator_process_update => { eid => 'id-001', # identifier meaningful for you epoch => (time + 30), # when you want the alert attempts => 5, # how many retries before giving up } );
You can also set alerts directly, without the mediation of Minion, using "set_alert":
$memorator->set_alert(\%same_hashref_as_before);
See "set_alert" for the allowed keys.
my $sub_reference = $obj->alert_callback; $obj->alert_callback(sub {...});
accessor for the callback to be run when an alert has to be sent. It is mandatory to set this before the first alert is sent. Can be set in the constructor.
The callback will be invoked like follows:
$callback->($identifier);
where $identifier is a meaningful identifier for your applications (which is also the identifier passed upon creation of the event).
$identifier
my $minion = $obj->minion; $obj->minion($minion_instance);
accessor for the Minion used behind the scenes. Note that in callbacks called in jobs the minion instance will be drawn from the jobs themselves, as it might prove to be fresher.
my $name = $obj->name; $obj->name($new_name);
accessor for a name for generating local names of tables in the database, as well as task names in Minion. This allows you to have more instances living inside the same Minion, should you ever need to do this. Defaults to memorator. Can be set in the constructor.
my $obj = Memorator->new(%args); my $obj = Memorator->new(\%args);
constructor. The recognized keys in %args correspond to accessors "alert_callback" (mandatory), "minion" (mandatory) and "name" (optional).
%args
$obj->set_alert(\%hashref);
Set an alert. The following keys are supported:
attempts
how many times Minion will retry upon failure of your callback. In this case, failure means thrown exception.
epoch
the UTC epoch at which you want the alert callback to be triggered.
id
the identifier for your event, which can help you retrieve the details of your event somewhere else. It has a textual form, so you might want to abuse it to store more data (e.g. some JSON data); just keep in mind that it is treated as an opaque identifier, i.e. a string that is compared to other strings for equality.
You don't need to call this directly if you use Minion for enqueuing alerts via memorator_process_update (or whatever name the task has, based on "name").
Report bugs through GitHub (patches welcome).
Minion.
Flavio Poletti <polettix@cpan.org>
Copyright (C) 2018 by Flavio Poletti <polettix@cpan.org>
This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
To install Memorator, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Memorator
CPAN shell
perl -MCPAN -e shell install Memorator
For more information on module installation, please visit the detailed CPAN module installation guide.