1MCE::Shared::Hash(3) User Contributed Perl Documentation MCE::Shared::Hash(3)
2
6 MCE::Shared::Hash - Hash helper class
7
9 This document describes MCE::Shared::Hash version 1.862
10
12 A hash helper class for use as a standalone or managed by MCE::Shared.
13
15 # non-shared or local construction for use by a single process
16 use MCE::Shared::Hash;
18 my $ha = MCE::Shared::Hash->new( @pairs );
20 # construction for sharing with other threads and processes
22 use MCE::Shared;
24 my $ha = MCE::Shared->hash( @pairs );
26 # hash-like dereferencing
28 my $val = $ha->{$key};
30 $ha->{$key} = $val;
31 %{$ha} = ();
33 # OO interface
35 if ( !defined ( $val = $ha->get("some_key") ) ) {
37 $val = $ha->set( some_key => "some_value" );
38 }
39 $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 $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 $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 # included, sugar methods without having to call set/get explicitly
62 $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 # pipeline, provides atomicity for shared objects, MCE::Shared v1.09+
73 @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 For normal hash behavior, the TIE interface is supported.
82 # non-shared or local construction for use by a single process
84 use MCE::Shared::Hash;
86 tie my %ha, "MCE::Shared::Hash";
88 # construction for sharing with other threads and processes
90 use MCE::Shared;
92 tie my %ha, "MCE::Shared";
94 # usage
96 my $val;
98 if ( !defined ( $val = $ha{some_key} ) ) {
100 $val = $ha{some_key} = "some_value";
101 }
102 $ha{some_key} = 0;
104 tied(%ha)->incrby("some_key", 20);
106 tied(%ha)->incrby(some_key => 20);
107
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 o Basic demonstration
116 @keys = $ha->keys( "query string given here" );
118 @keys = $ha->keys( "val =~ /pattern/" );
119 o Supported operators: =~ !~ eq ne lt le gt ge == != < <= > >=
121 o Multiple expressions delimited by :AND or :OR, mixed case allowed
122 "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 * key matches on keys in the hash
129 * likewise, val matches on values
130 o Quoting is optional inside the string
132 "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 Examples.
137 # search capability key/val: =~ !~ eq ne lt le gt ge == != < <= > >=
139 # key/val means to match against actual key/val respectively
140 @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 @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 %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 @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
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 MCE::Shared::Hash->new ( key, value [, key, value, ... ] )
171 MCE::Shared->hash ( key, value [, key, value, ... ] )
172 Constructs a new object, with an optional list of key-value pairs.
173 # non-shared or local construction for use by a single process
175 use MCE::Shared::Hash;
177 $ha = MCE::Shared::Hash->new( @pairs );
179 $ha = MCE::Shared::Hash->new( );
180 # construction for sharing with other threads and processes
182 use MCE::Shared;
184 $ha = MCE::Shared->hash( @pairs );
186 $ha = MCE::Shared->hash( );
187 assign ( key, value [, key, value, ... ] )
189 Clears the hash, then sets multiple key-value pairs and returns the
190 number of keys stored in the hash. This is equivalent to "clear",
191 "mset".
192 $len = $ha->assign( "key1" => "val1", "key2" => "val2" ); # 2
194 $len = %{$ha} = ( "key1" => "val1", "key2" => "val2" ); # 4
195 API available since 1.007.
197 clear
199 Removes all key-value pairs from the hash.
200 $ha->clear;
202 %{$ha} = ();
203 clone ( key [, key, ... ] )
205 Creates a shallow copy, a "MCE::Shared::Hash" object. It returns an
206 exact copy if no arguments are given. Otherwise, the object includes
207 only the given keys. Keys that do not exist in the hash will have the
208 "undef" value.
209 $ha2 = $ha->clone( "key1", "key2" );
211 $ha2 = $ha->clone;
212 delete ( key )
214 Deletes and returns the value by given key or "undef" if the key does
215 not exists in the hash.
216 $val = $ha->delete( "some_key" );
218 $val = delete $ha->{ "some_key" };
219 del
221 "del" is an alias for "delete".
222 exists ( key )
224 Determines if a key exists in the hash.
225 if ( $ha->exists( "some_key" ) ) { ... }
227 if ( exists $ha->{ "some_key" } ) { ... }
228 flush ( key [, key, ... ] )
230 Same as "clone". Though, clears all existing items before returning.
231 get ( key )
233 Gets the value of a hash key or "undef" if the key does not exists.
234 $val = $ha->get( "some_key" );
236 $val = $ha->{ "some_key" };
237 iterator ( key [, key, ... ] )
239 Returns a code reference for iterating a list of key-value pairs stored
240 in the hash when no arguments are given. Otherwise, returns a code
241 reference for iterating the given keys in the same order. Keys that do
242 not exist will have the "undef" value.
243 The list of keys to return is set when the closure is constructed.
245 Later keys added to the hash are not included. Subsequently, the
246 "undef" value is returned for deleted keys.
247 $iter = $ha->iterator;
249 $iter = $ha->iterator( "key1", "key2" );
250 while ( my ( $key, $val ) = $iter->() ) {
252 ...
253 }
254 iterator ( "query string" )
256 Returns a code reference for iterating a list of key-value pairs that
257 match the given criteria. It returns an empty list if the search found
258 nothing. The syntax for the "query string" is described above.
259 $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 while ( my ( $key, $val ) = $iter->() ) {
266 ...
267 }
268 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 will
272 have the "undef" value. In scalar context, returns the size of the
273 hash.
274 @keys = $ha->keys( "key1", "key2" );
276 @keys = $ha->keys; # faster
278 @keys = keys %{$ha}; # involves TIE overhead
279 $len = $ha->keys; # ditto
281 $len = keys %{$ha};
282 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" is
286 described above. In scalar context, returns the size of the resulting
287 list.
288 @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 len ( key )
295 Returns the size of the hash when no arguments are given. For the given
296 key, returns the length of the value stored at key or the "undef" value
297 if the key does not exists.
298 $size = $ha->len;
300 $len = $ha->len( "key1" );
301 $len = length $ha->{ "key1" };
302 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 counted.
306 $cnt = $ha->mdel( "key1", "key2" );
308 mexists ( key [, key, ... ] )
310 Returns a true value if all given keys exists in the hash. A false
311 value is returned otherwise.
312 if ( $ha->mexists( "key1", "key2" ) ) { ... }
314 mget ( key [, key, ... ] )
316 Gets the values of all given keys. It returns "undef" for keys which do
317 not exists in the hash.
318 ( $val1, $val2 ) = $ha->mget( "key1", "key2" );
320 mset ( key, value [, key, value, ... ] )
322 Sets multiple key-value pairs in a hash and returns the number of keys
323 stored in the hash.
324 $len = $ha->mset( "key1" => "val1", "key2" => "val2" );
326 merge
328 "merge" is an alias for "mset".
329 pairs ( key [, key, ... ] )
331 Returns key-value pairs in the hash when no arguments are given.
332 Otherwise, returns key-value pairs for the given keys in the same
333 order. Keys that do not exist will have the "undef" value. In scalar
334 context, returns the size of the hash.
335 @pairs = $ha->pairs( "key1", "key2" );
337 @pairs = $ha->pairs;
339 $len = $ha->pairs;
340 pairs ( "query string" )
342 Returns only key-value pairs that match the given criteria. It returns
343 an empty list if the search found nothing. The syntax for the "query
344 string" is described above. In scalar context, returns the size of the
345 resulting list.
346 @pairs = $ha->pairs( "val eq some_value" );
348 @pairs = $ha->pairs( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
349 @pairs = $ha->pairs( "val eq sun :OR val eq moon :OR val eq foo" );
350 $len = $ha->pairs( "key =~ /$pattern/" );
351 pipeline ( [ func1, @args ], [ func2, @args ], ... )
353 Combines multiple commands for the object to be processed serially. For
354 shared objects, the call is made atomically due to single IPC to the
355 shared-manager process. The "pipeline" method is fully
356 "wantarray"-aware and receives a list of commands and their arguments.
357 In scalar or list context, it returns data from the last command in the
358 pipeline.
359 @vals = $ha->pipeline( # ( "a_a", "b_b", "c_c" )
361 [ "set", foo => "a_a" ],
362 [ "set", bar => "b_b" ],
363 [ "set", baz => "c_c" ],
364 [ "mget", qw/ foo bar baz / ]
365 );
366 $len = $ha->pipeline( # 3, same as $ha->len
368 [ "set", foo => "i_i" ],
369 [ "set", bar => "j_j" ],
370 [ "set", baz => "k_k" ],
371 [ "len" ]
372 );
373 $ha->pipeline(
375 [ "set", foo => "m_m" ],
376 [ "set", bar => "n_n" ],
377 [ "set", baz => "o_o" ]
378 );
379 Current API available since 1.809.
381 pipeline_ex ( [ func1, @args ], [ func2, @args ], ... )
383 Same as "pipeline", but returns data for every command in the pipeline.
384 @vals = $ha->pipeline_ex( # ( "a_a", "b_b", "c_c" )
386 [ "set", foo => "a_a" ],
387 [ "set", bar => "b_b" ],
388 [ "set", baz => "c_c" ]
389 );
390 Current API available since 1.809.
392 set ( key, value )
394 Sets the value of the given hash key and returns its new value.
395 $val = $ha->set( "key", "value" );
397 $val = $ha->{ "key" } = "value";
398 values ( key [, key, ... ] )
400 Returns all values in the hash when no arguments are given. Otherwise,
401 returns values for the given keys in the same order. Keys that do not
402 exist will have the "undef" value. In scalar context, returns the size
403 of the hash.
404 @vals = $ha->values( "key1", "key2" );
406 @vals = $ha->values; # faster
408 @vals = values %{$ha}; # involves TIE overhead
409 $len = $ha->values; # ditto
411 $len = values %{$ha};
412 values ( "query string" )
414 Returns only values that match the given criteria. It returns an empty
415 list if the search found nothing. The syntax for the "query string" is
416 described above. In scalar context, returns the size of the resulting
417 list.
418 @vals = $ha->values( "val eq some_value" );
420 @vals = $ha->values( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
421 @vals = $ha->values( "val eq sun :OR val eq moon :OR val eq foo" );
422 $len = $ha->values( "key =~ /$pattern/" );
423 vals
425 "vals" is an alias for "values".
426
428 This module is equipped with sugar methods to not have to call "set"
429 and "get" explicitly. In shared context, the benefit is atomicity and
430 reduction in inter-process communication.
431 The API resembles a subset of the Redis primitives
433 <http://redis.io/commands#strings> with key representing the hash key.
434 append ( key, string )
436 Appends a value to a key and returns its new length.
437 $len = $ha->append( $key, "foo" );
439 decr ( key )
441 Decrements the value of a key by one and returns its new value.
442 $num = $ha->decr( $key );
444 decrby ( key, number )
446 Decrements the value of a key by the given number and returns its new
447 value.
448 $num = $ha->decrby( $key, 2 );
450 getdecr ( key )
452 Decrements the value of a key by one and returns its old value.
453 $old = $ha->getdecr( $key );
455 getincr ( key )
457 Increments the value of a key by one and returns its old value.
458 $old = $ha->getincr( $key );
460 getset ( key, value )
462 Sets the value of a key and returns its old value.
463 $old = $ha->getset( $key, "baz" );
465 incr ( key )
467 Increments the value of a key by one and returns its new value.
468 $num = $ha->incr( $key );
470 incrby ( key, number )
472 Increments the value of a key by the given number and returns its new
473 value.
474 $num = $ha->incrby( $key, 2 );
476
478 The implementation is inspired by Tie::StdHash.
479
481 MCE, MCE::Hobo, MCE::Shared
482
484 Mario E. Roy, <marioeroy AT gmail DOT com>
485perl v5.30.0 2019-09-19 MCE::Shared::Hash(3)