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.864
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   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
174        # non-shared or local construction for use by a single process
175
176        use MCE::Shared::Hash;
177
178        $ha = MCE::Shared::Hash->new( @pairs );
179        $ha = MCE::Shared::Hash->new( );
180
181        # construction for sharing with other threads and processes
182
183        use MCE::Shared;
184
185        $ha = MCE::Shared->hash( @pairs );
186        $ha = MCE::Shared->hash( );
187
188   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
193        $len = $ha->assign( "key1" => "val1", "key2" => "val2" );  # 2
194        $len = %{$ha} = ( "key1" => "val1", "key2" => "val2" );    # 4
195
196       API available since 1.007.
197
198   clear
199       Removes all key-value pairs from the hash.
200
201        $ha->clear;
202        %{$ha} = ();
203
204   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
210        $ha2 = $ha->clone( "key1", "key2" );
211        $ha2 = $ha->clone;
212
213   delete ( key )
214       Deletes and returns the value by given key or "undef" if the key does
215       not exists in the hash.
216
217        $val = $ha->delete( "some_key" );
218        $val = delete $ha->{ "some_key" };
219
220   del
221       "del" is an alias for "delete".
222
223   exists ( key )
224       Determines if a key exists in the hash.
225
226        if ( $ha->exists( "some_key" ) ) { ... }
227        if ( exists $ha->{ "some_key" } ) { ... }
228
229   flush ( key [, key, ... ] )
230       Same as "clone". Though, clears all existing items before returning.
231
232   get ( key )
233       Gets the value of a hash key or "undef" if the key does not exists.
234
235        $val = $ha->get( "some_key" );
236        $val = $ha->{ "some_key" };
237
238   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
244       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
248        $iter = $ha->iterator;
249        $iter = $ha->iterator( "key1", "key2" );
250
251        while ( my ( $key, $val ) = $iter->() ) {
252           ...
253        }
254
255   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
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 will
272       have the "undef" value. In scalar context, returns the size of the
273       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" is
286       described above. In scalar context, returns the size of the resulting
287       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 given
296       key, returns the length of the value stored at key or the "undef" value
297       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 counted.
306
307        $cnt = $ha->mdel( "key1", "key2" );
308
309   mexists ( key [, key, ... ] )
310       Returns a true value if all given keys exists in the hash. A false
311       value is returned otherwise.
312
313        if ( $ha->mexists( "key1", "key2" ) ) { ... }
314
315   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
319        ( $val1, $val2 ) = $ha->mget( "key1", "key2" );
320
321   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
325        $len = $ha->mset( "key1" => "val1", "key2" => "val2" );
326
327   merge
328       "merge" is an alias for "mset".
329
330   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
336        @pairs = $ha->pairs( "key1", "key2" );
337
338        @pairs = $ha->pairs;
339        $len   = $ha->pairs;
340
341   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
347        @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
352   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
360        @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
367        $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
374        $ha->pipeline(
375           [ "set", foo => "m_m" ],
376           [ "set", bar => "n_n" ],
377           [ "set", baz => "o_o" ]
378        );
379
380       Current API available since 1.809.
381
382   pipeline_ex ( [ func1, @args ], [ func2, @args ], ... )
383       Same as "pipeline", but returns data for every command in the pipeline.
384
385        @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
391       Current API available since 1.809.
392
393   set ( key, value )
394       Sets the value of the given hash key and returns its new value.
395
396        $val = $ha->set( "key", "value" );
397        $val = $ha->{ "key" } = "value";
398
399   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
405        @vals = $ha->values( "key1", "key2" );
406
407        @vals = $ha->values;     # faster
408        @vals = values %{$ha};   # involves TIE overhead
409
410        $len  = $ha->values;     # ditto
411        $len  = values %{$ha};
412
413   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
419        @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
424   vals
425       "vals" is an alias for "values".
426

SUGAR METHODS

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
432       The API resembles a subset of the Redis primitives
433       <http://redis.io/commands#strings> with key representing the hash key.
434
435   append ( key, string )
436       Appends a value to a key and returns its new length.
437
438        $len = $ha->append( $key, "foo" );
439
440   decr ( key )
441       Decrements the value of a key by one and returns its new value.
442
443        $num = $ha->decr( $key );
444
445   decrby ( key, number )
446       Decrements the value of a key by the given number and returns its new
447       value.
448
449        $num = $ha->decrby( $key, 2 );
450
451   getdecr ( key )
452       Decrements the value of a key by one and returns its old value.
453
454        $old = $ha->getdecr( $key );
455
456   getincr ( key )
457       Increments the value of a key by one and returns its old value.
458
459        $old = $ha->getincr( $key );
460
461   getset ( key, value )
462       Sets the value of a key and returns its old value.
463
464        $old = $ha->getset( $key, "baz" );
465
466   incr ( key )
467       Increments the value of a key by one and returns its new value.
468
469        $num = $ha->incr( $key );
470
471   incrby ( key, number )
472       Increments the value of a key by the given number and returns its new
473       value.
474
475        $num = $ha->incrby( $key, 2 );
476

CREDITS

478       The implementation is inspired by Tie::StdHash.
479

INDEX

481       MCE, MCE::Hobo, MCE::Shared
482

AUTHOR

484       Mario E. Roy, <marioeroy AT gmail DOT com>
485
486
487
488perl v5.30.1                      2020-01-30              MCE::Shared::Hash(3)
Impressum