| 1 | package Mojolicious::Plugin::Buffer::Lock::Redis; | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 2 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 3 | 10 | ▶ | use strict; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 4 | 10 | ▶ | use warnings; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 5 | 10 | ▶ | use autodie qw(:all); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 6 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 7 | 10 | ▶ | use Mojo::Base -base; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 8 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 9 | 10 | ▶ | use Carp qw(croak); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 10 | 10 | ▶ | use Mojo::Util qw(encode md5_sum trim); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 11 | 10 | ▶ | use Mojolicious::Plugin::Buffer::I18N qw(i18n); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 12 | 10 | ▶ | use Params::Get qw(get_params); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 13 | 10 | ▶ | use Params::Validate::Strict qw(validate_strict); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 14 | 10 | ▶ | use Readonly; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 15 | 10 | ▶ | use Scalar::Util qw(blessed refaddr); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 16 | 10 | ▶ | use Sub::Private { mode => 'enforce' }; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 17 | 10 | ▶ | use Sub::Protected; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 18 | 10 | ▶ | use Time::HiRes (); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 19 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 20 | 10 | ▶ | use version; our $VERSION = version->declare('0.002.0'); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 21 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 22 | 10 | Readonly::Scalar my $DEFAULT_NAMESPACE => 'buffer:lock:'; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 23 | 10 | Readonly::Scalar my $DEFAULT_TTL => 60; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 24 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 25 | # Redis takes PX in milliseconds; a TTL that rounds below 1ms would be | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 26 | # rejected by the server, so it is clamped to this | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 27 | 10 | Readonly::Scalar my $MS_PER_SECOND => 1000; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 28 | 10 | Readonly::Scalar my $MIN_TTL_MS => 1; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 29 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 30 | # Constructor arguments. The client is checked separately, because CPAN Redis | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 31 | # dispatches commands through AUTOLOAD and has no eval() for can() to find. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 32 | Readonly::Hash my %NEW_SCHEMA => ( | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 33 | namespace => {type => 'string', min => 1}, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 34 | 22 | ▶ | ttl => {type => 'number', matches => qr/^\d+(?:\.\d+)?$/, callback => sub { defined($_[0]) && ($_[0] > 0) }}, | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=2 SCAR=6.9
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 35 | 10 | ); | |||||||||||||||||||||||||||||||||||||||||||||||||
| 36 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 37 | 10 | has redis => undef; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 38 | 10 | has namespace => $DEFAULT_NAMESPACE; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 39 | 10 | has ttl => $DEFAULT_TTL; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 40 | 10 | has messages => undef; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 41 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 42 | # Makes each token unique within a process even within one clock tick | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 43 | 10 | my $TOKEN_COUNTER = 0; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 44 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 45 | # SET NX PX is atomic, so only one worker can create the key. The token lets | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 46 | # the owner release exactly its own lock. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 47 | 10 | Readonly::Scalar my $ACQUIRE_SCRIPT => <<'LUA'; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 48 | if redis.call('set', KEYS[1], ARGV[1], 'NX', 'PX', ARGV[2]) then | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 49 | return 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 50 | end | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 51 | return 0 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 52 | LUA | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 53 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 54 | # Compare and delete in one script, so a lock that expired and was taken by | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 55 | # another worker is never removed by the previous owner. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 56 | 10 | Readonly::Scalar my $RELEASE_SCRIPT => <<'LUA'; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 57 | if redis.call('get', KEYS[1]) == ARGV[1] then | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 58 | return redis.call('del', KEYS[1]) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 59 | end | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 60 | return 0 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 61 | LUA | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 62 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 63 | =encoding utf8 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 64 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 65 | =head1 NAME | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 66 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 67 | Mojolicious::Plugin::Buffer::Lock::Redis - Redis-backed lock backend | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 68 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 69 | =head1 VERSION | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 70 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 71 | Version 0.002.0 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 72 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 73 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 74 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 75 | Workers on several machines, sharing one Redis server and one cache: | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 76 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 77 | use Mojolicious::Lite; | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 78 | use CHI; | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 79 | use Redis; | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 80 | use Mojolicious::Plugin::Buffer::Lock::Redis; | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 81 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 82 | plugin 'Buffer' => { | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 83 | cache => CHI->new(driver => 'Memcached', servers => ['cache.internal:11211']), | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 84 | cache_lock => Mojolicious::Plugin::Buffer::Lock::Redis->new( | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 85 | # A code reference: each worker makes its own connection | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 86 | redis => sub { | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 87 | Redis->new( | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 88 | server => 'redis.internal:6379', | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 89 | cnx_timeout => 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 90 | read_timeout => 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 91 | write_timeout => 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 92 | ); | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 93 | }, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 94 | namespace => 'myapp:buffer:', | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 95 | ttl => 60, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 96 | ), | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 97 | }; | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 98 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 99 | The same with L<Redis::Fast>, which has the same interface: | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 100 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 101 | use Redis::Fast; | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 102 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 103 | my $lock = Mojolicious::Plugin::Buffer::Lock::Redis->new( | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 104 | redis => sub { Redis::Fast->new(server => 'redis.internal:6379') }, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 105 | ); | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 106 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 107 | Use it on its own, for example so that only one machine runs a job: | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 108 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 109 | my ($guard, $error) = $lock->acquire('nightly-report'); | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 110 | if ($guard) { | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 111 | build_report(); | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 112 | $lock->release($guard); | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 113 | } elsif (defined $error) { | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 114 | warn "Redis problem: $error\n"; | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 115 | } # else another machine is already doing it | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 116 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 117 | Add a Redis Cluster hash tag by overriding the protected C<_key> method, so | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 118 | every lock lands in one slot: | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 119 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 120 | package MyApp::Lock; | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 121 | use Mojo::Base 'Mojolicious::Plugin::Buffer::Lock::Redis'; | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 122 | use Mojo::Util qw(encode md5_sum); | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 123 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 124 | sub _key { | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 125 | my ($self, $key) = @_; | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 126 | return '{' . $self->namespace . '}' . md5_sum(encode('UTF-8', $key)); | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 127 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 128 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 129 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 130 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 131 | This is a lock backend for | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 132 | L<cache_lock|Mojolicious::Plugin::Buffer/cache_lock>. It lets workers on | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 133 | I<different machines> agree that only one of them builds a missing cache | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 134 | entry. The cache itself must also be shared between those workers. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 135 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 136 | =head2 How it works, in plain words | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 137 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 138 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 139 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 140 | =item 1. Each cache key is turned into a Redis key: L</namespace> followed by | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 141 | the MD5 digest of the cache key. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 142 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 143 | =item 2. To take the lock, the backend writes a random I<token> into that | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 144 | Redis key, but only if the key does not exist yet (Redis C<SET ... NX PX>). | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 145 | Redis does this in one step, so two workers can never both succeed. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 146 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 147 | =item 3. The Redis key expires by itself after L</ttl> seconds. So if a | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 148 | worker crashes while it holds a lock, the lock disappears later on its own. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 149 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 150 | =item 4. To release the lock, a small Lua script deletes the Redis key, but | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 151 | only if it still holds I<our> token. If our lock already expired and another | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 152 | worker took it, we do not delete theirs. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 153 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 154 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 155 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 156 | The Redis client is called I<synchronously>: the worker waits for Redis to | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 157 | answer before the request goes on. So set short connect, read and write | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 158 | timeouts on the client, and do not use a non-blocking client. Redis 2.6.12 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 159 | or newer is needed for C<SET ... NX PX>. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 160 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 161 | =head2 Words used in this document | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 162 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 163 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 164 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 165 | =item token | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 166 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 167 | A random 32-character string made for each successful L</acquire>. It | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 168 | proves which worker owns a lock. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 169 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 170 | =item TTL | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 171 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 172 | "Time to live": how long Redis keeps the lock before it deletes it by | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 173 | itself. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 174 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 175 | =item guard | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 176 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 177 | The value L</acquire> returns when you get the lock. It holds the Redis key | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 178 | and the token. Give it back to L</release>. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 179 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 180 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 181 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 182 | =head1 ATTRIBUTES | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 183 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 184 | Attributes are set with L</new>, which checks them. Each one also has an | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 185 | accessor method with the same name, made by L<Mojo::Base>. Changing a value | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 186 | through the accessor after L</new> skips those checks. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 187 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 188 | =head2 redis | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 189 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 190 | Required. Either a Redis client object with the same | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 191 | C<eval($script, $numkeys, @args)> method as L<Redis> and L<Redis::Fast>, or | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 192 | a code reference that returns such an object. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 193 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 194 | Prefer the code reference. It is called the first time this backend is | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 195 | used in each process, so with a pre-forking server such as L<hypnotoad> | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 196 | every worker gets its own connection. A client object made in C<startup> | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 197 | is copied into every worker by C<fork>, and the workers would then share | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 198 | one network connection, which corrupts the replies. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 199 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 200 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 201 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 202 | =head4 Input | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 203 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 204 | # An object is accepted when it can('eval') or has an AUTOLOAD, as the | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 205 | # CPAN Redis client dispatches its commands through AUTOLOAD | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 206 | { redis => { type => ['coderef', 'object'], optional => 1 } } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 207 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 208 | =head4 Output | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 209 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 210 | # Return::Set schema: the value when reading, the object when writing | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 211 | { type => ['coderef', 'object'] } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 212 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 213 | =head2 namespace | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 214 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 215 | The prefix for every Redis key this backend makes. Defaults to | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 216 | C<'buffer:lock:'>. Use a different namespace for each application that | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 217 | shares a Redis database. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 218 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 219 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 220 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 221 | =head4 Input | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 222 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 223 | { namespace => { type => 'string', min => 1, optional => 1 } } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 224 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 225 | =head4 Output | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 226 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 227 | # Return::Set schema: the value when reading, the object when writing | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 228 | { type => 'string', min => 1 } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 229 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 230 | =head2 ttl | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 231 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 232 | How long a lock lives, in seconds. Defaults to 60. Fractions such as | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 233 | C<0.5> are allowed; the value is sent to Redis in whole milliseconds, and | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 234 | never less than 1 millisecond. Choose a value longer than | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 235 | L<cache_lock_timeout|Mojolicious::Plugin::Buffer/cache_lock_timeout> and | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 236 | longer than your slowest cached action. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 237 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 238 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 239 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 240 | =head4 Input | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 241 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 242 | { ttl => { type => 'number', min => 0, optional => 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 243 | matches => qr/^\d+(?:\.\d+)?$/ } } # and > 0 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 244 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 245 | =head4 Output | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 246 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 247 | # Return::Set schema: the value when reading, the object when writing | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 248 | { type => 'number' } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 249 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 250 | =head2 messages | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 251 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 252 | An optional hash of message overrides. See | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 253 | L<Mojolicious::Plugin::Buffer::I18N> for the keys and the text format. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 254 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 255 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 256 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 257 | =head4 Input | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 258 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 259 | { messages => { type => 'hashref', optional => 1 } } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 260 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 261 | =head4 Output | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 262 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 263 | # Return::Set schema: the hash (or undef) when reading, the object | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 264 | # when writing | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 265 | { type => 'hashref', optional => 1 } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 266 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 267 | =head1 METHODS | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 268 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 269 | =head2 new | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 270 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 271 | my $lock = Mojolicious::Plugin::Buffer::Lock::Redis->new(redis => sub { Redis->new }); | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 272 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 273 | =head3 Purpose | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 274 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 275 | Create the backend and check its configuration. No connection is made. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 276 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 277 | =head3 Arguments | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 278 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 279 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 280 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 281 | =item C<redis> (named, required) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 282 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 283 | A client object or a code reference returning one. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 284 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 285 | =item C<namespace> (named, optional) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 286 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 287 | A non-empty string, default C<'buffer:lock:'>. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 288 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 289 | =item C<ttl> (named, optional) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 290 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 291 | A positive number of seconds, default 60. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 292 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 293 | =item C<messages> (named, optional) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 294 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 295 | A hash of message overrides. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 296 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 297 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 298 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 299 | =head3 Returns | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 300 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 301 | The new object. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 302 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 303 | =head3 Side effects | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 304 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 305 | None. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 306 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 307 | =head3 Example | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 308 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 309 | my $lock = Mojolicious::Plugin::Buffer::Lock::Redis->new( | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 310 | redis => sub { Redis->new(server => 'redis.internal:6379') }, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 311 | namespace => 'shop:buffer:', | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 312 | ttl => 30, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 313 | ); | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 314 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 315 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 316 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 317 | =head4 Input | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 318 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 319 | { | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 320 | redis => { type => ['coderef', 'object'] }, # object: eval() or AUTOLOAD | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 321 | namespace => { type => 'string', min => 1, optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 322 | ttl => { type => 'number', min => 0, optional => 1, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 323 | matches => qr/^\d+(?:\.\d+)?$/ }, # and > 0 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 324 | messages => { type => 'hashref', optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 325 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 326 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 327 | =head4 Output | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 328 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 329 | # Return::Set schema | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 330 | { type => 'object', isa => 'Mojolicious::Plugin::Buffer::Lock::Redis' } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 331 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 332 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 333 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 334 | Key Message Resolution | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 335 | ----------------------- ---------------------------------------- ------------------------------- | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 336 | redis_client_invalid cache_lock redis must be an object with Pass a Redis/Redis::Fast object | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 337 | an eval() method or a code reference or, better, a factory sub | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 338 | returning one | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 339 | redis_namespace_invalid cache_lock namespace must be a non-empty Pass e.g. 'myapp:buffer:' | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 340 | string | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 341 | redis_ttl_invalid cache_lock ttl must be a positive number Pass e.g. 60 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 342 | of seconds | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 343 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 344 | All three croak. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 345 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 346 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 347 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 348 | 26 | ▶ | sub new { | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
new: called CC=5 SCAR=16.1
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 349 | 26 | my ($class, @args) = @_; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 350 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 351 | 26 | ▶ | my $self = $class->SUPER::new(get_params(undef, @args) // {}); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Condition50%1/2
get_params(undef, @args) // {}
MC/DC0%0/1
get_params(undef, @args) // {}
get_params(undef, @args)
Truth table50%1/2
A
A= get_params(undef, @args)
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 352 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 353 | 26 | ▶ | croak $self->i18n('redis_client_invalid') unless _valid_client($self->redis); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 354 | 24 | ▶ | croak $self->i18n('redis_namespace_invalid') unless _valid($self, 'namespace'); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 355 | 22 | ▶ | croak $self->i18n('redis_ttl_invalid') unless _valid($self, 'ttl'); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 356 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 357 | 18 | return $self; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 358 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 359 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 360 | =head2 acquire | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 361 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 362 | my ($guard, $error) = $lock->acquire($key); | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 363 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 364 | =head3 Purpose | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 365 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 366 | Try, without waiting, to become the only worker building C<$key>. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 367 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 368 | =head3 Arguments | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 369 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 370 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 371 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 372 | =item C<$key> (positional, required) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 373 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 374 | The cache key: any defined string, in any language, emoji included. Only | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 375 | its MD5 digest is sent to Redis. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 376 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 377 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 378 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 379 | =head3 Returns | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 380 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 381 | C<($guard, undef)> when the lock was acquired, C<(undef, undef)> when | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 382 | another worker holds it, and C<(undef, $error)> when Redis is unavailable. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 383 | The plugin logs an error and continues without a cross-worker lock in the | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 384 | last case. Call it in list context; see L</COMMON PITFALLS>. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 385 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 386 | =head3 Side effects | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 387 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 388 | Connects to Redis on first use (through the factory) and sets a key that | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 389 | expires after L</ttl>. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 390 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 391 | =head3 Example | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 392 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 393 | my ($guard, $error) = $lock->acquire('buffer:0123abcd'); | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 394 | $lock->release($guard) if $guard; | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 395 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 396 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 397 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 398 | =head4 Input | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 399 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 400 | { key => { type => 'string', position => 0 } } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 401 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 402 | =head4 Output | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 403 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 404 | # Return::Set schema (list of two) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 405 | { | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 406 | type => 'arrayref', | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 407 | schema => [ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 408 | { type => 'hashref', optional => 1 }, # guard: {key, token} | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 409 | { type => 'string', optional => 1 }, # error | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 410 | ], | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 411 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 412 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 413 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 414 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 415 | Key Message Resolution | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 416 | ------------------ ---------------------------------------- --------------------------- | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 417 | lock_key_undefined cache key is not defined Pass a defined key | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 418 | redis_lock_failed Redis lock failed: ERROR Check the server and client | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 419 | redis_no_client Redis client factory returned no client Make the factory return one | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 420 | redis_no_result Redis lock command returned no result Check the client library | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 421 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 422 | These are returned, not thrown. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 423 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 424 | =head3 PSEUDOCODE | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 425 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 426 | reject an undefined key | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 427 | derive the Redis key and a fresh token | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 428 | convert the TTL to milliseconds, at least 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 429 | run SET NX PX through the Lua script | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 430 | if the call failed, return the error | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 431 | if it returned nothing, return "no result" | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 432 | if it returned 1, return the guard | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 433 | otherwise return (undef, undef): someone else holds it | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 434 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 435 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 436 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 437 | 32 | ▶ | sub acquire { | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
acquire: called CC=7 SCAR=19.8
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 438 | 32 | my ($self, @args) = @_; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 439 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 440 | # get_params() confesses on an empty list; no key is a returned error | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 441 | 32 | ▶ | my $key = @args ? get_params('key', @args)->{key} : undef; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 442 | 32 | ▶ | return (undef, $self->i18n('lock_key_undefined')) unless defined($key); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 443 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 444 | 32 | my $lock_key = $self->_key($key); | |||||||||||||||||||||||||||||||||||||||||||||||||
| 445 | 32 | my $token = $self->_token; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 446 | 32 | my $ttl = int($self->ttl * $MS_PER_SECOND); | |||||||||||||||||||||||||||||||||||||||||||||||||
| 447 | 32 | ▶ | $ttl = $MIN_TTL_MS if $ttl < $MIN_TTL_MS; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 448 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 449 | 32 | my $outcome = $self->_run_script($ACQUIRE_SCRIPT, $lock_key, $token, $ttl); | |||||||||||||||||||||||||||||||||||||||||||||||||
| 450 | 32 | ▶ | return (undef, $self->i18n('redis_lock_failed', {error => $outcome->{error}})) if defined($outcome->{error}); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 451 | 28 | ▶ | return (undef, $self->i18n('redis_no_result')) unless defined($outcome->{result}); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 452 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 453 | 28 | ▶ | return $outcome->{result} ? ({key => $lock_key, token => $token}, undef) : (undef, undef); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 454 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 455 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 456 | =head2 release | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 457 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 458 | my ($ok, $error) = $lock->release($guard); | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 459 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 460 | =head3 Purpose | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 461 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 462 | Delete the lock, but only if it still holds this guard's token. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 463 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 464 | =head3 Arguments | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 465 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 466 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 467 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 468 | =item C<$guard> (positional, required) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 469 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 470 | A guard returned by L</acquire>. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 471 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 472 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 473 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 474 | =head3 Returns | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 475 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 476 | C<(1, undef)> on success, including when the lock had already expired, and | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 477 | C<(0, $error)> on failure. A failed release is not fatal because the lock | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 478 | expires after L</ttl>. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 479 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 480 | =head3 Side effects | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 481 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 482 | Deletes the Redis key if it still holds the token. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 483 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 484 | =head3 Example | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 485 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 486 | my ($ok, $error) = $lock->release($guard); | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 487 | warn $error unless $ok; | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 488 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 489 | =head3 API SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 490 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 491 | =head4 Input | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 492 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 493 | { guard => { type => 'hashref', position => 0 } } # {key, token} | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 494 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 495 | =head4 Output | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 496 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 497 | # Return::Set schema (list of two) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 498 | { | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 499 | type => 'arrayref', | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 500 | schema => [ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 501 | { type => 'boolean' }, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 502 | { type => 'string', optional => 1 }, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 503 | ], | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 504 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 505 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 506 | =head3 MESSAGES | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 507 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 508 | Key Message Resolution | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 509 | ------------------- ---------------------------- ------------------------------ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 510 | redis_invalid_guard invalid lock guard Pass the guard acquire returned | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 511 | redis_unlock_failed Redis unlock failed: ERROR None needed; the TTL expires it | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 512 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 513 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 514 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 515 | 24 | ▶ | sub release { | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
release: called CC=6 SCAR=18.0
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 516 | 24 | my ($self, $guard) = @_; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 517 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 518 | 24 | ▶ | my $valid = (ref($guard) eq 'HASH') && defined($guard->{key}) && defined($guard->{token}); | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Condition66%4/6
ref $guard eq 'HASH' && defined $guard->{'key'} && defined $guard->{'token'}
ref $guard eq "HASH" and defined $guard->{"key"}
MC/DC33%1/3
ref $guard eq 'HASH' && defined $guard->{'key'} && defined $guard->{'token'}
ref $guard eq "HASH"
defined $guard->{"key"}
defined $guard->{'token'}
Truth table50%2/4
A and B && C
A= ref $guard eq "HASH"B= defined $guard->{"key"}C= defined $guard->{'token'}
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 519 | 24 | ▶ | my $outcome = $valid ? $self->_run_script($RELEASE_SCRIPT, $guard->{key}, $guard->{token}) : {}; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 520 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 521 | # An expired lock (script result 0) is still a successful release | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 522 | return !$valid ? (0, $self->i18n('redis_invalid_guard')) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 523 | 24 | ▶ | : defined($outcome->{error}) ? (0, $self->i18n('redis_unlock_failed', {error => $outcome->{error}})) | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 524 | : (1, undef); | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 525 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 526 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 527 | # Purpose: Run one of the Lua scripts against a single key. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 528 | # Entry criteria: $script is Lua; $key and @argv are strings. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 529 | # Exit status: {result => $value} on success, {error => $text} when the | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 530 | # factory returned nothing or the client died. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 531 | # Side effects: Network round trip; may create the per-worker client. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 532 | 54 | ▶ | sub _run_script :Private { | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_run_script: called CC=6 SCAR=18.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 533 | 54 | my ($self, $script, $key, @argv) = @_; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 534 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 535 | 54 | my $redis = eval { $self->_client }; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 536 | 54 | my $error = $@; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 537 | 54 | ▶ | $error = $self->i18n('redis_no_client') if !$error && !$redis; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
$error or $redis
MC/DC0%0/2
$error or $redis
$error
$redis
Truth table66%2/3
A or B
A= $errorB= $redis
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 538 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 539 | 54 | ▶ | my $result = $error ? undef : eval { $redis->eval($script, 1, $key, @argv) }; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 540 | 54 | ▶ | $error ||= $@; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Condition100%3/3
$error ||= $@
MC/DC100%2/2
$error ||= $@
$error
$@
Truth table100%3/3
A ||= B
A= $errorB= $@
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 541 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 542 | 54 | ▶ | return $error ? {error => trim("$error")} : {result => $result}; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 543 | 10 | ▶ | } | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 544 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 545 | # Purpose: Return the Redis client, calling the factory once. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 546 | # Entry criteria: redis is an object or a code reference. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 547 | # Exit status: The client, or whatever the factory returned. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 548 | # Side effects: Caches the factory result for this object; may die if | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 549 | # the factory dies. Protected so a subclass can supply a | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 550 | # pooled or sentinel-aware client. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 551 | 54 | ▶ | sub _client :Protected { | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_client: called CC=3 SCAR=11.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 552 | 54 | my $self = shift; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 553 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 554 | 54 | my $redis = $self->redis; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 555 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 556 | # Called lazily, so a pre-forking server gets one connection per worker | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 557 | 54 | ▶ | return ref($redis) eq 'CODE' ? ($self->{client} //= $redis->()) : $redis; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
$self->{"client"} //= &$redis()
MC/DC0%0/2
$self->{"client"} //= &$redis()
$self->{"client"}
&$redis()
Truth table66%2/3
A //= B
A= $self->{"client"}B= &$redis()
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 558 | 10 | ▶ | } | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 559 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 560 | # Purpose: Map a cache key to its Redis key. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 561 | # Entry criteria: $key is a defined string. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 562 | # Exit status: namespace followed by the MD5 of the key. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 563 | # Side effects: None. Protected so a subclass can add e.g. a hash tag | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 564 | # for Redis Cluster slot placement. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 565 | 32 | ▶ | sub _key :Protected { | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_key: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 566 | 32 | my ($self, $key) = @_; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 567 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 568 | # md5_sum dies on characters above 255, so hash the UTF-8 bytes | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 569 | 32 | return $self->namespace . md5_sum(encode('UTF-8', $key)); | |||||||||||||||||||||||||||||||||||||||||||||||||
| 570 | 10 | ▶ | } | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 571 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 572 | # Purpose: Produce a token that no other acquisition will share. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 573 | # Entry criteria: None. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 574 | # Exit status: A 32-character hex string. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 575 | # Side effects: Increments the per-process counter. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 576 | 32 | ▶ | sub _token :Protected { | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_token: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 577 | 32 | my $self = shift; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 578 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 579 | 32 | return md5_sum(join "\0", $$, Time::HiRes::time(), ++$TOKEN_COUNTER, rand(), refaddr($self)); | |||||||||||||||||||||||||||||||||||||||||||||||||
| 580 | 10 | ▶ | } | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 581 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 582 | # Purpose: Check a client value without connecting. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 583 | # Entry criteria: Any scalar. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 584 | # Exit status: True for a code reference, or an object with eval() or an | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 585 | # AUTOLOAD that will provide it. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 586 | # Side effects: None. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 587 | 26 | ▶ | sub _valid_client :Private { | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_valid_client: called CC=4 SCAR=14.1
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 588 | 26 | my $redis = shift; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 589 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 590 | 26 | ▶ | return (ref($redis) eq 'CODE') | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Condition77%7/9
ref $redis eq 'CODE' || builtin::blessed($redis) && ($redis->can('eval') || $redis->can('AUTOLOAD'))
builtin::blessed($redis) and $redis->can("eval") || $redis->can("AUTOLOAD")
$redis->can("eval") or $redis->can("AUTOLOAD")
MC/DC50%2/4
ref $redis eq 'CODE' || builtin::blessed($redis) && ($redis->can('eval') || $redis->can('AUTOLOAD'))
ref $redis eq 'CODE'
builtin::blessed($redis)
$redis->can("eval")
$redis->can("AUTOLOAD")
Truth table80%4/5
A || B and C or D
A= ref $redis eq 'CODE'B= builtin::blessed($redis)C= $redis->can("eval")D= $redis->can("AUTOLOAD")
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 591 | || (blessed($redis) && ($redis->can('eval') || $redis->can('AUTOLOAD'))); | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 592 | 10 | ▶ | } | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 593 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 594 | # Purpose: Validate one attribute against %NEW_SCHEMA. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 595 | # Entry criteria: $self is constructed; $name is a key of %NEW_SCHEMA. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 596 | # Exit status: True if the attribute's value is acceptable. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 597 | # Side effects: None. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 598 | 46 | ▶ | sub _valid :Private { | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
_valid: called CC=2 SCAR=7.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 599 | 46 | my ($self, $name) = @_; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 600 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 601 | 46 | my $value = $self->$name; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 602 | 46 | ▶ | return !ref($value) && eval { validate_strict(schema => {$name => $NEW_SCHEMA{$name}}, input => {$name => $value}); 1 }; | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Condition66%2/3
!ref($value) && eval {
do {
validate_strict('schema', {$name, $NEW_SCHEMA{$name}}, 'input', {$name, $value});
1
}
}
MC/DC50%1/2
!ref($value) && eval {
do {
validate_strict('schema', {$name, $NEW_SCHEMA{$name}}, 'input', {$name, $value});
1
}
}
!ref($value)
eval {
do {
validate_strict('schema', {$name, $NEW_SCHEMA{$name}}, 'input', {$name, $value});
1
}
}
Truth table66%2/3
not(A) && B
A= !ref($value)B= eval {
do {
validate_strict('schema', {$name, $NEW_SCHEMA{$name}}, 'input', {$name, $value});
1
}
}
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 603 | 10 | ▶ | } | ||||||||||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||||||||||
| 604 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 605 | 10 | 1; | |||||||||||||||||||||||||||||||||||||||||||||||||
| 606 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 607 | =head1 COMMON PITFALLS | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 608 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 609 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 610 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 611 | =item * B<Always take both return values.> L</acquire> returns a list of | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 612 | two values. In scalar context Perl gives you only the I<last> one, the | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 613 | error slot: | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 614 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 615 | my $guard = $lock->acquire($key); # WRONG: $guard is undef | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 616 | my ($guard, $error) = $lock->acquire($key); # right | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 617 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 618 | Here the mistake is costly. The lock I<was> taken in Redis, but you have | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 619 | lost the token, so you cannot release it. Every worker then sees "busy" for | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 620 | that key until the L</ttl> runs out. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 621 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 622 | =item * B<The TTL is too short.> If the builder is still working when the | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 623 | lock expires, a second worker can take the lock and build the same entry. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 624 | Make L</ttl> longer than the slowest action that uses the cache. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 625 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 626 | =item * B<A client object made before the fork.> Pass a code reference as | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 627 | L</redis>, not an object made in C<startup>. Also, do not call L</acquire> | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 628 | in C<startup>: the first call stores the client, and C<fork> would then copy | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 629 | it into every worker. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 630 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 631 | =item * B<A slow Redis server slows every cached request.> The call waits | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 632 | for Redis. Set C<cnx_timeout>, C<read_timeout> and C<write_timeout> on the | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 633 | client. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 634 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 635 | =item * B<Changing attributes after C<new>.> C<< $lock->ttl(0) >> is not | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 636 | checked; Redis is then sent the smallest TTL, 1 millisecond, and the lock | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 637 | protects nothing. Set attributes with L</new> only. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 638 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 639 | =item * B<The lock is not re-entrant.> A second C<acquire> for a key this | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 640 | worker already holds returns "busy" C<(undef, undef)>. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 641 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 642 | =item * B<undef values.> C<acquire(undef)> returns | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 643 | C<(undef, 'cache key is not defined')>. C<release(undef)> returns | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 644 | C<(0, 'invalid lock guard')>. A factory that returns C<undef> gives | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 645 | C<(undef, 'Redis lock failed: Redis client factory returned no client')>, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 646 | and is asked again on the next call. C<< new(ttl =E<gt> undef) >> and | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 647 | C<< new(namespace =E<gt> undef) >> croak. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 648 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 649 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 650 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 651 | =head1 ENCODING | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 652 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 653 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 654 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 655 | =item Keys | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 656 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 657 | Any Perl string is safe, including accented letters, other non-ASCII text | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 658 | and emoji. The key is encoded as UTF-8 bytes and hashed, so only an ASCII | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 659 | digest is sent to Redis. A subclass that overrides C<_key> must encode | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 660 | before calling C<md5_sum>, which dies on a character above U+00FF. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 661 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 662 | =item namespace | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 663 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 664 | Sent to Redis as part of the key. Keep it ASCII. Redis keys are bytes, so | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 665 | a non-ASCII namespace must be encoded to bytes by you first. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 666 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 667 | =item messages | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 668 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 669 | Override texts may hold any characters, including emoji. The messages this | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 670 | module returns are Perl character strings; print them through an encoding | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 671 | layer such as C<:encoding(UTF-8)>, or Perl warns "Wide character". | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 672 | L<Mojo::Log> encodes to UTF-8 by itself. The text after C<ERROR> comes from | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 673 | the Redis client and is passed on unchanged. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 674 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 675 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 676 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 677 | =head1 LIMITATIONS | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 678 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 679 | =over 4 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 680 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 681 | =item * The client is called synchronously inside a request. A slow or | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 682 | partitioned Redis server stalls that worker for as long as the client's own | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 683 | timeouts allow; there is no circuit breaker. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 684 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 685 | =item * This is a single-instance lock, not Redlock. With Redis replication, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 686 | a fail-over can lose a lock that was just set, and two builders may run. For | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 687 | a cache that is acceptable: the cost is one duplicated build, not corrupted | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 688 | data. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 689 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 690 | =item * A lock that outlives L</ttl> is silently lost, and a second builder | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 691 | can start. Choose a TTL longer than the slowest cached action. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 692 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 693 | =back | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 694 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 695 | =head1 SEE ALSO | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 696 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 697 | L<Mojolicious::Plugin::Buffer>, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 698 | L<Mojolicious::Plugin::Buffer::Lock::File>, | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 699 | L<Mojolicious::Plugin::Buffer::I18N>. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 700 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 701 | =head1 AUTHOR | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 702 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 703 | Nigel Horne, C<< <njh at bandsman.co.uk> >> | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 704 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 705 | =head1 FORMAL SPECIFICATION | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 706 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 707 | This section describes the backend in the Z notation, for readers who want | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 708 | an exact model. You do not need it to use the module. C<store> is the part | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 709 | of the Redis database that this backend uses, C<expiry> says when each of | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 710 | its keys disappears, and C<now> is the current time. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 711 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 712 | [KEY, TEXT, TOKEN, Client] | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 713 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 714 | rkey : KEY → TEXT | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 715 | ∀ k : KEY • rkey k = namespace ⁀ md5(utf8(k)) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 716 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 717 | Guard == TEXT × TOKEN | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 718 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 719 | ┌─ Redis ───────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 720 | │ namespace : seq₁ CHAR | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 721 | │ ttl : ℝ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 722 | │ client : Client ∪ {⊥} | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 723 | │ store : TEXT ⇸ TOKEN | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 724 | │ expiry : TEXT ⇸ ℝ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 725 | ├───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 726 | │ ttl > 0 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 727 | │ dom expiry = dom store | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 728 | └───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 729 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 730 | ┌─ Expire ──────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 731 | │ ΔRedis | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 732 | ├───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 733 | │ store′ = { r : dom store | expiry r ≤ now } ⩤ store | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 734 | │ expiry′ = { r : dom store | expiry r ≤ now } ⩤ expiry | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 735 | └───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 736 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 737 | =head2 new | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 738 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 739 | ┌─ NewRedisLock ────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 740 | │ Redis′ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 741 | │ redis? : Client ∪ (seq ARG → Client) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 742 | │ namespace? : seq₁ CHAR ; ttl? : ℝ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 743 | │ result! : Redis | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 744 | ├───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 745 | │ ttl? > 0 | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 746 | │ namespace′ = namespace? ∧ ttl′ = ttl? | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 747 | │ client′ = ⊥ ⇐ redis? is a code reference | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 748 | │ result! = θRedis′ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 749 | └───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 750 | -- No connection is made. Any violated predicate: croak. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 751 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 752 | =head2 acquire | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 753 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 754 | C<reachable> means the client could be made and answered. C<token> is | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 755 | fresh: it differs from every token issued before. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 756 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 757 | ┌─ AcquireRedis ────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 758 | │ ΔRedis | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 759 | │ key? : KEY ; token : TOKEN | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 760 | │ guard! : Guard ∪ {⊥} ; error! : TEXT ∪ {⊥} | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 761 | ├───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 762 | │ let r == rkey key? • | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 763 | │ reachable ∧ r ∉ dom store ⇒ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 764 | │ store′ = store ⊕ {r ↦ token} | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 765 | │ ∧ expiry′ = expiry ⊕ {r ↦ now + max(ttl, 0.001)} | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 766 | │ ∧ guard! = (r, token) ∧ error! = ⊥ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 767 | │ reachable ∧ r ∈ dom store ⇒ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 768 | │ store′ = store ∧ guard! = ⊥ ∧ error! = ⊥ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 769 | │ ¬reachable ⇒ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 770 | │ store′ = store ∧ guard! = ⊥ ∧ error! ≠ ⊥ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 771 | └───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 772 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 773 | =head2 release | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 774 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 775 | ┌─ ReleaseRedis ────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 776 | │ ΔRedis | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 777 | │ guard? : Guard ∪ {⊥} ; ok! : 𝔹 ; error! : TEXT ∪ {⊥} | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 778 | ├───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 779 | │ guard? = ⊥ ⇒ store′ = store ∧ ok! = false ∧ error! ≠ ⊥ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 780 | │ guard? = (r, t) ∧ store r = t ⇒ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 781 | │ store′ = {r} ⩤ store ∧ ok! = true | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 782 | │ guard? = (r, t) ∧ (r ∉ dom store ∨ store r ≠ t) ⇒ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 783 | │ store′ = store ∧ ok! = true | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 784 | │ ¬reachable ⇒ store′ = store ∧ ok! = false ∧ error! ≠ ⊥ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 785 | └───────────────────────────────────────────── | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 786 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 787 | =head1 STATE DIAGRAM | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 788 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 789 | Each cache key's lock, as Redis sees it. The numbers on the arrows are | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 790 | explained below the picture. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 791 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 792 | +-----------+ (1) +----------------+ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 793 | | FREE | --------------------------> | HELD (token) | | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 794 | | (key k) | <-------------------------- | | | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 795 | +-----------+ (2) or (3) +----------------+ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 796 | | ^ | ^ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 797 | +-----+ (4) +-----+ (5), (6) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 798 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 799 | (1) acquire(k) [Redis answers and the key is absent] | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 800 | / SET key token NX PX ttl; returns ({key, token}, undef) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 801 | (2) release(guard) [the stored token matches the guard] | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 802 | / the Lua script deletes the key; returns (1, undef) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 803 | (3) the TTL runs out | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 804 | / Redis deletes the key by itself. If the holder is still | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 805 | building, a second worker can now start building as well. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 806 | (4) acquire(k) [Redis is unreachable, or the factory gave no client] | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 807 | / returns (undef, error); nothing changes | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 808 | (5) acquire(k) [the key is present], from any worker, the holder too | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 809 | / returns (undef, undef); nothing changes | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 810 | (6) release(old guard) [the token differs: this lock expired and | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 811 | another worker took the key] | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 812 | / nothing is deleted; returns (1, undef) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 813 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 814 | The backend object itself has one more state, for its client: | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 815 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 816 | +----------------+ first acquire() or release() in this process | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 817 | | NO CLIENT YET | [redis is a code reference] +---------+ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 818 | | (after new) | -------------------------------------> | CLIENT | | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 819 | +----------------+ / call the factory once; keep result | READY | | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 820 | | ^ +---------+ | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 821 | +---+ the factory returned undef or died | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 822 | / the call returns (undef, error); try again next time | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 823 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 824 | When L</redis> is an object rather than a code reference, the backend | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 825 | starts in CLIENT READY. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 826 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 827 | The plugin's own use of these states is drawn in | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 828 | L<Mojolicious::Plugin::Buffer/STATE DIAGRAM>. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 829 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 830 | =head1 LICENSE AND COPYRIGHT | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 831 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 832 | Copyright 2026 Nigel Horne. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 833 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 834 | This program is free software; you can redistribute it and/or modify it | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 835 | under the terms of the GNU General Public License as published by the Free | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 836 | Software Foundation; either version 2 of the License, or (at your option) | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 837 | any later version. | ||||||||||||||||||||||||||||||||||||||||||||||||||
| 838 | |||||||||||||||||||||||||||||||||||||||||||||||||||
| 839 | =cut | ||||||||||||||||||||||||||||||||||||||||||||||||||