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.876
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       <http://redis.io/commands#strings> with key representing the cache key.
633
634       Optionally in v1.839 and later releases, give the number of seconds
635       before the key is expired, similarly to "set".
636
637   append ( key, string [, expires_in ] )
638       Appends a value to a key and returns its new length.
639
640        $len = $ca->append( $key, "foo" );
641
642       Reorder: Yes
643
644   decr ( key [, expires_in ] )
645       Decrements the value of a key by one and returns its new value.
646
647        $num = $ca->decr( $key );
648
649       Reorder: Yes
650
651   decrby ( key, number [, expires_in ] )
652       Decrements the value of a key by the given number and returns its new
653       value.
654
655        $num = $ca->decrby( $key, 2 );
656
657       Reorder: Yes
658
659   getdecr ( key [, expires_in ] )
660       Decrements the value of a key by one and returns its old value.
661
662        $old = $ca->getdecr( $key );
663
664       Reorder: Yes
665
666   getincr ( key [, expires_in ] )
667       Increments the value of a key by one and returns its old value.
668
669        $old = $ca->getincr( $key );
670
671       Reorder: Yes
672
673   getset ( key, value [, expires_in ] )
674       Sets the value of a key and returns its old value.
675
676        $old = $ca->getset( $key, "baz" );
677
678       Reorder: Yes
679
680   incr ( key [, expires_in ] )
681       Increments the value of a key by one and returns its new value.
682
683        $num = $ca->incr( $key );
684
685       Reorder: Yes
686
687   incrby ( key, number [, expires_in ] )
688       Increments the value of a key by the given number and returns its new
689       value.
690
691        $num = $ca->incrby( $key, 2 );
692
693       Reorder: Yes
694

INTERNAL METHODS

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

PERFORMANCE TESTING

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

SEE ALSO

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

INDEX

815       MCE, MCE::Hobo, MCE::Shared
816

AUTHOR

818       Mario E. Roy, <marioeroy AT gmail DOT com>
819
820
821
822perl v5.34.0                      2022-02-20             MCE::Shared::Cache(3)
Impressum