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.880
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 $ret = $ha->setnx( $key, $val ); # set only if the key exists
42 $val = $ha->get( $key );
43 $val = $ha->delete( $key ); # del is an alias for delete
44 $bool = $ha->exists( $key );
45 void = $ha->clear();
46 $len = $ha->len(); # scalar keys %{ $ha }
47 $len = $ha->len( $key ); # length $ha->{ $key }
48 $ha2 = $ha->clone( @keys ); # @keys is optional
50 $ha3 = $ha->flush( @keys );
51 $iter = $ha->iterator( @keys ); # ($key, $val) = $iter->()
52 @keys = $ha->keys( @keys );
53 %pairs = $ha->pairs( @keys );
54 @vals = $ha->values( @keys ); # vals is an alias for values
55 $len = $ha->assign( $key/$val pairs ); # equivalent to ->clear, ->mset
57 $cnt = $ha->mdel( @keys );
58 @vals = $ha->mget( @keys );
59 $bool = $ha->mexists( @keys ); # true if all keys exists
60 $len = $ha->mset( $key/$val pairs ); # merge is an alias for mset
61 # included, sugar methods without having to call set/get explicitly
63 $len = $ha->append( $key, $string ); # $val .= $string
65 $val = $ha->decr( $key ); # --$val
66 $val = $ha->decrby( $key, $number ); # $val -= $number
67 $val = $ha->getdecr( $key ); # $val--
68 $val = $ha->getincr( $key ); # $val++
69 $val = $ha->incr( $key ); # ++$val
70 $val = $ha->incrby( $key, $number ); # $val += $number
71 $old = $ha->getset( $key, $new ); # $o = $v, $v = $n, $o
72 # pipeline, provides atomicity for shared objects, MCE::Shared v1.09+
74 @vals = $ha->pipeline( # ( "a_a", "b_b", "c_c" )
76 [ "set", foo => "a_a" ],
77 [ "set", bar => "b_b" ],
78 [ "set", baz => "c_c" ],
79 [ "mget", qw/ foo bar baz / ]
80 );
81 For normal hash behavior, the TIE interface is supported.
83 # non-shared or local construction for use by a single process
85 use MCE::Shared::Hash;
87 tie my %ha, "MCE::Shared::Hash";
89 # construction for sharing with other threads and processes
91 use MCE::Shared;
93 tie my %ha, "MCE::Shared";
95 # usage
97 my $val;
99 if ( !defined ( $val = $ha{some_key} ) ) {
101 $val = $ha{some_key} = "some_value";
102 }
103 $ha{some_key} = 0;
105 tied(%ha)->incrby("some_key", 20);
107 tied(%ha)->incrby(some_key => 20);
108
110 Several methods take a query string for an argument. The format of the
111 string is described below. In the context of sharing, the query
112 mechanism is beneficial for the shared-manager process. It is able to
113 perform the query where the data resides versus the client-process grep
114 locally involving lots of IPC.
115 o Basic demonstration
117 @keys = $ha->keys( "query string given here" );
119 @keys = $ha->keys( "val =~ /pattern/" );
120 o Supported operators: =~ !~ eq ne lt le gt ge == != < <= > >=
122 o Multiple expressions delimited by :AND or :OR, mixed case allowed
123 "key eq 'some key' :or (val > 5 :and val < 9)"
125 "key eq some key :or (val > 5 :and val < 9)"
126 "key =~ /pattern/i :And val =~ /pattern/i"
127 "val eq foo baz :OR key !~ /pattern/i"
128 * key matches on keys in the hash
130 * likewise, val matches on values
131 o Quoting is optional inside the string
133 "key =~ /pattern/i :AND val eq 'foo bar'" # val eq "foo bar"
135 "key =~ /pattern/i :AND val eq foo bar" # val eq "foo bar"
136 Examples.
138 # search capability key/val: =~ !~ eq ne lt le gt ge == != < <= > >=
140 # key/val means to match against actual key/val respectively
141 @keys = $ha->keys( "key eq 'some key' :or (val > 5 :and val < 9)" );
143 @keys = $ha->keys( "key eq some key :or (val > 5 :and val < 9)" );
144 @keys = $ha->keys( "key =~ /$pattern/i" );
146 @keys = $ha->keys( "key !~ /$pattern/i" );
147 @keys = $ha->keys( "val =~ /$pattern/i" );
148 @keys = $ha->keys( "val !~ /$pattern/i" );
149 %pairs = $ha->pairs( "key == $number" );
151 %pairs = $ha->pairs( "key != $number :and val > 100" );
152 %pairs = $ha->pairs( "key < $number :or key > $number" );
153 %pairs = $ha->pairs( "val <= $number" );
154 %pairs = $ha->pairs( "val > $number" );
155 %pairs = $ha->pairs( "val >= $number" );
156 @vals = $ha->vals( "key eq $string" );
158 @vals = $ha->vals( "key ne $string with space" );
159 @vals = $ha->vals( "key lt $string :or val =~ /$pat1|$pat2/" );
160 @vals = $ha->vals( "val le $string :and val eq 'foo bar'" );
161 @vals = $ha->vals( "val le $string :and val eq foo bar" );
162 @vals = $ha->vals( "val gt $string" );
163 @vals = $ha->vals( "val ge $string" );
164
166 This module may involve TIE when accessing the object via hash-like
167 behavior. Only shared instances are impacted if doing so. Although
168 likely fast enough for many use cases, the OO interface is recommended
169 for best performance.
170 MCE::Shared::Hash->new ( key, value [, key, value, ... ] )
172 MCE::Shared->hash ( key, value [, key, value, ... ] )
173 Constructs a new object, with an optional list of key-value pairs.
174 # non-shared or local construction for use by a single process
176 use MCE::Shared::Hash;
178 $ha = MCE::Shared::Hash->new( @pairs );
180 $ha = MCE::Shared::Hash->new( );
181 # construction for sharing with other threads and processes
183 use MCE::Shared;
185 $ha = MCE::Shared->hash( @pairs );
187 $ha = MCE::Shared->hash( );
188 assign ( key, value [, key, value, ... ] )
190 Clears the hash, then sets multiple key-value pairs and returns the
191 number of keys stored in the hash. This is equivalent to "clear",
192 "mset".
193 $len = $ha->assign( "key1" => "val1", "key2" => "val2" ); # 2
195 $len = %{$ha} = ( "key1" => "val1", "key2" => "val2" ); # 4
196 API available since 1.007.
198 clear
200 Removes all key-value pairs from the hash.
201 $ha->clear;
203 %{$ha} = ();
204 clone ( key [, key, ... ] )
206 Creates a shallow copy, a "MCE::Shared::Hash" object. It returns an
207 exact copy if no arguments are given. Otherwise, the object includes
208 only the given keys. Keys that do not exist in the hash will have the
209 "undef" value.
210 $ha2 = $ha->clone( "key1", "key2" );
212 $ha2 = $ha->clone;
213 delete ( key )
215 Deletes and returns the value by given key or "undef" if the key does
216 not exists in the hash.
217 $val = $ha->delete( "some_key" );
219 $val = delete $ha->{ "some_key" };
220 del
222 "del" is an alias for "delete".
223 exists ( key )
225 Determines if a key exists in the hash.
226 if ( $ha->exists( "some_key" ) ) { ... }
228 if ( exists $ha->{ "some_key" } ) { ... }
229 flush ( key [, key, ... ] )
231 Same as "clone". Though, clears all existing items before returning.
232 get ( key )
234 Gets the value of a hash key or "undef" if the key does not exists.
235 $val = $ha->get( "some_key" );
237 $val = $ha->{ "some_key" };
238 iterator ( key [, key, ... ] )
240 Returns a code reference for iterating a list of key-value pairs stored
241 in the hash when no arguments are given. Otherwise, returns a code
242 reference for iterating the given keys in the same order. Keys that do
243 not exist will have the "undef" value.
244 The list of keys to return is set when the closure is constructed.
246 Later keys added to the hash are not included. Subsequently, the
247 "undef" value is returned for deleted keys.
248 $iter = $ha->iterator;
250 $iter = $ha->iterator( "key1", "key2" );
251 while ( my ( $key, $val ) = $iter->() ) {
253 ...
254 }
255 iterator ( "query string" )
257 Returns a code reference for iterating a list of key-value pairs that
258 match the given criteria. It returns an empty list if the search found
259 nothing. The syntax for the "query string" is described above.
260 $iter = $ha->iterator( "val eq some_value" );
262 $iter = $ha->iterator( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
263 $iter = $ha->iterator( "val eq sun :OR val eq moon :OR val eq foo" );
264 $iter = $ha->iterator( "key =~ /$pattern/" );
265 while ( my ( $key, $val ) = $iter->() ) {
267 ...
268 }
269 keys ( key [, key, ... ] )
271 Returns all keys in the hash when no arguments are given. Otherwise,
272 returns the given keys in the same order. Keys that do not exist will
273 have the "undef" value. In scalar context, returns the size of the
274 hash.
275 @keys = $ha->keys( "key1", "key2" );
277 @keys = $ha->keys; # faster
279 @keys = keys %{$ha}; # involves TIE overhead
280 $len = $ha->keys; # ditto
282 $len = keys %{$ha};
283 keys ( "query string" )
285 Returns only keys that match the given criteria. It returns an empty
286 list if the search found nothing. The syntax for the "query string" is
287 described above. In scalar context, returns the size of the resulting
288 list.
289 @keys = $ha->keys( "val eq some_value" );
291 @keys = $ha->keys( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
292 @keys = $ha->keys( "val eq sun :OR val eq moon :OR val eq foo" );
293 $len = $ha->keys( "key =~ /$pattern/" );
294 len ( key )
296 Returns the size of the hash when no arguments are given. For the given
297 key, returns the length of the value stored at key or the "undef" value
298 if the key does not exists.
299 $size = $ha->len;
301 $len = $ha->len( "key1" );
302 $len = length $ha->{ "key1" };
303 mdel ( key [, key, ... ] )
305 Deletes one or more keys in the hash and returns the number of keys
306 deleted. A given key which does not exist in the hash is not counted.
307 $cnt = $ha->mdel( "key1", "key2" );
309 mexists ( key [, key, ... ] )
311 Returns a true value if all given keys exists in the hash. A false
312 value is returned otherwise.
313 if ( $ha->mexists( "key1", "key2" ) ) { ... }
315 mget ( key [, key, ... ] )
317 Gets the values of all given keys. It returns "undef" for keys which do
318 not exists in the hash.
319 ( $val1, $val2 ) = $ha->mget( "key1", "key2" );
321 mset ( key, value [, key, value, ... ] )
323 Sets multiple key-value pairs in a hash and returns the number of keys
324 stored in the hash.
325 $len = $ha->mset( "key1" => "val1", "key2" => "val2" );
327 merge
329 "merge" is an alias for "mset".
330 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 @pairs = $ha->pairs( "key1", "key2" );
338 @pairs = $ha->pairs;
340 $len = $ha->pairs;
341 pairs ( "query string" )
343 Returns only key-value pairs that match the given criteria. It returns
344 an empty list if the search found nothing. The syntax for the "query
345 string" is described above. In scalar context, returns the size of the
346 resulting list.
347 @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 pipeline ( [ func1, @args ], [ func2, @args ], ... )
354 Combines multiple commands for the object to be processed serially. For
355 shared objects, the call is made atomically due to single IPC to the
356 shared-manager process. The "pipeline" method is fully
357 "wantarray"-aware and receives a list of commands and their arguments.
358 In scalar or list context, it returns data from the last command in the
359 pipeline.
360 @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 $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 $ha->pipeline(
376 [ "set", foo => "m_m" ],
377 [ "set", bar => "n_n" ],
378 [ "set", baz => "o_o" ]
379 );
380 Current API available since 1.809.
382 pipeline_ex ( [ func1, @args ], [ func2, @args ], ... )
384 Same as "pipeline", but returns data for every command in the pipeline.
385 @vals = $ha->pipeline_ex( # ( "a_a", "b_b", "c_c" )
387 [ "set", foo => "a_a" ],
388 [ "set", bar => "b_b" ],
389 [ "set", baz => "c_c" ]
390 );
391 Current API available since 1.809.
393 set ( key, value )
395 Sets the value of the given hash key and returns its new value.
396 $val = $ha->set( "key", "value" );
398 $val = $ha->{ "key" } = "value";
399 setnx ( key, value )
401 Sets the value of a hash key, only if the key does not exist. Returns a
402 1 for new key or 0 if the key already exists and no operation was
403 performed.
404 $ret = $ha->setnx( "key", "value" );
406 Current API available since 1.872.
408 values ( key [, key, ... ] )
410 Returns all values in the hash when no arguments are given. Otherwise,
411 returns values for the given keys in the same order. Keys that do not
412 exist will have the "undef" value. In scalar context, returns the size
413 of the hash.
414 @vals = $ha->values( "key1", "key2" );
416 @vals = $ha->values; # faster
418 @vals = values %{$ha}; # involves TIE overhead
419 $len = $ha->values; # ditto
421 $len = values %{$ha};
422 values ( "query string" )
424 Returns only values that match the given criteria. It returns an empty
425 list if the search found nothing. The syntax for the "query string" is
426 described above. In scalar context, returns the size of the resulting
427 list.
428 @vals = $ha->values( "val eq some_value" );
430 @vals = $ha->values( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
431 @vals = $ha->values( "val eq sun :OR val eq moon :OR val eq foo" );
432 $len = $ha->values( "key =~ /$pattern/" );
433 vals
435 "vals" is an alias for "values".
436
438 This module is equipped with sugar methods to not have to call "set"
439 and "get" explicitly. In shared context, the benefit is atomicity and
440 reduction in inter-process communication.
441 The API resembles a subset of the Redis primitives
443 <https://redis.io/commands#strings> with key representing the hash key.
444 append ( key, string )
446 Appends a value to a key and returns its new length.
447 $len = $ha->append( $key, "foo" );
449 decr ( key )
451 Decrements the value of a key by one and returns its new value.
452 $num = $ha->decr( $key );
454 decrby ( key, number )
456 Decrements the value of a key by the given number and returns its new
457 value.
458 $num = $ha->decrby( $key, 2 );
460 getdecr ( key )
462 Decrements the value of a key by one and returns its old value.
463 $old = $ha->getdecr( $key );
465 getincr ( key )
467 Increments the value of a key by one and returns its old value.
468 $old = $ha->getincr( $key );
470 getset ( key, value )
472 Sets the value of a key and returns its old value.
473 $old = $ha->getset( $key, "baz" );
475 incr ( key )
477 Increments the value of a key by one and returns its new value.
478 $num = $ha->incr( $key );
480 incrby ( key, number )
482 Increments the value of a key by the given number and returns its new
483 value.
484 $num = $ha->incrby( $key, 2 );
486
488 The implementation is inspired by Tie::StdHash.
489
491 MCE, MCE::Hobo, MCE::Shared
492
494 Mario E. Roy, <marioeroy AT gmail DOT com>
495perl v5.36.0 2023-01-20 MCE::Shared::Hash(3)