1MCE::Shared::Hash(3)  User Contributed Perl Documentation MCE::Shared::Hash(3)
2
3
4

NAME

6       MCE::Shared::Hash - Hash helper class
7

VERSION

9       This document describes MCE::Shared::Hash version 1.839
10

DESCRIPTION

12       A hash helper class for use as a standalone or managed by MCE::Shared.
13

SYNOPSIS

15        # non-shared or local construction for use by a single process
16
17        use MCE::Shared::Hash;
18
19        my $ha = MCE::Shared::Hash->new( @pairs );
20
21        # construction for sharing with other threads and processes
22
23        use MCE::Shared;
24
25        my $ha = MCE::Shared->hash( @pairs );
26
27        # hash-like dereferencing
28
29        my $val = $ha->{$key};
30        $ha->{$key} = $val;
31
32        %{$ha} = ();
33
34        # OO interface
35
36        if ( !defined ( $val = $ha->get("some_key") ) ) {
37           $val = $ha->set( some_key => "some_value" );
38        }
39
40        $val   = $ha->set( $key, $val );
41        $val   = $ha->get( $key );
42        $val   = $ha->delete( $key );              # del is an alias for delete
43        $bool  = $ha->exists( $key );
44        void   = $ha->clear();
45        $len   = $ha->len();                       # scalar keys %{ $ha }
46        $len   = $ha->len( $key );                 # length $ha->{ $key }
47
48        $ha2   = $ha->clone( @keys );              # @keys is optional
49        $ha3   = $ha->flush( @keys );
50        $iter  = $ha->iterator( @keys );           # ($key, $val) = $iter->()
51        @keys  = $ha->keys( @keys );
52        %pairs = $ha->pairs( @keys );
53        @vals  = $ha->values( @keys );             # vals is an alias for values
54
55        $len   = $ha->assign( $key/$val pairs );   # equivalent to ->clear, ->mset
56        $cnt   = $ha->mdel( @keys );
57        @vals  = $ha->mget( @keys );
58        $bool  = $ha->mexists( @keys );            # true if all keys exists
59        $len   = $ha->mset( $key/$val pairs );     # merge is an alias for mset
60
61        # included, sugar methods without having to call set/get explicitly
62
63        $len   = $ha->append( $key, $string );     #   $val .= $string
64        $val   = $ha->decr( $key );                # --$val
65        $val   = $ha->decrby( $key, $number );     #   $val -= $number
66        $val   = $ha->getdecr( $key );             #   $val--
67        $val   = $ha->getincr( $key );             #   $val++
68        $val   = $ha->incr( $key );                # ++$val
69        $val   = $ha->incrby( $key, $number );     #   $val += $number
70        $old   = $ha->getset( $key, $new );        #   $o = $v, $v = $n, $o
71
72        # pipeline, provides atomicity for shared objects, MCE::Shared v1.09+
73
74        @vals  = $ha->pipeline(                    # ( "a_a", "b_b", "c_c" )
75           [ "set", foo => "a_a" ],
76           [ "set", bar => "b_b" ],
77           [ "set", baz => "c_c" ],
78           [ "mget", qw/ foo bar baz / ]
79        );
80
81       For normal hash behavior, the TIE interface is supported.
82
83        # non-shared or local construction for use by a single process
84
85        use MCE::Shared::Hash;
86
87        tie my %ha, "MCE::Shared::Hash";
88
89        # construction for sharing with other threads and processes
90
91        use MCE::Shared;
92
93        tie my %ha, "MCE::Shared";
94
95        # usage
96
97        my $val;
98
99        if ( !defined ( $val = $ha{some_key} ) ) {
100           $val = $ha{some_key} = "some_value";
101        }
102
103        $ha{some_key} = 0;
104
105        tied(%ha)->incrby("some_key", 20);
106        tied(%ha)->incrby(some_key => 20);
107

SYNTAX for QUERY STRING

