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.880
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 MCE::Shared::Array->new ( val [, val, ... ] )
178 MCE::Shared->array ( val [, val, ... ] )
179 Constructs a new object, with an optional list of values.
180 # non-shared or local construction for use by a single process
182 use MCE::Shared::Array;
184 $ar = MCE::Shared::Array->new( @list );
186 $ar = MCE::Shared::Array->new( );
187 # construction for sharing with other threads and processes
189 use MCE::Shared;
191 $ar = MCE::Shared->array( @list );
193 $ar = MCE::Shared->array( );
194 assign ( value [, value, ... ] )
196 Clears the list, then appends one or multiple values and returns the
197 new length. This is equivalent to "clear", "push".
198 $len = $ar->assign( "val1", "val2" );
200 $len = @{$ar} = ( "val1", "val2" );
201 API available since 1.007.
203 clear
205 Removes all elements from the array.
206 $ar->clear;
208 @{$ar} = ();
209 clone ( index [, index, ... ] )
211 Creates a shallow copy, a "MCE::Shared::Array" object. It returns an
212 exact copy if no arguments are given. Otherwise, the object includes
213 only the given indices in the same order. Indices that do not exist in
214 the array will have the "undef" value.
215 $ar2 = $ar->clone( 0, 1 );
217 $ar2 = $ar->clone;
218 delete ( index )
220 Deletes and returns the value associated by index or "undef" if index
221 exceeds the size of the list.
222 $val = $ar->delete( 20 );
224 $val = delete $ar->[ 20 ];
225 del
227 "del" is an alias for "delete".
228 exists ( index )
230 Determines if an element by its index exists in the array. The behavior
231 is strongly tied to the use of delete on lists.
232 $ar->push(qw/ value0 value1 value2 value3 /);
234 $ar->exists( 2 ); # True
236 $ar->delete( 2 ); # value2
237 $ar->exists( 2 ); # False
238 $ar->exists( 3 ); # True
240 exists $ar->[ 3 ]; # True
241 flush ( index [, index, ... ] )
243 Same as "clone". Though, clears all existing items before returning.
244 get ( index )
246 Gets the value of an element by its index or "undef" if the index does
247 not exists.
248 $val = $ar->get( 2 );
250 $val = $ar->[ 2 ];
251 iterator ( index [, index, ... ] )
253 Returns a code reference for iterating a list of index-value pairs
254 stored in the array when no arguments are given. Otherwise, returns a
255 code reference for iterating the given indices in the same order.
256 Indices that do not exist will have the "undef" value.
257 The list of indices to return is set when the closure is constructed.
259 New indices added later are not included. Subsequently, the "undef"
260 value is returned for deleted indices.
261 $iter = $ar->iterator;
263 $iter = $ar->iterator( 0, 1 );
264 while ( my ( $index, $val ) = $iter->() ) {
266 ...
267 }
268 iterator ( "query string" )
270 Returns a code reference for iterating a list of index-value pairs that
271 match the given criteria. It returns an empty list if the search found
272 nothing. The syntax for the "query string" is 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 do
286 not exist will have the "undef" value. In scalar context, returns the
287 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 empty
299 list if the search found nothing. The syntax for the "query string" is
300 described above. In scalar context, returns the size of the resulting
301 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 not
320 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 false
326 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" for
332 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 of
338 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 same
348 order. Indices that do not exist will have the "undef" value. In scalar
349 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 the
359 "query string" is described above. In scalar context, returns the size
360 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. For
369 shared objects, the call is made atomically due to single IPC to the
370 shared-manager process. The "pipeline" method is fully
371 "wantarray"-aware and receives a list of commands and their arguments.
372 In scalar or list context, it returns data from the last command in the
373 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 pipeline.
399 @vals = $ar->pipeline_ex( # ( "a_a", "b_b", "c_c" )
401 [ "set", 0 => "a_a" ],
402 [ "set", 1 => "b_b" ],
403 [ "set", 2 => "c_c" ]
404 );
405 Current API available since 1.809.
407 pop
409 Removes and returns the last value of the list. If there are no
410 elements in the list, returns the undefined value.
411 $val = $ar->pop;
413 $val = pop @{$ar};
414 push ( value [, value, ... ] )
416 Appends one or multiple values to the tail of the list and returns the
417 new length.
418 $len = $ar->push( "val1", "val2" );
420 $len = push @{$ar}, "val1", "val2";
421 set ( index, value )
423 Sets the value of the given array index and returns its new value.
424 $val = $ar->set( 2, "value" );
426 $val = $ar->[ 2 ] = "value";
427 shift
429 Removes and returns the first value of the list. If there are no
430 elements in the list, returns the undefined value.
431 $val = $ar->shift;
433 $val = shift @{$ar};
434 range ( start, stop )
436 Returns the specified elements of the list. The offsets "start" and
437 "stop" can also be negative numbers indicating offsets starting at the
438 end of the list.
439 An empty list is returned if "start" is larger than the end of the
441 list. "stop" is set to the last index of the list if larger than the
442 actual end of the list.
443 @list = $ar->range( 20, 29 );
445 @list = $ar->range( -4, -1 );
446 sort ( "BY val [ ASC | DESC ] [ ALPHA ]" )
448 Returns sorted values in list context, leaving the elements intact. In
449 void context, sorts the list in-place. By default, sorting is numeric
450 when no arguments are given. The "BY val" modifier is optional and may
451 be omitted.
452 @vals = $ar->sort( "BY val" );
454 $ar->sort();
456 If the list contains string values and you want to sort them
458 lexicographically, specify the "ALPHA" modifier.
459 @vals = $ar->sort( "BY val ALPHA" );
461 $ar->sort( "ALPHA" );
463 The default is "ASC" for sorting the list from small to large. In order
465 to sort the list from large to small, specify the "DESC" modifier.
466 @vals = $ar->sort( "DESC ALPHA" );
468 $ar->sort( "DESC ALPHA" );
470 splice ( offset [, length [, list ] ] )
472 Removes the elements designated by "offset" and "length" from the
473 array, and replaces them with the elements of "list", if any. The
474 behavior is similar to the Perl "splice" function.
475 @items = $ar->splice( 20, 2, @list );
477 @items = $ar->splice( 20, 2 );
478 @items = $ar->splice( 20 );
479 unshift ( value [, value, ... ] )
481 Prepends one or multiple values to the head of the list and returns the
482 new length.
483 $len = $ar->unshift( "val1", "val2" );
485 $len = unshift @{$ar}, "val1", "val2";
486 values ( index [, index, ... ] )
488 Returns all values in the array when no arguments are given. Otherwise,
489 returns values for the given indices in the same order. Indices that do
490 not exist will have the "undef" value. In scalar context, returns the
491 size of the array.
492 @vals = $ar->values( 0, 1 );
494 @vals = $ar->values; # faster
496 @vals = values @{$ar}; # involves TIE overhead
497 $len = $ar->values; # ditto
499 $len = values @{$ar};
500 values ( "query string" )
502 Returns only values that match the given criteria. It returns an empty
503 list if the search found nothing. The syntax for the "query string" is
504 described above. In scalar context, returns the size of the resulting
505 list.
506 @keys = $ar->values( "val eq some_value" );
508 @keys = $ar->values( "key >= 50 :AND val =~ /sun|moon|air|wind/" );
509 @keys = $ar->values( "val eq sun :OR val eq moon :OR val eq foo" );
510 $len = $ar->values( "key =~ /$pattern/" );
511 vals
513 "vals" is an alias for "values".
514
516 This module is equipped with sugar methods to not have to call "set"
517 and "get" explicitly. In shared context, the benefit is atomicity and
518 reduction in inter-process communication.
519 The API resembles a subset of the Redis primitives
521 <https://redis.io/commands#strings> with key representing the array
522 index.
523 append ( key, string )
525 Appends a value to a key and returns its new length.
526 $len = $ar->append( 0, "foo" );
528 decr ( key )
530 Decrements the value of a key by one and returns its new value.
531 $num = $ar->decr( 0 );
533 decrby ( key, number )
535 Decrements the value of a key by the given number and returns its new
536 value.
537 $num = $ar->decrby( 0, 2 );
539 getdecr ( key )
541 Decrements the value of a key by one and returns its old value.
542 $old = $ar->getdecr( 0 );
544 getincr ( key )
546 Increments the value of a key by one and returns its old value.
547 $old = $ar->getincr( 0 );
549 getset ( key, value )
551 Sets the value of a key and returns its old value.
552 $old = $ar->getset( 0, "baz" );
554 incr ( key )
556 Increments the value of a key by one and returns its new value.
557 $num = $ar->incr( 0 );
559 incrby ( key, number )
561 Increments the value of a key by the given number and returns its new
562 value.
563 $num = $ar->incrby( 0, 2 );
565
567 The implementation is inspired by Tie::StdArray.
568
570 MCE, MCE::Hobo, MCE::Shared
571
573 Mario E. Roy, <marioeroy AT gmail DOT com>
574perl v5.36.0 2023-01-20 MCE::Shared::Array(3)