1MCE::Shared::Cache(3) User Contributed Perl DocumentationMCE::Shared::Cache(3)
2
3
4

NAME

6       MCE::Shared::Cache - A hybrid LRU-plain cache helper class
7

VERSION

9       This document describes MCE::Shared::Cache version 1.880
10

DESCRIPTION

12       A cache helper class for use as a standalone or managed by MCE::Shared.
13
14       This module implements a least-recently used (LRU) cache with its
15       origin based on MCE::Shared::Ordhash, for its performance and low-
16       memory characteristics.  It is both a LRU and plain implementation. LRU
17       logic is applied to new items and subsequent updates. A fetch however,
18       involves LRU reorder only if the item is found in the lower section of
19       the cache. This equates to extra performance for the upper section as
20       fetch behaves similarly to accessing a plain cache.  Upon reaching its
21       size restriction, it prunes items from the bottom of the cache.
22
23       The 50% LRU-mode (bottom section), 50% plain-mode (upper-section)
24       applies to fetches only.
25

SYNOPSIS

27        # non-shared or local construction for use by a single process
28
29        use MCE::Shared::Cache;
30
31        my $ca;
32
33        $ca = MCE::Shared::Cache->new(); # max_keys => undef, max_age => undef
34        $ca = MCE::Shared::Cache->new( { max_keys => 500 }, @pairs );
35
36        $ca = MCE::Shared::Cache->new( max_keys => "unlimited", max_age => "never" );
37        $ca = MCE::Shared::Cache->new( max_keys => undef, max_age => undef ); # ditto
38        $ca = MCE::Shared::Cache->new( max_keys => 500, max_age => "1 hour" );
39        $ca = MCE::Shared::Cache->new( max_keys => "4 KiB" ); # 4*1024
40        $ca = MCE::Shared::Cache->new( max_keys => "1 MiB" ); # 1*1024*1024
41
42        $ca = MCE::Shared::Cache->new( max_age  => "43200 seconds" );
43        $ca = MCE::Shared::Cache->new( max_age  => 43200 );   # ditto
44        $ca = MCE::Shared::Cache->new( max_age  => "720 minutes" );
45        $ca = MCE::Shared::Cache->new( max_age  => "12 hours" );
46        $ca = MCE::Shared::Cache->new( max_age  => "0.5 days" );
47        $ca = MCE::Shared::Cache->new( max_age  => "1 week" );
48        $ca = MCE::Shared::Cache->new( max_age  => undef );   # no expiration
49        $ca = MCE::Shared::Cache->new( max_age  => 0 );       # now
50
51        # construction for sharing with other threads and processes
52
53        use MCE::Shared;
54
55        my $ca;
56
57        $ca = MCE::Shared->cache(); # max_keys => undef, max_age => undef
58        $ca = MCE::Shared->cache( { max_keys => 500 }, @pairs );
59
60        $ca = MCE::Shared->cache( max_keys => "unlimited", max_age => "never" );
61        $ca = MCE::Shared->cache( max_keys => undef, max_age => undef ); # ditto
62        $ca = MCE::Shared->cache( max_keys => 500, max_age => "1 hour" );
63        $ca = MCE::Shared->cache( max_keys => "4 KiB" ); # 4*1024
64        $ca = MCE::Shared->cache( max_keys => "1 MiB" ); # 1*1024*1024
65
66        $ca = MCE::Shared->cache( max_age  => "43200 seconds" );
67        $ca = MCE::Shared->cache( max_age  => 43200 );   # ditto
68        $ca = MCE::Shared->cache( max_age  => "720 minutes" );
69        $ca = MCE::Shared->cache( max_age  => "12 hours" );
70        $ca = MCE::Shared->cache( max_age  => "0.5 days" );
71        $ca = MCE::Shared->cache( max_age  => "1 week" );
72        $ca = MCE::Shared->cache( max_age  => undef );   # no expiration
73        $ca = MCE::Shared->cache( max_age  => 0 );       # now
74
75        # hash-like dereferencing
76
77        my $val = $ca->{$key};
78        $ca->{$key} = $val;
79
80        %{$ca} = ();
81
82        # OO interface
83
84        if ( !defined ( $val = $ca->get("some_key") ) ) {
85           $val = $ca->set( some_key => "some_value" );
86        }
87
88        $val   = $ca->set( $key, $val );
89        $ret   = $ca->setnx( $key, $val );         # set only if the key exists
90        $val   = $ca->get( $key );
91        $val   = $ca->delete( $key );              # del is an alias for delete
92        $bool  = $ca->exists( $key );
93        void   = $ca->clear();
94        $len   = $ca->len();                       # scalar keys %{ $ca }
95        $len   = $ca->len( $key );                 # length $ca->{ $key }
96
97        $iter  = $ca->iterator( @keys );           # ($key, $val) = $iter->()
98        @keys  = $ca->keys( @keys );               # @keys is optional
99        %pairs = $ca->pairs( @keys );
100        @vals  = $ca->values( @keys );             # vals is an alias for values
101
102        $len   = $ca->assign( $key/$val pairs );   # equivalent to ->clear, ->mset
103        $cnt   = $ca->mdel( @keys );
104        @vals  = $ca->mget( @keys );
105        $bool  = $ca->mexists( @keys );            # true if all keys exists
106        $len   = $ca->mset( $key/$val pairs );     # merge is an alias for mset
107
108        # included, sugar methods without having to call set/get explicitly
109
110        $len   = $ca->append( $key, $string );     #   $val .= $string
111        $val   = $ca->decr( $key );                # --$val
112        $val   = $ca->decrby( $key, $number );     #   $val -= $number
113        $val   = $ca->getdecr( $key );             #   $val--
114        $val   = $ca->getincr( $key );             #   $val++
115        $val   = $ca->incr( $key );                # ++$val
116        $val   = $ca->incrby( $key, $number );     #   $val += $number
117        $old   = $ca->getset( $key, $new );        #   $o = $v, $v = $n, $o
118
119        # pipeline, provides atomicity for shared objects, MCE::Shared v1.09+
120
121        @vals  = $ca->pipeline(                    # ( "a_a", "b_b", "c_c" )
122           [ "set", foo => "a_a" ],
123           [ "set", bar => "b_b" ],
124           [ "set", baz => "c_c" ],
125           [ "mget", qw/ foo bar baz / ]
126        );
127
128       For normal hash behavior, the TIE interface is supported.
129
130        # non-shared or local construction for use by a single process
131
132        use MCE::Shared::Cache;
133
134        tie my %ca, "MCE::Shared::Cache", max_keys => undef, max_age => undef;
135        tie my %ca, "MCE::Shared::Cache", max_keys => 500, max_age => "1 hour";
136        tie my %ca, "MCE::Shared::Cache", { max_keys => 500 }, @pairs;
137
138        # construction for sharing with other threads and processes
139        # one option is needed minimally to know to use MCE::Shared::Cache
140
141        use MCE::Shared;
142
143        tie my %ca, "MCE::Shared", max_keys => undef, max_age => undef;
144        tie my %ca, "MCE::Shared", max_keys => 500, max_age => "1 hour";
145        tie my %ca, "MCE::Shared", { max_keys => 500 }, @pairs;
146
147        # usage
148
149        my $val;
150
151        if ( !defined ( $val = $ca{some_key} ) ) {
152           $val = $ca{some_key} = "some_value";
153        }
154
155        $ca{some_key} = 0;
156
157        tied(%ca)->incrby("some_key", 20);
158        tied(%ca)->incrby(some_key => 20);
159