109       Several methods take a query string for an argument. The format of the
110       string is described below. In the context of sharing, the query
111       mechanism is beneficial for the shared-manager process. It is able to
112       perform the query where the data resides versus the client-process grep
113       locally involving lots of IPC.
114
115        o Basic demonstration
116
117          @keys = $ha->keys( "query string given here" );
118          @keys = $ha->keys( "val =~ /pattern/" );
119
120        o Supported operators: =~ !~ eq ne lt le gt ge == != < <= > >=
121        o Multiple expressions delimited by :AND or :OR, mixed case allowed
122
123          "key eq 'some key' :or (val > 5 :and val < 9)"
124          "key eq some key :or (val > 5 :and val < 9)"
125          "key =~ /pattern/i :And val =~ /pattern/i"
126          "val eq foo baz :OR key !~ /pattern/i"
127
128          * key matches on keys in the hash
129          * likewise, val matches on values
130
131        o Quoting is optional inside the string
132
133          "key =~ /pattern/i :AND val eq 'foo bar'"   # val eq "foo bar"
134          "key =~ /pattern/i :AND val eq foo bar"     # val eq "foo bar"
135
136       Examples.
137
138        # search capability key/val: =~ !~ eq ne lt le gt ge == != < <= > >=
139        # key/val means to match against actual key/val respectively
140
141        @keys  = $ha->keys( "key eq 'some key' :or (val > 5 :and val < 9)" );
142        @keys  = $ha->keys( "key eq some key :or (val > 5 :and val < 9)" );
143
144        @keys  = $ha->keys( "key =~ /$pattern/i" );
145        @keys  = $ha->keys( "key !~ /$pattern/i" );
146        @keys  = $ha->keys( "val =~ /$pattern/i" );
147        @keys  = $ha->keys( "val !~ /$pattern/i" );
148
149        %pairs = $ha->pairs( "key == $number" );
150        %pairs = $ha->pairs( "key != $number :and val > 100" );
151        %pairs = $ha->pairs( "key <  $number :or key > $number" );
152        %pairs = $ha->pairs( "val <= $number" );
153        %pairs = $ha->pairs( "val >  $number" );
154        %pairs = $ha->pairs( "val >= $number" );
155
156        @vals  = $ha->vals( "key eq $string" );
157        @vals  = $ha->vals( "key ne $string with space" );
158        @vals  = $ha->vals( "key lt $string :or val =~ /$pat1|$pat2/" );
159        @vals  = $ha->vals( "val le $string :and val eq 'foo bar'" );
160        @vals  = $ha->vals( "val le $string :and val eq foo bar" );
161        @vals  = $ha->vals( "val gt $string" );
162        @vals  = $ha->vals( "val ge $string" );
163

API DOCUMENTATION

