/ 
Minion-Notifier-0.08
River stage zero No dependents
/ Minion::Notifier

NAME

Minion::Notifier - Notify listeners when a Minion task has completed

SYNOPSIS

use Mojolicious::Lite;

plugin Minion => { Pg => 'posgressql://...'};

plugin 'Minion::Notifier';

app->minion->add_task( doit => sub { ... } );

any '/doit' => sub {
  my $c = shift;
  my $id = $c->minion->enqueue(doit => [...]);
  $c->minion_notifier->on(job => sub {
    my ($notifier, $job_id, $message) = @_;
    return unless $job_id eq $id;
    $c->render( text => "job $id: $message" );
  });
};

DESCRIPTION

Although Minion is a highly capable job queue, it does not natively have a mechanism to notify listeners when a job has finished or failed. Minion::Notifier provides this feature using pluggable Transport backends. Currently supported are Postgres, Redis, and WebSocket. Postgres support requires Mojo::Pg and Redis requires Mojo::Redis2. WebSockets are native to Mojolicious but you need a broker to manage the connections; Mercury is the author's suggested WebSocket message broker.

Note that this is an early release and the mechansim for loading plugins, especially third-party plugins is likely to change. Also note that due to the use of messaging buses, the order of events is not guaranteed especially on very fast jobs.

EVENTS

Minion::Notifier inherits all events from Mojo::EventEmitter and emits the following new ones.

enqueue

$notifier->on(enqueue => sub { my ($notifier, $job_id) = @_; ... });

Emitted whenever any job is enqueued (typically having a state of "inactive"). Note that the event is not repeated as an argument, though this is subject to change.

dequeue

$notifier->on(dequeue => sub { my ($notifier, $job_id) = @_; ... });

Emitted whenever any job is dequeued for processing (typically having a state of "active"). Note that the event is not repeated as an argument, though this is subject to change.

job

$notifier->on(job => sub { my ($notifier, $job_id, $event) = @_; ... });

Emitted on any event from the backend for all jobs. The events are currently "enqueue", "dequeue", "finished", and "failed".

job:$id

$notifier->on("job:1234" => sub { my ($notifier, $job_id, $event) = @_; ... });

Emitted on any message from the backend for specific jobs. Note that the id is still passed so that you may reuse callbacks if desired. The events are currently "enqueue", "dequeue", "finished", and "failed".

Users of this event are encouraged to carefully consider what race conditions may exist in the act of subscribing to it. For example, Minion::enqueue will emit the "enqueue" event before it even returns the job's id. For this reason, this event is discouraged and may be deprecated/removed in a future release.

finished

$notifier->on(finished => sub { my ($notifier, $job_id) = @_; ... });

Emitted whenever any job reaches a state of "finished". Note that the event is not repeated as an argument, though this is subject to change.

failed

$notifier->on(failed => sub { my ($notifier, $job_id) = @_; ... });

Emitted whenever any job reaches a state of "failed". Note that the event is not repeated as an argument, though this is subject to change.

ATTRIBUTES

Minion::Notifier inherits all of the attributes from Mojo::EventEmitter and implements the following new ones.

minion

The Minion instance to listen to. Note that this attribute is used to gain access to the "application instance".

transport

An instance of Minion::Notifier::Transport or more likely a subclass thereof. This is used to moderate the communication between processes and even hosts.

METHODS

Minion::Notifier inherits all of the methods from Mojo::EventEmitter and implements the following new ones.

app

A shortcut for $notifier->minion->app.

emit_event

A low level method used to emit the batch of events related to received minion events.

setup_listener

Setup the linkages that allow for notifications to be received. This is called automatically by Mojolicious::Plugin::Minion::Notifier once the ioloop has started.

setup_worker

Setup the linkages that cause the jobs to send notifications when reaching "finished" or "failed" states. This is called automatically by Mojolicious::Plugin::Minion::Notifier.

FUTURE WORK

  • Document all included classes (hey this is a preview release!)

  • Improve backend loader mechanism

  • Investigate timeout behavior for the various transport backends

SEE ALSO

SOURCE REPOSITORY

http://github.com/jberger/Minion-Notifier

AUTHOR

Joel Berger, <joel.a.berger@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Joel Berger

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