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.880
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        $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
49        $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
56        $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
62        # included, sugar methods without having to call set/get explicitly
63
64        $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
73        # pipeline, provides atomicity for shared objects, MCE::Shared v1.09+
74
75        @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
82       For normal hash behavior, the TIE interface is supported.
83
84        # non-shared or local construction for use by a single process
85
86        use MCE::Shared::Hash;
87
88        tie my %ha, "MCE::Shared::Hash";
89
90        # construction for sharing with other threads and processes
91
92        use MCE::Shared;
93
94        tie my %ha, "MCE::Shared";
95
96        # usage
97
98        my $val;
99
100        if ( !defined ( $val = $ha{some_key} ) ) {
101           $val = $ha{some_key} = "some_value";
102        }
103
104        $ha{some_key} = 0;
105
106        tied(%ha)->incrby("some_key", 20);
107        tied(%ha)->incrby(some_key => 20);
108

SYNTAX for QUERY STRING

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
116        o Basic demonstration
117
118          @keys = $ha->keys( "query string given here" );
119          @keys = $ha->keys( "val =~ /pattern/" );
120
121        o Supported operators: =~ !~ eq ne lt le gt ge == != < <= > >=
122        o Multiple expressions delimited by :AND or :OR, mixed case allowed
123
124          "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
129          * key matches on keys in the hash
130          * likewise, val matches on values
131
132        o Quoting is optional inside the string
133
134          "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
137       Examples.
138
139        # search capability key/val: =~ !~ eq ne lt le gt ge == != < <= > >=
140        # key/val means to match against actual key/val respectively
141
142        @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
145        @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
150        %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
157        @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

API DOCUMENTATION

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
171   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
175        # non-shared or local construction for use by a single process
176
177        use MCE::Shared::Hash;
178
179        $ha = MCE::Shared::Hash->new( @pairs );
180        $ha = MCE::Shared::Hash->new( );
181
182        # construction for sharing with other threads and processes
183
184        use MCE::Shared;
185
186        $ha = MCE::Shared->hash( @pairs );
187        $ha = MCE::Shared->hash( );
188
189   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
194        $len = $ha->assign( "key1" => "val1", "key2" => "val2" );  # 2
195        $len = %{$ha} = ( "key1" => "val1", "key2" => "val2" );    # 4
196
197       API available since 1.007.
198
199   clear
200       Removes all key-value pairs from the hash.
201
202        $ha->clear;
203        %{$ha} = ();
204
205   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
211        $ha2 = $ha->clone( "key1", "key2" );
212        $ha2 = $ha->clone;
213
214   delete ( key )
215       Deletes and returns the value by given key or "undef" if the key does
216       not exists in the hash.
217
218        $val = $ha->delete( "some_key" );
219        $val = delete $ha->{ "some_key" };
220
221   del
222       "del" is an alias for "delete".
223
224   exists ( key )
225       Determines if a key exists in the hash.
226
227        if ( $ha->exists( "some_key" ) ) { ... }
228        if ( exists $ha->{ "some_key" } ) { ... }
229
230   flush ( key [, key, ... ] )
231       Same as "clone". Though, clears all existing items before returning.
232
233   get ( key )
234       Gets the value of a hash key or "undef" if the key does not exists.
235
236        $val = $ha->get( "some_key" );
237        $val = $ha->{ "some_key" };
238
239   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
245       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
249        $iter = $ha->iterator;
250        $iter = $ha->iterator( "key1", "key2" );
251
252        while ( my ( $key, $val ) = $iter->() ) {
253           ...
254        }
255
256   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
261        $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
266        while ( my ( $key, $val ) = $iter->() ) {
267           ...
268        }
269
270   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
276        @keys = $ha->keys( "key1", "key2" );
277
278        @keys = $ha->keys;     # faster
279        @keys = keys %{$ha};   # involves TIE overhead
280
281        $len  = $ha->keys;     # ditto
282        $len  = keys %{$ha};
283
284   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
290        @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
295   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
300        $size = $ha->len;
301        $len  = $ha->len( "key1" );
302        $len  = length $ha->{ "key1" };
303
304   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
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 do
318       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 keys
324       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 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
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. 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
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 pipeline.
385
386        @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
392       Current API available since 1.809.
393
394   set ( key, value )
395       Sets the value of the given hash key and returns its new value.
396
397        $val = $ha->set( "key", "value" );
398        $val = $ha->{ "key" } = "value";
399
400   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
405        $ret = $ha->setnx( "key", "value" );
406
407       Current API available since 1.872.
408
409   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
415        @vals = $ha->values( "key1", "key2" );
416
417        @vals = $ha->values;     # faster
418        @vals = values %{$ha};   # involves TIE overhead
419
420        $len  = $ha->values;     # ditto
421        $len  = values %{$ha};
422
423   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
429        @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
434   vals
435       "vals" is an alias for "values".
436

SUGAR METHODS

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

CREDITS

488       The implementation is inspired by Tie::StdHash.
489

INDEX

491       MCE, MCE::Hobo, MCE::Shared
492

AUTHOR

494       Mario E. Roy, <marioeroy AT gmail DOT com>
495
496
497
498perl v5.36.0                      2023-01-20              MCE::Shared::Hash(3)
Impressum