1MCE::Shared::Array(3) User Contributed Perl DocumentationMCE::Shared::Array(3)
2
6 MCE::Shared::Array - Array helper class
7
9 This document describes MCE::Shared::Array version 1.840
10
12 An array helper class for use as a standalone or managed by
13 MCE::Shared.
14
16 # non-shared or local construction for use by a single process
17 use MCE::Shared::Array;
19 my $ar = MCE::Shared::Array->new( @list );
21 # construction for sharing with other threads and processes
23 use MCE::Shared;
25 my $ar = MCE::Shared->array( @list );
27 # array-like dereferencing
29 my $val = $ar->[$index];
31 $ar->[$index] = $val;
32 @{$ar} = ();
34 # OO interface
36 $val = $ar->set( $index, $val );
38 $val = $ar->get( $index);
39 $val = $ar->delete( $index ); # del is an alias for delete
40 $bool = $ar->exists( $index );
41 void = $ar->clear();
42 $len = $ar->len(); # scalar @{ $ar }
43 $len = $ar->len( $index ); # length $ar->[ $index ]
44 $val = $ar->pop();
45 $len = $ar->push( @list );
46 $val = $ar->shift();
47 $len = $ar->unshift( @list );
48 @list = $ar->splice( $offset, $length, @list );
49 $ar2 = $ar->clone( @indices ); # @indices is optional
51 $ar3 = $ar->flush( @indices );
52 $iter = $ar->iterator( @indices ); # ($idx, $val) = $iter->()
53 @keys = $ar->keys( @indices );
54 %pairs = $ar->pairs( @indices );
55 @vals = $ar->values( @indices ); # vals is an alias for values
56 $len = $ar->assign( $idx/$val pairs ); # equivalent to ->clear, ->push
58 $cnt = $ar->mdel( @indices );
59 @vals = $ar->mget( @indices );
60 $bool = $ar->mexists( @indices ); # true if all indices exists
61 $len = $ar->mset( $idx/$val pairs ); # merge is an alias for mset
62 @vals = $ar->range( $start, $stop );
64 @vals = $ar->sort(); # $a <=> $b default
66 @vals = $ar->sort( "desc" ); # $b <=> $a
67 @vals = $ar->sort( "alpha" ); # $a cmp $b
68 @vals = $ar->sort( "alpha desc" ); # $b cmp $a
69 # included, sugar methods without having to call set/get explicitly
71 $len = $ar->append( $index, $string ); # $val .= $string
73 $val = $ar->decr( $index ); # --$val
74 $val = $ar->decrby( $index, $number ); # $val -= $number
75 $val = $ar->getdecr( $index ); # $val--
76 $val = $ar->getincr( $index ); # $val++
77 $val = $ar->incr( $index ); # ++$val
78 $val = $ar->incrby( $index, $number ); # $val += $number
79 $old = $ar->getset( $index, $new ); # $o = $v, $v = $n, $o
80 # pipeline, provides atomicity for shared objects, MCE::Shared v1.09+
82 @vals = $ar->pipeline( # ( "a_a", "b_b", "c_c" )
84 [ "set", 0 => "a_a" ],
85 [ "set", 1 => "b_b" ],
86 [ "set", 2 => "c_c" ],
87 [ "mget", qw/ 0 1 2 / ]
88 );
89 For normal array behavior, the TIE interface is supported.
91 # non-shared or local construction for use by a single process
93 use MCE::Shared::Array;
95 tie my @ar, "MCE::Shared::Array";
97 # construction for sharing with other threads and processes
99 use MCE::Shared;
101 tie my @ar, "MCE::Shared";
103 # usage
105 my $val;
107 if ( !defined ( $val = $ar[some_index] ) ) {
109 $val = $ar[some_index] = "some_value";
110 }
111 $ar[some_index] = 0;
113 tied(@ar)->incrby("some_index", 20);
115 tied(@ar)->incrby(some_index => 20);
116
118 Several methods take a query string for an argument. The format of the
119 string is described below. In the context of sharing, the query
120 mechanism is beneficial for the shared-manager process. It is able to
121 perform the query where the data resides versus the client-process grep
122 locally involving lots of IPC.
123 o Basic demonstration
125 @keys = $ar->keys( "query string given here" );
127 @keys = $ar->keys( "val =~ /pattern/" );
128 o Supported operators: =~ !~ eq ne lt le gt ge == != < <= > >=
130 o Multiple expressions delimited by :AND or :OR, mixed case allowed
131 "key == 3 :or (val > 5 :and val < 9)"
133 "key =~ /pattern/i :And val =~ /pattern/i"
134 "val eq foo baz :OR key !~ /pattern/i"
135 * key matches on indices in the array
137 * likewise, val matches on values
138 o Quoting is optional inside the string
140 "key =~ /pattern/i :AND val eq 'foo bar'" # val eq "foo bar"
142 "key =~ /pattern/i :AND val eq foo bar" # val eq "foo bar"
143 Examples.
145 # search capability key/val: =~ !~ eq ne lt le gt ge == != < <= > >=
147 # key/val means to match against actual key/val respectively
148 @keys = $ar->keys( "key == 3 :or (val > 5 :and val < 9)" );
150 @keys = $ar->keys( "key =~ /$pattern/i" );
152 @keys = $ar->keys( "key !~ /$pattern/i" );
153 @keys = $ar->keys( "val =~ /$pattern/i" );
154 @keys = $ar->keys( "val !~ /$pattern/i" );
155 %pairs = $ar->pairs( "key == $number" );
157 %pairs = $ar->pairs( "key != $number :and val > 100" );
158 %pairs = $ar->pairs( "key < $number :or key > $number" );
159 %pairs = $ar->pairs( "val <= $number" );
160 %pairs = $ar->pairs( "val > $number" );
161 %pairs = $ar->pairs( "val >= $number" );
162 @vals = $ar->vals( "key eq $string" );
164 @vals = $ar->vals( "key ne $string with space" );
165 @vals = $ar->vals( "key lt $string :or val =~ /$pat1|$pat2/" );
166 @vals = $ar->vals( "val le $string :and val eq 'foo bar'" );
167 @vals = $ar->vals( "val le $string :and val eq foo bar" );
168 @vals = $ar->vals( "val gt $string" );
169 @vals = $ar->vals( "val ge $string" );
170
172 This module may involve TIE when accessing the object via array-like
173 behavior. Only shared instances are impacted if doing so. Although
174 likely fast enough for many use cases, the OO interface is recommended
175 for best performance.
176 new ( val [, val, ... ] )
178 Constructs a new object, with an optional list of values.
179 # non-shared or local construction for use by a single process
181 use MCE::Shared::Array;
183 $ar = MCE::Shared::Array->new( @list );
185 $ar = MCE::Shared::Array->new( );
186 # construction for sharing with other threads and processes
188 use MCE::Shared;
190 $ar = MCE::Shared->array( @list );
192 $ar = MCE::Shared->array( );
193 assign ( value [, value, ... ] )
195 Clears the list, then appends one or multiple values and returns the
196 new length. This is equivalent to "clear", "push".
197 $len = $ar->assign( "val1", "val2" );
199 $len = @{$ar} = ( "val1", "val2" );
200 API available since 1.007.
202 clear
204 Removes all elements from the array.
205 $ar->clear;
207 @{$ar} = ();
208 clone ( index [, index, ... ] )
210 Creates a shallow copy, a "MCE::Shared::Array" object. It returns an
211 exact copy if no arguments are given. Otherwise, the object includes
212 only the given indices in the same order. Indices that do not exist
213 in the array will have the "undef" value.
214 $ar2 = $ar->clone( 0, 1 );
216 $ar2 = $ar->clone;
217 delete ( index )
219 Deletes and returns the value associated by index or "undef" if
220 index exceeds the size of the list.
221 $val = $ar->delete( 20 );
223 $val = delete $ar->[ 20 ];
224 del
226 "del" is an alias for "delete".
227 exists ( index )
229 Determines if an element by its index exists in the array. The
230 behavior is strongly tied to the use of delete on lists.
231 $ar->push(qw/ value0 value1 value2 value3 /);
233 $ar->exists( 2 ); # True
235 $ar->delete( 2 ); # value2
236 $ar->exists( 2 ); # False
237 $ar->exists( 3 ); # True
239 exists $ar->[ 3 ]; # True
240 flush ( index [, index, ... ] )
242 Same as "clone". Though, clears all existing items before returning.
243 get ( index )
245 Gets the value of an element by its index or "undef" if the index
246 does not exists.
247 $val = $ar->get( 2 );
249 $val = $ar->[ 2 ];
250 iterator ( index [, index, ... ] )
252 Returns a code reference for iterating a list of index-value pairs
253 stored in the array when no arguments are given. Otherwise, returns
254 a code reference for iterating the given indices in the same order.
255 Indices that do not exist will have the "undef" value.
256 The list of indices to return is set when the closure is
258 constructed. New indices added later are not included. Subsequently,
259 the "undef" value is returned for deleted indices.
260 $iter = $ar->iterator;
262 $iter = $ar->iterator( 0, 1 );
263 while ( my ( $index, $val ) = $iter->() ) {
265 ...
266 }
267 iterator ( "query string" )
269 Returns a code reference for iterating a list of index-value pairs
270 that match the given criteria. It returns an empty list if the
271 search found nothing. The syntax for the "query string" is
272 described above.
273 $iter = $ar->iterator( "val eq some_value" );
275 $iter = $ar->iterator( "key >= 50 :AND val =~ /sun|moon|air|wind/" );
276 $iter = $ar->iterator( "val eq sun :OR val eq moon :OR val eq foo" );
277 $iter = $ar->iterator( "key =~ /$pattern/" );
278 while ( my ( $index, $val ) = $iter->() ) {
280 ...
281 }
282 keys ( index [, index, ... ] )
284 Returns all indices in the array when no arguments are given.
285 Otherwise, returns the given indices in the same order. Indices that
286 do not exist will have the "undef" value. In scalar context, returns
287 the size of the array.
288 @keys = $ar->keys( 0, 1 );
290 @keys = $ar->keys; # faster
292 @keys = keys @{$ar}; # involves TIE overhead
293 $len = $ar->keys; # ditto
295 $len = keys @{$ar};
296 keys ( "query string" )
298 Returns only indices that match the given criteria. It returns an
299 empty list if the search found nothing. The syntax for the "query
300 string" is described above. In scalar context, returns the size of
301 the resulting list.
302 @keys = $ar->keys( "val eq some_value" );
304 @keys = $ar->keys( "key >= 50 :AND val =~ /sun|moon|air|wind/" );
305 @keys = $ar->keys( "val eq sun :OR val eq moon :OR val eq foo" );
306 $len = $ar->keys( "key =~ /$pattern/" );
307 len ( index )
309 Returns the size of the array when no arguments are given. For the
310 given index, returns the length of the value stored at index or the
311 "undef" value if the index does not exists.
312 $len = $ar->len;
314 $len = $ar->len( 0 );
315 $len = length $ar->[ 0 ];
316 mdel ( index [, index, ... ] )
318 Deletes one or more elements by its index and returns the number of
319 indices deleted. A given index which does not exist in the list is
320 not counted.
321 $cnt = $ar->mdel( 0, 1 );
323 mexists ( index [, index, ... ] )
325 Returns a true value if all given indices exists in the list. A
326 false value is returned otherwise.
327 if ( $ar->mexists( 0, 1 ) ) { ... }
329 mget ( index [, index, ... ] )
331 Gets multiple values from the list by its index. It returns "undef"
332 for indices which do not exists in the list.
333 ( $val1, $val2 ) = $ar->mget( 0, 1 );
335 mset ( index, value [, index, value, ... ] )
337 Sets multiple index-value pairs in the list and returns the length
338 of the list.
339 $len = $ar->mset( 0 => "val1", 1 => "val2" );
341 merge
343 "merge" is an alias for "mset".
344 pairs ( index [, index, ... ] )
346 Returns index-value pairs in the array when no arguments are given.
347 Otherwise, returns index-value pairs for the given indices in the
348 same order. Indices that do not exist will have the "undef" value.
349 In scalar context, returns the size of the array.
350 @pairs = $ar->pairs( 0, 1 );
352 @pairs = $ar->pairs;
354 $len = $ar->pairs;
355 pairs ( "query string" )
357 Returns only index-value pairs that match the given criteria. It
358 returns an empty list if the search found nothing. The syntax for
359 the "query string" is described above. In scalar context, returns
360 the size of the resulting list.
361 @pairs = $ar->pairs( "val eq some_value" );
363 @pairs = $ar->pairs( "key >= 50 :AND val =~ /sun|moon|air|wind/" );
364 @pairs = $ar->pairs( "val eq sun :OR val eq moon :OR val eq foo" );
365 $len = $ar->pairs( "key =~ /$pattern/" );
366 pipeline ( [ func1, @args ], [ func2, @args ], ... )
368 Combines multiple commands for the object to be processed serially.
369 For shared objects, the call is made atomically due to single IPC to
370 the shared-manager process. The "pipeline" method is fully
371 "wantarray"-aware and receives a list of commands and their
372 arguments. In scalar or list context, it returns data from the last
373 command in the pipeline.
374 @vals = $ar->pipeline( # ( "a_a", "b_b", "c_c" )
376 [ "set", 0 => "a_a" ],
377 [ "set", 1 => "b_b" ],
378 [ "set", 2 => "c_c" ],
379 [ "mget", qw/ 0 1 2 / ]
380 );
381 $len = $ar->pipeline( # 3, same as $ar->len
383 [ "set", 0 => "i_i" ],
384 [ "set", 1 => "j_j" ],
385 [ "set", 2 => "k_k" ],
386 [ "len" ]
387 );
388 $ar->pipeline(
390 [ "set", 0 => "m_m" ],
391 [ "set", 1 => "n_n" ],
392 [ "set", 2 => "o_o" ]
393 );
394 Current API available since 1.809.
396 pipeline_ex ( [ func1, @args ], [ func2, @args ], ... )
398 Same as "pipeline", but returns data for every command in the
399 pipeline.
400 @vals = $ar->pipeline_ex( # ( "a_a", "b_b", "c_c" )
402 [ "set", 0 => "a_a" ],
403 [ "set", 1 => "b_b" ],
404 [ "set", 2 => "c_c" ]
405 );
406 Current API available since 1.809.
408 pop
410 Removes and returns the last value of the list. If there are no
411 elements in the list, returns the undefined value.
412 $val = $ar->pop;
414 $val = pop @{$ar};
415 push ( value [, value, ... ] )
417 Appends one or multiple values to the tail of the list and returns
418 the new length.
419 $len = $ar->push( "val1", "val2" );
421 $len = push @{$ar}, "val1", "val2";
422 set ( index, value )
424 Sets the value of the given array index and returns its new value.
425 $val = $ar->set( 2, "value" );
427 $val = $ar->[ 2 ] = "value";
428 shift
430 Removes and returns the first value of the list. If there are no
431 elements in the list, returns the undefined value.
432 $val = $ar->shift;
434 $val = shift @{$ar};
435 range ( start, stop )
437 Returns the specified elements of the list. The offsets "start" and
438 "stop" can also be negative numbers indicating offsets starting at
439 the end of the list.
440 An empty list is returned if "start" is larger than the end of the
442 list. "stop" is set to the last index of the list if larger than
443 the actual end of the list.
444 @list = $ar->range( 20, 29 );
446 @list = $ar->range( -4, -1 );
447 sort ( "BY val [ ASC | DESC ] [ ALPHA ]" )
449 Returns sorted values in list context, leaving the elements intact.
450 In void context, sorts the list in-place. By default, sorting is
451 numeric when no arguments are given. The "BY val" modifier is
452 optional and may be omitted.
453 @vals = $ar->sort( "BY val" );
455 $ar->sort();
457 If the list contains string values and you want to sort them
459 lexicographically, specify the "ALPHA" modifier.
460 @vals = $ar->sort( "BY val ALPHA" );
462 $ar->sort( "ALPHA" );
464 The default is "ASC" for sorting the list from small to large. In
466 order to sort the list from large to small, specify the "DESC"
467 modifier.
468 @vals = $ar->sort( "DESC ALPHA" );
470 $ar->sort( "DESC ALPHA" );
472 splice ( offset [, length [, list ] ] )
474 Removes the elements designated by "offset" and "length" from the
475 array, and replaces them with the elements of "list", if any. The
476 behavior is similar to the Perl "splice" function.
477 @items = $ar->splice( 20, 2, @list );
479 @items = $ar->splice( 20, 2 );
480 @items = $ar->splice( 20 );
481 unshift ( value [, value, ... ] )
483 Prepends one or multiple values to the head of the list and returns
484 the new length.
485 $len = $ar->unshift( "val1", "val2" );
487 $len = unshift @{$ar}, "val1", "val2";
488 values ( index [, index, ... ] )
490 Returns all values in the array when no arguments are given.
491 Otherwise, returns values for the given indices in the same order.
492 Indices that do not exist will have the "undef" value. In scalar
493 context, returns the size of the array.
494 @vals = $ar->values( 0, 1 );
496 @vals = $ar->values; # faster
498 @vals = values @{$ar}; # involves TIE overhead
499 $len = $ar->values; # ditto
501 $len = values @{$ar};
502 values ( "query string" )
504 Returns only values that match the given criteria. It returns an
505 empty list if the search found nothing. The syntax for the "query
506 string" is described above. In scalar context, returns the size of
507 the resulting list.
508 @keys = $ar->values( "val eq some_value" );
510 @keys = $ar->values( "key >= 50 :AND val =~ /sun|moon|air|wind/" );
511 @keys = $ar->values( "val eq sun :OR val eq moon :OR val eq foo" );
512 $len = $ar->values( "key =~ /$pattern/" );
513 vals
515 "vals" is an alias for "values".
516
518 This module is equipped with sugar methods to not have to call "set"
519 and "get" explicitly. In shared context, the benefit is atomicity and
520 reduction in inter-process communication.
521 The API resembles a subset of the Redis primitives
523 <http://redis.io/commands#strings> with key representing the array
524 index.
525 append ( key, string )
527 Appends a value to a key and returns its new length.
528 $len = $ar->append( 0, "foo" );
530 decr ( key )
532 Decrements the value of a key by one and returns its new value.
533 $num = $ar->decr( 0 );
535 decrby ( key, number )
537 Decrements the value of a key by the given number and returns its
538 new value.
539 $num = $ar->decrby( 0, 2 );
541 getdecr ( key )
543 Decrements the value of a key by one and returns its old value.
544 $old = $ar->getdecr( 0 );
546 getincr ( key )
548 Increments the value of a key by one and returns its old value.
549 $old = $ar->getincr( 0 );
551 getset ( key, value )
553 Sets the value of a key and returns its old value.
554 $old = $ar->getset( 0, "baz" );
556 incr ( key )
558 Increments the value of a key by one and returns its new value.
559 $num = $ar->incr( 0 );
561 incrby ( key, number )
563 Increments the value of a key by the given number and returns its
564 new value.
565 $num = $ar->incrby( 0, 2 );
567
569 The implementation is inspired by Tie::StdArray.
570
572 MCE, MCE::Hobo, MCE::Shared
573
575 Mario E. Roy, <marioeroy AT gmail DOT com>
576perl v5.28.1 2019-01-04 MCE::Shared::Array(3)