SYNTAX for QUERY STRING

161       Several methods take a query string for an argument. The format of the
162       string is described below. In the context of sharing, the query
163       mechanism is beneficial for the shared-manager process. It is able to
164       perform the query where the data resides versus the client-process grep
165       locally involving lots of IPC.
166
167        o Basic demonstration
168
169          @keys = $ca->keys( "query string given here" );
170          @keys = $ca->keys( "val =~ /pattern/" );
171
172        o Supported operators: =~ !~ eq ne lt le gt ge == != < <= > >=
173        o Multiple expressions delimited by :AND or :OR, mixed case allowed
174
175          "key eq 'some key' :or (val > 5 :and val < 9)"
176          "key eq some key :or (val > 5 :and val < 9)"
177          "key =~ /pattern/i :And val =~ /pattern/i"
178          "val eq foo baz :OR key !~ /pattern/i"
179
180          * key matches on keys in the cache
181          * likewise, val matches on values
182
183        o Quoting is optional inside the string
184
185          "key =~ /pattern/i :AND val eq 'foo bar'"   # val eq "foo bar"
186          "key =~ /pattern/i :AND val eq foo bar"     # val eq "foo bar"
187
188       Examples.
189
190        # search capability key/val: =~ !~ eq ne lt le gt ge == != < <= > >=
191        # key/val means to match against actual key/val respectively
192
193        @keys  = $ca->keys( "key eq 'some key' :or (val > 5 :and val < 9)" );
194        @keys  = $ca->keys( "key eq some key :or (val > 5 :and val < 9)" );
195
196        @keys  = $ca->keys( "key =~ /$pattern/i" );
197        @keys  = $ca->keys( "key !~ /$pattern/i" );
198        @keys  = $ca->keys( "val =~ /$pattern/i" );
199        @keys  = $ca->keys( "val !~ /$pattern/i" );
200
201        %pairs = $ca->pairs( "key == $number" );
202        %pairs = $ca->pairs( "key != $number :and val > 100" );
203        %pairs = $ca->pairs( "key <  $number :or key > $number" );
204        %pairs = $ca->pairs( "val <= $number" );
205        %pairs = $ca->pairs( "val >  $number" );
206        %pairs = $ca->pairs( "val >= $number" );
207
208        @vals  = $ca->vals( "key eq $string" );
209        @vals  = $ca->vals( "key ne $string with space" );
210        @vals  = $ca->vals( "key lt $string :or val =~ /$pat1|$pat2/" );
211        @vals  = $ca->vals( "val le $string :and val eq 'foo bar'" );
212        @vals  = $ca->vals( "val le $string :and val eq foo bar" );
213        @vals  = $ca->vals( "val gt $string" );
214        @vals  = $ca->vals( "val ge $string" );
215

