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.840
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 new ( key, value [, key, value, ... ] )
171 Constructs a new object, with an optional list of key-value pairs.
172 # non-shared or local construction for use by a single process
174 use MCE::Shared::Hash;
176 $ha = MCE::Shared::Hash->new( @pairs );
178 $ha = MCE::Shared::Hash->new( );
179 # construction for sharing with other threads and processes
181 use MCE::Shared;
183 $ha = MCE::Shared->hash( @pairs );
185 $ha = MCE::Shared->hash( );
186 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 $len = $ha->assign( "key1" => "val1", "key2" => "val2" ); # 2
193 $len = %{$ha} = ( "key1" => "val1", "key2" => "val2" ); # 4
194 API available since 1.007.
196 clear
198 Removes all key-value pairs from the hash.
199 $ha->clear;
201 %{$ha} = ();
202 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 $ha2 = $ha->clone( "key1", "key2" );
210 $ha2 = $ha->clone;
211 delete ( key )
213 Deletes and returns the value by given key or "undef" if the key
214 does not exists in the hash.
215 $val = $ha->delete( "some_key" );
217 $val = delete $ha->{ "some_key" };
218 del
220 "del" is an alias for "delete".
221 exists ( key )
223 Determines if a key exists in the hash.
224 if ( $ha->exists( "some_key" ) ) { ... }
226 if ( exists $ha->{ "some_key" } ) { ... }
227 flush ( key [, key, ... ] )
229 Same as "clone". Though, clears all existing items before returning.
230 get ( key )
232 Gets the value of a hash key or "undef" if the key does not exists.
233 $val = $ha->get( "some_key" );
235 $val = $ha->{ "some_key" };
236 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 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 $iter = $ha->iterator;
248 $iter = $ha->iterator( "key1", "key2" );
249 while ( my ( $key, $val ) = $iter->() ) {
251 ...
252 }
253 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 $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
272 will have the "undef" value. In scalar context, returns the size of
273 the 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"
286 is described above. In scalar context, returns the size of the
287 resulting 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
296 given key, returns the length of the value stored at key or the
297 "undef" value 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
306 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
318 do 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
324 keys 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
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 @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.
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 @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
385 pipeline.
386 @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 Current API available since 1.809.
394 set ( key, value )
396 Sets the value of the given hash key and returns its new value.
397 $val = $ha->set( "key", "value" );
399 $val = $ha->{ "key" } = "value";
400 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 @vals = $ha->values( "key1", "key2" );
408 @vals = $ha->values; # faster
410 @vals = values %{$ha}; # involves TIE overhead
411 $len = $ha->values; # ditto
413 $len = values %{$ha};
414 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 @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 vals
427 "vals" is an alias for "values".
428
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 The API resembles a subset of the Redis primitives
435 <http://redis.io/commands#strings> with key representing the hash key.
436 append ( key, string )
438 Appends a value to a key and returns its new length.
439 $len = $ha->append( $key, "foo" );
441 decr ( key )
443 Decrements the value of a key by one and returns its new value.
444 $num = $ha->decr( $key );
446 decrby ( key, number )
448 Decrements the value of a key by the given number and returns its
449 new value.
450 $num = $ha->decrby( $key, 2 );
452 getdecr ( key )
454 Decrements the value of a key by one and returns its old value.
455 $old = $ha->getdecr( $key );
457 getincr ( key )
459 Increments the value of a key by one and returns its old value.
460 $old = $ha->getincr( $key );
462 getset ( key, value )
464 Sets the value of a key and returns its old value.
465 $old = $ha->getset( $key, "baz" );
467 incr ( key )
469 Increments the value of a key by one and returns its new value.
470 $num = $ha->incr( $key );
472 incrby ( key, number )
474 Increments the value of a key by the given number and returns its
475 new value.
476 $num = $ha->incrby( $key, 2 );
478
480 The implementation is inspired by Tie::StdHash.
481
483 MCE, MCE::Hobo, MCE::Shared
484
486 Mario E. Roy, <marioeroy AT gmail DOT com>
487perl v5.28.1 2019-01-04 MCE::Shared::Hash(3)