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.839
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        $val   = $ca->get( $key );
90        $val   = $ca->delete( $key );              # del is an alias for delete
91        $bool  = $ca->exists( $key );
92        void   = $ca->clear();
93        $len   = $ca->len();                       # scalar keys %{ $ca }
94        $len   = $ca->len( $key );                 # length $ca->{ $key }
95
96        $iter  = $ca->iterator( @keys );           # ($key, $val) = $iter->()
97        @keys  = $ca->keys( @keys );               # @keys is optional
98        %pairs = $ca->pairs( @keys );
99        @vals  = $ca->values( @keys );             # vals is an alias for values
100
101        $len   = $ca->assign( $key/$val pairs );   # equivalent to ->clear, ->mset
102        $cnt   = $ca->mdel( @keys );
103        @vals  = $ca->mget( @keys );
104        $bool  = $ca->mexists( @keys );            # true if all keys exists
105        $len   = $ca->mset( $key/$val pairs );     # merge is an alias for mset
106
107        # included, sugar methods without having to call set/get explicitly
108
109        $len   = $ca->append( $key, $string );     #   $val .= $string
110        $val   = $ca->decr( $key );                # --$val
111        $val   = $ca->decrby( $key, $number );     #   $val -= $number
112        $val   = $ca->getdecr( $key );             #   $val--
113        $val   = $ca->getincr( $key );             #   $val++
114        $val   = $ca->incr( $key );                # ++$val
115        $val   = $ca->incrby( $key, $number );     #   $val += $number
116        $old   = $ca->getset( $key, $new );        #   $o = $v, $v = $n, $o
117
118        # pipeline, provides atomicity for shared objects, MCE::Shared v1.09+
119
120        @vals  = $ca->pipeline(                    # ( "a_a", "b_b", "c_c" )
121           [ "set", foo => "a_a" ],
122           [ "set", bar => "b_b" ],
123           [ "set", baz => "c_c" ],
124           [ "mget", qw/ foo bar baz / ]
125        );
126
127       For normal hash behavior, the TIE interface is supported.
128
129        # non-shared or local construction for use by a single process
130
131        use MCE::Shared::Cache;
132
133        tie my %ca, "MCE::Shared::Cache", max_keys => undef, max_age => undef;
134        tie my %ca, "MCE::Shared::Cache", max_keys => 500, max_age => "1 hour";
135        tie my %ca, "MCE::Shared::Cache", { max_keys => 500 }, @pairs;
136
137        # construction for sharing with other threads and processes
138        # one option is needed minimally to know to use MCE::Shared::Cache
139
140        use MCE::Shared;
141
142        tie my %ca, "MCE::Shared", max_keys => undef, max_age => undef;
143        tie my %ca, "MCE::Shared", max_keys => 500, max_age => "1 hour";
144        tie my %ca, "MCE::Shared", { max_keys => 500 }, @pairs;
145
146        # usage
147
148        my $val;
149
150        if ( !defined ( $val = $ca{some_key} ) ) {
151           $val = $ca{some_key} = "some_value";
152        }
153
154        $ca{some_key} = 0;
155
156        tied(%ca)->incrby("some_key", 20);
157        tied(%ca)->incrby(some_key => 20);
158

SYNTAX for QUERY STRING

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

API DOCUMENTATION

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

PERFORMANCE TESTING

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

SEE ALSO

790       ·  CHI
791
792       ·  Cache::FastMmap
793
794       ·  Cache::LRU
795
796       ·  Cache::Ref
797
798       ·  Tie::Cache::LRU
799
800       ·  Tie::Cache::LRU::Expires
801

INDEX

803       MCE, MCE::Hobo, MCE::Shared
804

AUTHOR

806       Mario E. Roy, <marioeroy AT gmail DOT com>
807
808
809
810perl v5.28.0                      2018-08-25             MCE::Shared::Cache(3)
Impressum