API DOCUMENTATION

217       This module involves TIE when accessing the object via hash-like
218       behavior.  Both non-shared and shared instances are impacted if doing
219       so. Although likely fast enough for many use cases, the OO interface is
220       recommended for best performance.
221
222       Accessing an item is likely to involve moving its key to the top of the
223       cache.  Various methods described below state with "Reorder: Yes" or
224       "Reorder: No" as an indication.
225
226       The methods "keys", "pairs", and "values" return the most frequently
227       accessed items from the upper section of the cache first before the
228       lower section. Returned values may not be ordered as expected. This
229       abnormally is normal for this hybrid LRU-plain implementation. It comes
230       from fetches not involving LRU movement on keys residing in the upper
231       section of the cache.
232
233       When "max_age" is set, accessing an item which has expired will behave
234       similarly to a non-existing item.
235
236   MCE::Shared::Cache->new ( { options }, key, value [, key, value, ... ] )
237   MCE::Shared->cache ( { options }, key, value [, key, value, ... ] )
238       Constructs a new object.
239
240        # non-shared or local construction for use by a single process
241
242        use MCE::Shared::Cache;
243
244        $ca = MCE::Shared::Cache->new(); # max_keys => undef, max_age => undef
245        $ca = MCE::Shared::Cache->new( { max_keys => 500 }, @pairs );
246
247        $ca = MCE::Shared::Cache->new( max_keys => "unlimited", max_age => "never" );
248        $ca = MCE::Shared::Cache->new( max_keys => undef, max_age => undef ); # ditto
249        $ca = MCE::Shared::Cache->new( max_keys => 500, max_age => "1 hour" );
250        $ca = MCE::Shared::Cache->new( max_keys => "4 KiB" ); # 4*1024
251        $ca = MCE::Shared::Cache->new( max_keys => "1 MiB" ); # 1*1024*1024
252
253        $ca = MCE::Shared::Cache->new( max_age  => "43200 seconds" );
254        $ca = MCE::Shared::Cache->new( max_age  => 43200 );   # ditto
255        $ca = MCE::Shared::Cache->new( max_age  => "720 minutes" );
256        $ca = MCE::Shared::Cache->new( max_age  => "12 hours" );
257        $ca = MCE::Shared::Cache->new( max_age  => "0.5 days" );
258        $ca = MCE::Shared::Cache->new( max_age  => "1 week" );
259        $ca = MCE::Shared::Cache->new( max_age  => undef );   # no expiration
260        $ca = MCE::Shared::Cache->new( max_age  => 0 );       # now
261
262        $ca->assign( @pairs );
263
264        # construction for sharing with other threads and processes
265
266        use MCE::Shared;
267
268        $ca = MCE::Shared->cache(); # max_keys => undef, max_age => undef
269        $ca = MCE::Shared->cache( { max_keys => 500 }, @pairs );
270
271        $ca = MCE::Shared->cache( max_keys => "unlimited", max_age => "never" );
272        $ca = MCE::Shared->cache( max_keys => undef, max_age => undef ); # ditto
273        $ca = MCE::Shared->cache( max_keys => 500, max_age => "1 hour" );
274        $ca = MCE::Shared->cache( max_keys => "4 KiB" ); # 4*1024
275        $ca = MCE::Shared->cache( max_keys => "1 MiB" ); # 1*1024*1024
276
277        $ca = MCE::Shared->cache( max_age  => "43200 seconds" );
278        $ca = MCE::Shared->cache( max_age  => 43200 );   # ditto
279        $ca = MCE::Shared->cache( max_age  => "720 minutes" );
280        $ca = MCE::Shared->cache( max_age  => "12 hours" );
281        $ca = MCE::Shared->cache( max_age  => "0.5 days" );
282        $ca = MCE::Shared->cache( max_age  => "1 week" );
283        $ca = MCE::Shared->cache( max_age  => undef );   # no expiration
284        $ca = MCE::Shared->cache( max_age  => 0 );       # now
285
286        $ca->assign( @pairs );
287
288       Reorder: Yes, when given key-value pairs contain duplicate keys
289
290   assign ( key, value [, key, value, ... ] )
291       Clears the cache, then sets multiple key-value pairs and returns the
292       number of keys stored in the cache. This is equivalent to "clear",
293       "mset".
294
295        $len = $ca->assign( "key1" => "val1", "key2" => "val2" );
296
297       Reorder: Yes, when given key-value pairs contain duplicate keys
298
299   clear
300       Removes all key-value pairs from the cache.
301
302        $ca->clear;
303        %{$ca} = ();
304
305   delete ( key )
306       Deletes and returns the value by given key or "undef" if the key does
307       not exists in the cache.
308
309        $val = $ca->delete( "some_key" );
310        $val = delete $ca->{ "some_key" };
311
312   del
313       "del" is an alias for "delete".
314
315   exists ( key )
316       Determines if a key exists in the cache.
317
318        if ( $ca->exists( "some_key" ) ) { ... }
319        if ( exists $ca->{ "some_key" } ) { ... }
320
321       Reorder: No
322
323   get ( key )
324       Gets the value of a cache key or "undef" if the key does not exists.
325       LRU reordering occurs only if the key is found in the lower section of
326       the cache. See "peek" to not promote the key internally to the top of
327       the list.
328
329        $val = $ca->get( "some_key" );
330        $val = $ca->{ "some_key" };
331
332       Reorder: Yes
333
334   iterator ( key [, key, ... ] )
335       When "max_age" is set, prunes any expired keys at the head of the list.
336
337       Returns a code reference for iterating a list of key-value pairs stored
338       in the cache when no arguments are given. Otherwise, returns a code
339       reference for iterating the given keys in the same order. Keys that do
340       not exist will have the "undef" value.
341
342       The list of keys to return is set when the closure is constructed.
343       Later keys added to the hash are not included. Subsequently, the
344       "undef" value is returned for deleted keys.
345
346        $iter = $ca->iterator;
347        $iter = $ca->iterator( "key1", "key2" );
348
349        while ( my ( $key, $val ) = $iter->() ) {
350           ...
351        }
352
353       Reorder: No
354
355   iterator ( "query string" )
356       When "max_age" is set, prunes any expired keys at the head of the list.
357
358       Returns a code reference for iterating a list of key-value pairs that
359       match the given criteria. It returns an empty list if the search found
360       nothing.  The syntax for the "query string" is described above.
361
362        $iter = $ca->iterator( "val eq some_value" );
363        $iter = $ca->iterator( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
364        $iter = $ca->iterator( "val eq sun :OR val eq moon :OR val eq foo" );
365        $iter = $ca->iterator( "key =~ /$pattern/" );
366
367        while ( my ( $key, $val ) = $iter->() ) {
368           ...
369        }
370
371       Reorder: No
372
373   keys ( key [, key, ... ] )
374       When "max_age" is set, prunes any expired keys at the head of the list.
375
376       Returns all keys in the cache by most frequently accessed when no
377       arguments are given. Otherwise, returns the given keys in the same
378       order. Keys that do not exist will have the "undef" value. In scalar
379       context, returns the size of the cache.
380
381        @keys = $ca->keys;
382        @keys = $ca->keys( "key1", "key2" );
383        $len  = $ca->keys;
384
385       Reorder: No
386
387   keys ( "query string" )
388       When "max_age" is set, prunes any expired keys at the head of the list.
389
390       Returns only keys that match the given criteria. It returns an empty
391       list if the search found nothing. The syntax for the "query string" is
392       described above. In scalar context, returns the size of the resulting
393       list.
394
395        @keys = $ca->keys( "val eq some_value" );
396        @keys = $ca->keys( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
397        @keys = $ca->keys( "val eq sun :OR val eq moon :OR val eq foo" );
398        $len  = $ca->keys( "key =~ /$pattern/" );
399
400       Reorder: No
401
402   len ( key )
403       When "max_age" is set, prunes any expired keys at the head of the list.
404
405       Returns the size of the cache when no arguments are given. For the
406       given key, returns the length of the value stored at key or the "undef"
407       value if the key does not exists.
408
409        $size = $ca->len;
410        $len  = $ca->len( "key1" );
411        $len  = length $ca->{ "key1" };
412
413       Reorder: Yes, only when key is given
414
415   max_age ( [ secs ] )
416       Returns the maximum age set on the cache or "never" if not defined
417       internally.  It sets the default expiry time when seconds is given.
418
419        $age = $ca->max_age;
420
421        $ca->max_age( "43200 seconds" );
422        $ca->max_age( 43200 );     # ditto
423        $ca->max_age( "720 minutes" );
424        $ca->max_age( "12 hours" );
425        $ca->max_age( "0.5 days" );
426        $ca->max_age( "1 week" );
427        $ca->max_age( undef );     # no expiration
428        $ca->max_age( 0 );         # now
429
430   max_keys ( [ size ] )
431       Returns the size limit set on the cache or "unlimited" if not defined
432       internally. When size is given, it adjusts the cache accordingly to the
433       new size by pruning the head of the list if necessary.
434
435        $size = $ca->max_keys;
436
437        $ca->max_keys( undef );    # unlimited
438        $ca->max_keys( "4 KiB" );  # 4*1024
439        $ca->max_keys( "1 MiB" );  # 1*1024*1024
440        $ca->max_keys( 500 );
441
442   mdel ( key [, key, ... ] )
443       Deletes one or more keys in the cache and returns the number of keys
444       deleted.  A given key which does not exist in the cache is not counted.
445
446        $cnt = $ca->mdel( "key1", "key2" );
447
448   mexists ( key [, key, ... ] )
449       Returns a true value if all given keys exists in the cache. A false
450       value is returned otherwise.
451
452        if ( $ca->mexists( "key1", "key2" ) ) { ... }
453
454       Reorder: No
455
456   mget ( key [, key, ... ] )
457       Gets the values of all given keys. It returns "undef" for keys which do
458       not exists in the cache.
459
460        ( $val1, $val2 ) = $ca->mget( "key1", "key2" );
461
462       Reorder: Yes
463
464   mset ( key, value [, key, value, ... ] )
465       Sets multiple key-value pairs in a cache and returns the number of keys
466       stored in the cache.
467
468        $len = $ca->mset( "key1" => "val1", "key2" => "val2" );
469
470       Reorder: Yes
471
472   merge
473       "merge" is an alias for "mset".
474
475   pairs ( key [, key, ... ] )
476       When "max_age" is set, prunes any expired keys at the head of the list.
477
478       Returns key-value pairs in the cache by most frequently accessed when
479       no arguments are given. Otherwise, returns key-value pairs for the
480       given keys in the same order. Keys that do not exist will have the
481       "undef" value.  In scalar context, returns the size of the cache.
482
483        @pairs = $ca->pairs;
484        @pairs = $ca->pairs( "key1", "key2" );
485        $len   = $ca->pairs;
486
487       Reorder: No
488
489   pairs ( "query string" )
490       When "max_age" is set, prunes any expired keys at the head of the list.
491
492       Returns only key-value pairs that match the given criteria. It returns
493       an empty list if the search found nothing. The syntax for the "query
494       string" is described above. In scalar context, returns the size of the
495       resulting list.
496
497        @pairs = $ca->pairs( "val eq some_value" );
498        @pairs = $ca->pairs( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
499        @pairs = $ca->pairs( "val eq sun :OR val eq moon :OR val eq foo" );
500        $len   = $ca->pairs( "key =~ /$pattern/" );
501
502       Reorder: No
503
504   peek ( key )
505       Same as "get" without changing the order of the keys. Gets the value of
506       a cache key or "undef" if the key does not exists.
507
508        $val = $ca->get( "some_key" );
509        $val = $ca->{ "some_key" };
510
511       Reorder: No
512
513   pipeline ( [ func1, @args ], [ func2, @args ], ... )
514       Combines multiple commands for the object to be processed serially. For
515       shared objects, the call is made atomically due to single IPC to the
516       shared-manager process. The "pipeline" method is fully
517       "wantarray"-aware and receives a list of commands and their arguments.
518       In scalar or list context, it returns data from the last command in the
519       pipeline.
520
521        @vals = $ca->pipeline(                     # ( "a_a", "b_b", "c_c" )
522           [ "set", foo => "a_a" ],
523           [ "set", bar => "b_b" ],
524           [ "set", baz => "c_c" ],
525           [ "mget", qw/ foo bar baz / ]
526        );
527
528        $len = $ca->pipeline(                      # 3, same as $ca->len
529           [ "set", foo => "i_i" ],
530           [ "set", bar => "j_j" ],
531           [ "set", baz => "k_k" ],
532           [ "len" ]
533        );
534
535        $ca->pipeline(
536           [ "set", foo => "m_m" ],
537           [ "set", bar => "n_n" ],
538           [ "set", baz => "o_o" ]
539        );
540
541       Reorder: Very likely, see API on given method
542
543   pipeline_ex ( [ func1, @args ], [ func2, @args ], ... )
544       Same as "pipeline", but returns data for every command in the pipeline.
545
546        @vals = $ca->pipeline_ex(                  # ( "a_a", "b_b", "c_c" )
547           [ "set", foo => "a_a" ],
548           [ "set", bar => "b_b" ],
549           [ "set", baz => "c_c" ]
550        );
551
552       Reorder: Very likely, see API on given command
553
554   purge ( )
555       Remove all tombstones and expired data from the cache.
556
557        $ca->purge;
558
559   remove
560       "remove" is an alias for "delete".
561
562   set ( key, value [, expires_in ] )
563       Sets the value of the given cache key and returns its new value.
564       Optionally in v1.839 and later releases, give the number of seconds
565       before the key is expired.
566
567        $val = $ca->set( "key", "value" );
568        $val = $ca->{ "key" } = "value";
569
570        $val = $ca->set( "key", "value", 3600  );  # or "60 minutes"
571        $val = $ca->set( "key", "value", undef );  # or "never"
572        $val = $ca->set( "key", "value", 0     );  # or "now"
573
574        $val = $ca->set( "key", "value", "2 seconds" );  # or "2s"
575        $val = $ca->set( "key", "value", "2 minutes" );  # or "2m"
576        $val = $ca->set( "key", "value", "2 hours"   );  # or "2h"
577        $val = $ca->set( "key", "value", "2 days"    );  # or "2d"
578        $val = $ca->set( "key", "value", "2 weeks"   );  # or "2w"
579
580       Reorder: Yes
581
582   setnx ( key, value [, expires_in ] )
583       Sets the value of a hash key, only if the key does not exist. Returns a
584       1 for new key or 0 if the key already exists and no operation was
585       performed.  Optionally, give the number of seconds before the key is
586       expired.
587
588        $ret = $ca->setnx( "key", "value" );
589
590       Current API available since 1.872.
591
592       Reorder: Yes
593
594   values ( key [, key, ... ] )
595       When "max_age" is set, prunes any expired keys at the head of the list.
596
597       Returns all values in the cache by most frequently accessed when no
598       arguments are given. Otherwise, returns values for the given keys in
599       the same order.  Keys that do not exist will have the "undef" value. In
600       scalar context, returns the size of the cache.
601
602        @vals = $ca->values;
603        @vals = $ca->values( "key1", "key2" );
604        $len  = $ca->values;
605
606       Reorder: No
607
608   values ( "query string" )
609       When "max_age" is set, prunes any expired keys at the head of the list.
610
611       Returns only values that match the given criteria. It returns an empty
612       list if the search found nothing. The syntax for the "query string" is
613       described above. In scalar context, returns the size of the resulting
614       list.
615
616        @vals = $ca->values( "val eq some_value" );
617        @vals = $ca->values( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
618        @vals = $ca->values( "val eq sun :OR val eq moon :OR val eq foo" );
619        $len  = $ca->values( "key =~ /$pattern/" );
620
621       Reorder: No
622
623   vals
624       "vals" is an alias for "values".
625

SUGAR METHODS

627       This module is equipped with sugar methods to not have to call "set"
628       and "get" explicitly. In shared context, the benefit is atomicity and
629       reduction in inter-process communication.
630
631       The API resembles a subset of the Redis primitives
632       <https://redis.io/commands#strings> with key representing the cache
633       key.
634
635       Optionally in v1.839 and later releases, give the number of seconds
636       before the key is expired, similarly to "set".
637
638   append ( key, string [, expires_in ] )
639       Appends a value to a key and returns its new length.
640
641        $len = $ca->append( $key, "foo" );
642
643       Reorder: Yes
644
645   decr ( key [, expires_in ] )
646       Decrements the value of a key by one and returns its new value.
647
648        $num = $ca->decr( $key );
649
650       Reorder: Yes
651
652   decrby ( key, number [, expires_in ] )
653       Decrements the value of a key by the given number and returns its new
654       value.
655
656        $num = $ca->decrby( $key, 2 );
657
658       Reorder: Yes
659
660   getdecr ( key [, expires_in ] )
661       Decrements the value of a key by one and returns its old value.
662
663        $old = $ca->getdecr( $key );
664
665       Reorder: Yes
666
667   getincr ( key [, expires_in ] )
668       Increments the value of a key by one and returns its old value.
669
670        $old = $ca->getincr( $key );
671
672       Reorder: Yes
673
674   getset ( key, value [, expires_in ] )
675       Sets the value of a key and returns its old value.
676
677        $old = $ca->getset( $key, "baz" );
678
679       Reorder: Yes
680
681   incr ( key [, expires_in ] )
682       Increments the value of a key by one and returns its new value.
683
684        $num = $ca->incr( $key );
685
686       Reorder: Yes
687
688   incrby ( key, number [, expires_in ] )
689       Increments the value of a key by the given number and returns its new
690       value.
691
692        $num = $ca->incrby( $key, 2 );
693
694       Reorder: Yes
695

INTERNAL METHODS

697       Internal "Sereal" freeze-thaw hooks for exporting shared-cache object.
698
699       FREEZE
700       THAW
701
702       Internal "Storable" freeze-thaw hooks for exporting shared-cache
703       object.
704
705       STORABLE_freeze
706       STORABLE_thaw
707

PERFORMANCE TESTING

709       One might want to benchmark this module. If yes, remember to use the
710       non-shared construction for running on a single core.
711
712        use MCE::Shared::Cache;
713
714        my $cache = MCE::Shared::Cache->new( max_keys => 500_000 );
715
716       Otherwise, the following is a parallel version for a benchmark script
717       <https://blog.celogeek.com/201401/426/perl-benchmark-cache-with-
718       expires-and-max-size> found on the web. The serial version was created
719       by Celogeek for benchmarking various caching modules.
720
721       The MCE "progress" option makes it possible to track progress while
722       running parallel. This script involves IPC to and from the shared-
723       manager process, where the data resides. In regards to IPC, fetches may
724       take longer on Linux versus Darwin or FreeBSD.
725
726        #!/usr/bin/perl
727
728        use strict;
729        use warnings;
730        use feature qw( say );
731
732        use Digest::MD5 qw( md5_base64 );
733        use Time::HiRes qw( time );
734        use MCE 1.814;
735        use MCE::Shared;
736
737        $| = 1; srand(0);
738
739        # construct shared variables
740        # serialization is handled automatically
741
742        my $c     = MCE::Shared->cache( max_keys => 500_000 );
743        my $found = MCE::Shared->scalar( 0 );
744
745        # construct and spawn MCE workers
746        # workers increment a local variable $f
747
748        my $mce = MCE->new(
749            chunk_size  => 4000,
750            max_workers => 4,
751            user_func   => sub {
752                my ($mce, $chunk_ref, $chunk_id) = @_;
753                if ( $mce->user_args()->[0] eq 'setter' ) {
754                    for ( @{ $chunk_ref } ) { $c->set($_, {md5 => $_})  }
755                }
756                else {
757                    my $f = 0;
758                    for ( @{ $chunk_ref } ) { $f++ if ref $c->get($_) eq 'HASH' }
759                    $found->incrby($f);
760                }
761            }
762        )->spawn();
763
764        say "Mapping";
765        my @todo = map { md5_base64($_) } ( 1 .. 600_000 );
766
767        say "Starting";
768        my ( $read, $write );
769
770        {
771            my $s = time;
772            $mce->process({
773                progress  => sub { print "Write: $_[0]\r" },
774                user_args => [ 'setter' ],
775            }, \@todo);
776            $write = time - $s;
777        }
778
779        say "Write: ", sprintf("%0.3f", scalar(@todo) / $write);
780
781        {
782            my $s = time;
783            $found->set(0);
784            $mce->process({
785                progress  => sub { print "Read $_[0]\r" },
786                user_args => [ 'getter' ],
787            }, \@todo);
788            $read = time - $s;
789        }
790
791        $mce->shutdown();
792
793        say "Read : ", sprintf("%0.3f", scalar(@todo) / $read);
794        say "Found: ", $found->get();
795
796       The "progress" option is further described on Metacpan. Several
797       examples are provided, accommodating all input data-types in MCE.
798
799       Progress Demonstrations <https://metacpan.org/pod/MCE::Core#PROGRESS-
800       DEMONSTRATIONS>
801

SEE ALSO

803       •  CHI
804
805       •  Cache::FastMmap
806
807       •  Cache::LRU
808
809       •  Cache::Ref
810
811       •  Tie::Cache::LRU
812
813       •  Tie::Cache::LRU::Expires
814

INDEX

816       MCE, MCE::Hobo, MCE::Shared
817

AUTHOR

819       Mario E. Roy, <marioeroy AT gmail DOT com>
820
821
822
823perl v5.36.0                      2023-01-20             MCE::Shared::Cache(3)
Impressum