165       This module may involve TIE when accessing the object via hash-like
166       behavior.  Only shared instances are impacted if doing so. Although
167       likely fast enough for many use cases, the OO interface is recommended
168       for best performance.
169
170       new ( key, value [, key, value, ... ] )
171          Constructs a new object, with an optional list of key-value pairs.
172
173           # non-shared or local construction for use by a single process
174
175           use MCE::Shared::Hash;
176
177           $ha = MCE::Shared::Hash->new( @pairs );
178           $ha = MCE::Shared::Hash->new( );
179
180           # construction for sharing with other threads and processes
181
182           use MCE::Shared;
183
184           $ha = MCE::Shared->hash( @pairs );
185           $ha = MCE::Shared->hash( );
186
187       assign ( key, value [, key, value, ... ] )
188          Clears the hash, then sets multiple key-value pairs and returns the
189          number of keys stored in the hash. This is equivalent to "clear",
190          "mset".
191
192           $len = $ha->assign( "key1" => "val1", "key2" => "val2" );  # 2
193           $len = %{$ha} = ( "key1" => "val1", "key2" => "val2" );    # 4
194
195          API available since 1.007.
196
197       clear
198          Removes all key-value pairs from the hash.
199
200           $ha->clear;
201           %{$ha} = ();
202
203       clone ( key [, key, ... ] )
204          Creates a shallow copy, a "MCE::Shared::Hash" object. It returns an
205          exact copy if no arguments are given. Otherwise, the object includes
206          only the given keys. Keys that do not exist in the hash will have
207          the "undef" value.
208
209           $ha2 = $ha->clone( "key1", "key2" );
210           $ha2 = $ha->clone;
211
212       delete ( key )
213          Deletes and returns the value by given key or "undef" if the key
214          does not exists in the hash.
215
216           $val = $ha->delete( "some_key" );
217           $val = delete $ha->{ "some_key" };
218
219       del
220          "del" is an alias for "delete".
221
222       exists ( key )
223          Determines if a key exists in the hash.
224
225           if ( $ha->exists( "some_key" ) ) { ... }
226           if ( exists $ha->{ "some_key" } ) { ... }
227
228       flush ( key [, key, ... ] )
229          Same as "clone". Though, clears all existing items before returning.
230
231       get ( key )
232          Gets the value of a hash key or "undef" if the key does not exists.
233
234           $val = $ha->get( "some_key" );
235           $val = $ha->{ "some_key" };
236
237       iterator ( key [, key, ... ] )
238          Returns a code reference for iterating a list of key-value pairs
239          stored in the hash when no arguments are given. Otherwise, returns a
240          code reference for iterating the given keys in the same order. Keys
241          that do not exist will have the "undef" value.
242
243          The list of keys to return is set when the closure is constructed.
244          Later keys added to the hash are not included. Subsequently, the
245          "undef" value is returned for deleted keys.
246
247           $iter = $ha->iterator;
248           $iter = $ha->iterator( "key1", "key2" );
249
250           while ( my ( $key, $val ) = $iter->() ) {
251              ...
252           }
253
254       iterator ( "query string" )
255          Returns a code reference for iterating a list of key-value pairs
256          that match the given criteria. It returns an empty list if the
257          search found nothing.  The syntax for the "query string" is
258          described above.
259
260           $iter = $ha->iterator( "val eq some_value" );
261           $iter = $ha->iterator( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
262           $iter = $ha->iterator( "val eq sun :OR val eq moon :OR val eq foo" );
263           $iter = $ha->iterator( "key =~ /$pattern/" );
264
265           while ( my ( $key, $val ) = $iter->() ) {
266              ...
267           }
268
269       keys ( key [, key, ... ] )
270          Returns all keys in the hash when no arguments are given. Otherwise,
271          returns the given keys in the same order. Keys that do not exist
272          will have the "undef" value. In scalar context, returns the size of
273          the hash.
274
275           @keys = $ha->keys( "key1", "key2" );
276
277           @keys = $ha->keys;     # faster
278           @keys = keys %{$ha};   # involves TIE overhead
279
280           $len  = $ha->keys;     # ditto
281           $len  = keys %{$ha};
282
283       keys ( "query string" )
284          Returns only keys that match the given criteria. It returns an empty
285          list if the search found nothing. The syntax for the "query string"
286          is described above. In scalar context, returns the size of the
287          resulting list.
288
289           @keys = $ha->keys( "val eq some_value" );
290           @keys = $ha->keys( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
291           @keys = $ha->keys( "val eq sun :OR val eq moon :OR val eq foo" );
292           $len  = $ha->keys( "key =~ /$pattern/" );
293
294       len ( key )
295          Returns the size of the hash when no arguments are given. For the
296          given key, returns the length of the value stored at key or the
297          "undef" value if the key does not exists.
298
299           $size = $ha->len;
300           $len  = $ha->len( "key1" );
301           $len  = length $ha->{ "key1" };
302
303       mdel ( key [, key, ... ] )
304          Deletes one or more keys in the hash and returns the number of keys
305          deleted.  A given key which does not exist in the hash is not
306          counted.
307
308           $cnt = $ha->mdel( "key1", "key2" );
309
310       mexists ( key [, key, ... ] )
311          Returns a true value if all given keys exists in the hash. A false
312          value is returned otherwise.
313
314           if ( $ha->mexists( "key1", "key2" ) ) { ... }
315
316       mget ( key [, key, ... ] )
317          Gets the values of all given keys. It returns "undef" for keys which
318          do not exists in the hash.
319
320           ( $val1, $val2 ) = $ha->mget( "key1", "key2" );
321
322       mset ( key, value [, key, value, ... ] )
323          Sets multiple key-value pairs in a hash and returns the number of
324          keys stored in the hash.
325
326           $len = $ha->mset( "key1" => "val1", "key2" => "val2" );
327
328       merge
329          "merge" is an alias for "mset".
330
331       pairs ( key [, key, ... ] )
332          Returns key-value pairs in the hash when no arguments are given.
333          Otherwise, returns key-value pairs for the given keys in the same
334          order. Keys that do not exist will have the "undef" value. In scalar
335          context, returns the size of the hash.
336
337           @pairs = $ha->pairs( "key1", "key2" );
338
339           @pairs = $ha->pairs;
340           $len   = $ha->pairs;
341
342       pairs ( "query string" )
343          Returns only key-value pairs that match the given criteria. It
344          returns an empty list if the search found nothing. The syntax for
345          the "query string" is described above. In scalar context, returns
346          the size of the resulting list.
347
348           @pairs = $ha->pairs( "val eq some_value" );
349           @pairs = $ha->pairs( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
350           @pairs = $ha->pairs( "val eq sun :OR val eq moon :OR val eq foo" );
351           $len   = $ha->pairs( "key =~ /$pattern/" );
352
353       pipeline ( [ func1, @args ], [ func2, @args ], ... )
354          Combines multiple commands for the object to be processed serially.
355          For shared objects, the call is made atomically due to single IPC to
356          the shared-manager process. The "pipeline" method is fully
357          "wantarray"-aware and receives a list of commands and their
358          arguments. In scalar or list context, it returns data from the last
359          command in the pipeline.
360
361           @vals = $ha->pipeline(                     # ( "a_a", "b_b", "c_c" )
362              [ "set", foo => "a_a" ],
363              [ "set", bar => "b_b" ],
364              [ "set", baz => "c_c" ],
365              [ "mget", qw/ foo bar baz / ]
366           );
367
368           $len = $ha->pipeline(                      # 3, same as $ha->len
369              [ "set", foo => "i_i" ],
370              [ "set", bar => "j_j" ],
371              [ "set", baz => "k_k" ],
372              [ "len" ]
373           );
374
375           $ha->pipeline(
376              [ "set", foo => "m_m" ],
377              [ "set", bar => "n_n" ],
378              [ "set", baz => "o_o" ]
379           );
380
381          Current API available since 1.809.
382
383       pipeline_ex ( [ func1, @args ], [ func2, @args ], ... )
384          Same as "pipeline", but returns data for every command in the
385          pipeline.
386
387           @vals = $ha->pipeline_ex(                  # ( "a_a", "b_b", "c_c" )
388              [ "set", foo => "a_a" ],
389              [ "set", bar => "b_b" ],
390              [ "set", baz => "c_c" ]
391           );
392
393          Current API available since 1.809.
394
395       set ( key, value )
396          Sets the value of the given hash key and returns its new value.
397
398           $val = $ha->set( "key", "value" );
399           $val = $ha->{ "key" } = "value";
400
401       values ( key [, key, ... ] )
402          Returns all values in the hash when no arguments are given.
403          Otherwise, returns values for the given keys in the same order. Keys
404          that do not exist will have the "undef" value. In scalar context,
405          returns the size of the hash.
406
407           @vals = $ha->values( "key1", "key2" );
408
409           @vals = $ha->values;     # faster
410           @vals = values %{$ha};   # involves TIE overhead
411
412           $len  = $ha->values;     # ditto
413           $len  = values %{$ha};
414
415       values ( "query string" )
416          Returns only values that match the given criteria. It returns an
417          empty list if the search found nothing. The syntax for the "query
418          string" is described above. In scalar context, returns the size of
419          the resulting list.
420
421           @vals = $ha->values( "val eq some_value" );
422           @vals = $ha->values( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
423           @vals = $ha->values( "val eq sun :OR val eq moon :OR val eq foo" );
424           $len  = $ha->values( "key =~ /$pattern/" );
425
426       vals
427          "vals" is an alias for "values".
428

SUGAR METHODS

430       This module is equipped with sugar methods to not have to call "set"
431       and "get" explicitly. In shared context, the benefit is atomicity and
432       reduction in inter-process communication.
433
434       The API resembles a subset of the Redis primitives
435       <http://redis.io/commands#strings> with key representing the hash key.
436
437       append ( key, string )
438          Appends a value to a key and returns its new length.
439
440           $len = $ha->append( $key, "foo" );
441
442       decr ( key )
443          Decrements the value of a key by one and returns its new value.
444
445           $num = $ha->decr( $key );
446
447       decrby ( key, number )
448          Decrements the value of a key by the given number and returns its
449          new value.
450
451           $num = $ha->decrby( $key, 2 );
452
453       getdecr ( key )
454          Decrements the value of a key by one and returns its old value.
455
456           $old = $ha->getdecr( $key );
457
458       getincr ( key )
459          Increments the value of a key by one and returns its old value.
460
461           $old = $ha->getincr( $key );
462
463       getset ( key, value )
464          Sets the value of a key and returns its old value.
465
466           $old = $ha->getset( $key, "baz" );
467
468       incr ( key )
469          Increments the value of a key by one and returns its new value.
470
471           $num = $ha->incr( $key );
472
473       incrby ( key, number )
474          Increments the value of a key by the given number and returns its
475          new value.
476
477           $num = $ha->incrby( $key, 2 );
478

CREDITS

480       The implementation is inspired by Tie::StdHash.
481

INDEX

483       MCE, MCE::Hobo, MCE::Shared
484

AUTHOR

486       Mario E. Roy, <marioeroy AT gmail DOT com>
487
488
489
490perl v5.28.0                      2018-08-25              MCE::Shared::Hash(3)
Impressum