| 1 | =head1 NAME | ||
| 2 | |||
| 3 | Queue::Worker - Database based work queue abstraction. | ||
| 4 | |||
| 5 | =head1 SYNOPSIS | ||
| 6 | |||
| 7 | package MyWorker; | ||
| 8 | use base 'Queue::Worker'; | ||
| 9 | |||
| 10 | sub name { 'my_work'; } | ||
| 11 | |||
| 12 | sub process { | ||
| 13 | my ($self, $item) = @_; | ||
| 14 | # do your work here | ||
| 15 | } | ||
| 16 | |||
| 17 | # create worker table in db | ||
| 18 | MyWorker->create_table($dbh); | ||
| 19 | |||
| 20 | # and somewhere else | ||
| 21 | MyWorker->enqueue($dbh, 'some work order string'); | ||
| 22 | |||
| 23 | # and finally to run the queue | ||
| 24 | MyWorker->run($dbh); | ||
| 25 | |||
| 26 | =head1 DESCRIPTION | ||
| 27 | |||
| 28 | This module provides simple, database queue based, worker abstraction. It | ||
| 29 | provides locking between worker instances using L<POSIX::RT::Semaphore>. | ||
| 30 | |||
| 31 | Strings representing work orders are enqueued with C<enqueue> function. Those | ||
| 32 | items are removed from the queue by C<run> function. | ||
| 33 | |||
| 34 | =cut | ||
| 35 | use strict; | ||
| 36 | use warnings FATAL => 'all'; | ||
| 37 | |||
| 38 | package Queue::Worker; | ||
| 39 | our $VERSION = '0.01'; | ||
| 40 | use POSIX::RT::Semaphore; | ||
| 41 | use Fcntl; # O_CREAT, O_EXCL for named semaphore creation | ||
| 42 | |||
| 43 | =head1 METHODS | ||
| 44 | |||
| 45 | =head2 $class->create_table($dbh, $name) | ||
| 46 | |||
| 47 | Creates table C<queue_worker_$name> table in the database. C<$name> parameter | ||
| 48 | is optional: if undef C<name> accessor is used. | ||
| 49 | |||
| 50 | =cut | ||
| 51 | sub create_table { | ||
| 52 | my ($class, $dbh, $name) = @_; | ||
| 53 | $name ||= $class->name; | ||
| 54 | $dbh->do(sprintf(<<'ENDS', $name)); | ||
| 55 | create table queue_worker_%s (id serial primary key, msg text) without oids | ||
| 56 | ENDS | ||
| 57 | } | ||
| 58 | |||
| 59 | =head2 $class->enqueue($dbh, $msg) | ||
| 60 | |||
| 61 | Enqueues work order C<$msg> into the queue. | ||
| 62 | |||
| 63 | =cut | ||
| 64 | sub enqueue { | ||
| 65 | my ($class, $dbh, $msg) = @_; | ||
| 66 | $dbh->do(sprintf('insert into queue_worker_%s (msg) values (?)' | ||
| 67 | , $class->name), undef, $msg); | ||
| 68 | } | ||
| 69 | |||
| 70 | =head2 $class->new | ||
| 71 | |||
| 72 | Creates new instance of the worker. Also creates underlying semaphore. | ||
| 73 | |||
| 74 | =cut | ||
| 75 | sub new { | ||
| 76 | my $class = shift; | ||
| 77 | my $sem = POSIX::RT::Semaphore->open("/" . $class->name | ||
| 78 | , O_CREAT, 0660, 1); | ||
| 79 | return bless({ semaphore => $sem }, $class); | ||
| 80 | } | ||
| 81 | |||
| 82 | =head2 $class->run($dbh) | ||
| 83 | |||
| 84 | Runs the queue. Calls C<process> method on each work item. | ||
| 85 | |||
| 86 | =cut | ||
| 87 | sub run { | ||
| 88 | my ($self, $dbh) = @_; | ||
| 89 | my $t = 'queue_worker_' . $self->name; | ||
| 90 | my $sql = <<ENDS; | ||
| 91 | delete from $t where id in (select id from $t order by id limit 1) | ||
| 92 | returning msg; | ||
| 93 | ENDS | ||
| 94 | my $cnt = 0; | ||
| 95 | AGAIN: | ||
| 96 | (!$self->{semaphore}->trywait) and goto OUT; # has 0 but true | ||
| 97 | eval { for (;;) { | ||
| 98 | # delete should not be in transaction: we should always make | ||
| 99 | # progress, even if we die. Otherwise, we'll be crashing again | ||
| 100 | # and again. | ||
| 101 | my $res = $dbh->selectcol_arrayref($sql); | ||
| 102 | last unless @$res; | ||
| 103 | $self->process($res->[0]); | ||
| 104 | $cnt++; | ||
| 105 | } }; | ||
| 106 | $self->{semaphore}->post; | ||
| 107 | die "Retrowing: $@" if $@; | ||
| 108 | |||
| 109 | my $more = $dbh->selectcol_arrayref("select id from $t limit 1"); | ||
| 110 | goto AGAIN if @$more; | ||
| 111 | OUT: | ||
| 112 | return $cnt; | ||
| 113 | } | ||
| 114 | |||
| 115 | =head2 $class->unlink_semaphore | ||
| 116 | |||
| 117 | Unlinks semaphore. | ||
| 118 | |||
| 119 | =cut | ||
| 120 | sub unlink_semaphore { | ||
| 121 | my $class = shift; | ||
| 122 | POSIX::RT::Semaphore->unlink('/' . $class->name); | ||
| 123 | } | ||
| 124 | |||
| 125 | =head2 $class->get_semaphore | ||
| 126 | |||
| 127 | Returns underlying semaphore. | ||
| 128 | |||
| 129 | =cut | ||
| 130 | sub get_semaphore { | ||
| 131 | return shift()->new->{semaphore}; | ||
| 132 | } | ||
| 133 | |||
| 134 | 1; | ||
| 135 | |||
| 136 | =head1 ABSTRACT METHODS | ||
| 137 | |||
| 138 | The following methods should be implemented by inherited class. | ||
| 139 | |||
| 140 | =head2 $class->name | ||
| 141 | |||
| 142 | Should return the name of the worker. | ||
| 143 | |||
| 144 | =head2 $self->process($msg) | ||
| 145 | |||
| 146 | Callback to process the work order. | ||
| 147 | |||
| 148 | =head1 AUTHOR | ||
| 149 | |||
| 150 | Boris Sukholitko | ||
| 151 | CPAN ID: BOSU | ||
| 152 | |||
| 153 | boriss@gmail.com | ||
| 154 | |||
| 155 | |||
| 156 | =head1 COPYRIGHT | ||
| 157 | |||
| 158 | This program is free software; you can redistribute | ||
| 159 | it and/or modify it under the same terms as Perl itself. | ||
| 160 | |||
| 161 | The full text of the license can be found in the | ||
| 162 | LICENSE file included with this module. | ||
| 163 | |||
| 164 | |||
| 165 | =head1 SEE ALSO | ||
| 166 | |||
| 167 | L<POSIX::RT::Semaphore> | ||
| 168 | |||
| 169 | =cut |