1MCE::Shared::Array(3) User Contributed Perl DocumentationMCE::Shared::Array(3)
2
3
4
6 MCE::Shared::Array - Array helper class
7
9 This document describes MCE::Shared::Array version 1.864
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
18 use MCE::Shared::Array;
19
20 my $ar = MCE::Shared::Array->new( @list );
21
22 # construction for sharing with other threads and processes
23
24 use MCE::Shared;
25
26 my $ar = MCE::Shared->array( @list );
27
28 # array-like dereferencing
29
30 my $val = $ar->[$index];
31 $ar->[$index] = $val;
32
33 @{$ar} = ();
34
35 # OO interface
36
37 $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
50 $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
57 $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
63 @vals = $ar->range( $start, $stop );
64
65 @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
70 # included, sugar methods without having to call set/get explicitly
71
72 $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
81 # pipeline, provides atomicity for shared objects, MCE::Shared v1.09+
82
83 @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
90 For normal array behavior, the TIE interface is supported.
91
92 # non-shared or local construction for use by a single process
93
94 use MCE::Shared::Array;
95
96 tie my @ar, "MCE::Shared::Array";
97
98 # construction for sharing with other threads and processes
99
100 use MCE::Shared;
101
102 tie my @ar, "MCE::Shared";
103
104 # usage
105
106 my $val;
107
108 if ( !defined ( $val = $ar[some_index] ) ) {
109 $val = $ar[some_index] = "some_value";
110 }
111
112 $ar[some_index] = 0;
113
114 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
124 o Basic demonstration
125
126 @keys = $ar->keys( "query string given here" );
127 @keys = $ar->keys( "val =~ /pattern/" );
128
129 o Supported operators: =~ !~ eq ne lt le gt ge == != < <= > >=
130 o Multiple expressions delimited by :AND or :OR, mixed case allowed
131
132 "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
136 * key matches on indices in the array
137 * likewise, val matches on values
138
139 o Quoting is optional inside the string
140
141 "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
144 Examples.
145
146 # search capability key/val: =~ !~ eq ne lt le gt ge == != < <= > >=
147 # key/val means to match against actual key/val respectively
148
149 @keys = $ar->keys( "key == 3 :or (val > 5 :and val < 9)" );
150
151 @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
156 %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
163 @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
177 MCE::Shared::Array->new ( val [, val, ... ] )
178 MCE::Shared->array ( val [, val, ... ] )
179 Constructs a new object, with an optional list of values.
180
181 # non-shared or local construction for use by a single process
182
183 use MCE::Shared::Array;
184
185 $ar = MCE::Shared::Array->new( @list );
186 $ar = MCE::Shared::Array->new( );
187
188 # construction for sharing with other threads and processes
189
190 use MCE::Shared;
191
192 $ar = MCE::Shared->array( @list );
193 $ar = MCE::Shared->array( );
194
195 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
199 $len = $ar->assign( "val1", "val2" );
200 $len = @{$ar} = ( "val1", "val2" );
201
202 API available since 1.007.
203
204 clear
205 Removes all elements from the array.
206
207 $ar->clear;
208 @{$ar} = ();
209
210 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
216 $ar2 = $ar->clone( 0, 1 );
217 $ar2 = $ar->clone;
218
219 delete ( index )
220 Deletes and returns the value associated by index or "undef" if index
221 exceeds the size of the list.
222
223 $val = $ar->delete( 20 );
224 $val = delete $ar->[ 20 ];
225
226 del
227 "del" is an alias for "delete".
228
229 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
233 $ar->push(qw/ value0 value1 value2 value3 /);
234
235 $ar->exists( 2 ); # True
236 $ar->delete( 2 ); # value2
237 $ar->exists( 2 ); # False
238
239 $ar->exists( 3 ); # True
240 exists $ar->[ 3 ]; # True
241
242 flush ( index [, index, ... ] )
243 Same as "clone". Though, clears all existing items before returning.
244
245 get ( index )
246 Gets the value of an element by its index or "undef" if the index does
247 not exists.
248
249 $val = $ar->get( 2 );
250 $val = $ar->[ 2 ];
251
252 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
258 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
262 $iter = $ar->iterator;
263 $iter = $ar->iterator( 0, 1 );
264
265 while ( my ( $index, $val ) = $iter->() ) {
266 ...
267 }
268
269 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
274 $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
279 while ( my ( $index, $val ) = $iter->() ) {
280 ...
281 }
282
283 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
289 @keys = $ar->keys( 0, 1 );
290
291 @keys = $ar->keys; # faster
292 @keys = keys @{$ar}; # involves TIE overhead
293
294 $len = $ar->keys; # ditto
295 $len = keys @{$ar};
296
297 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
303 @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
308 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
313 $len = $ar->len;
314 $len = $ar->len( 0 );
315 $len = length $ar->[ 0 ];
316
317 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
322 $cnt = $ar->mdel( 0, 1 );
323
324 mexists ( index [, index, ... ] )
325 Returns a true value if all given indices exists in the list. A false
326 value is returned otherwise.
327
328 if ( $ar->mexists( 0, 1 ) ) { ... }
329
330 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
334 ( $val1, $val2 ) = $ar->mget( 0, 1 );
335
336 mset ( index, value [, index, value, ... ] )
337 Sets multiple index-value pairs in the list and returns the length of
338 the list.
339
340 $len = $ar->mset( 0 => "val1", 1 => "val2" );
341
342 merge
343 "merge" is an alias for "mset".
344
345 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
351 @pairs = $ar->pairs( 0, 1 );
352
353 @pairs = $ar->pairs;
354 $len = $ar->pairs;
355
356 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
362 @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
367 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
375 @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
382 $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
389 $ar->pipeline(
390 [ "set", 0 => "m_m" ],
391 [ "set", 1 => "n_n" ],
392 [ "set", 2 => "o_o" ]
393 );
394
395 Current API available since 1.809.
396
397 pipeline_ex ( [ func1, @args ], [ func2, @args ], ... )
398 Same as "pipeline", but returns data for every command in the pipeline.
399
400 @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
406 Current API available since 1.809.
407
408 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
412 $val = $ar->pop;
413 $val = pop @{$ar};
414
415 push ( value [, value, ... ] )
416 Appends one or multiple values to the tail of the list and returns the
417 new length.
418
419 $len = $ar->push( "val1", "val2" );
420 $len = push @{$ar}, "val1", "val2";
421
422 set ( index, value )
423 Sets the value of the given array index and returns its new value.
424
425 $val = $ar->set( 2, "value" );
426 $val = $ar->[ 2 ] = "value";
427
428 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
432 $val = $ar->shift;
433 $val = shift @{$ar};
434
435 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
440 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
444 @list = $ar->range( 20, 29 );
445 @list = $ar->range( -4, -1 );
446
447 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
453 @vals = $ar->sort( "BY val" );
454
455 $ar->sort();
456
457 If the list contains string values and you want to sort them
458 lexicographically, specify the "ALPHA" modifier.
459
460 @vals = $ar->sort( "BY val ALPHA" );
461
462 $ar->sort( "ALPHA" );
463
464 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
467 @vals = $ar->sort( "DESC ALPHA" );
468
469 $ar->sort( "DESC ALPHA" );
470
471 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
476 @items = $ar->splice( 20, 2, @list );
477 @items = $ar->splice( 20, 2 );
478 @items = $ar->splice( 20 );
479
480 unshift ( value [, value, ... ] )
481 Prepends one or multiple values to the head of the list and returns the
482 new length.
483
484 $len = $ar->unshift( "val1", "val2" );
485 $len = unshift @{$ar}, "val1", "val2";
486
487 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
493 @vals = $ar->values( 0, 1 );
494
495 @vals = $ar->values; # faster
496 @vals = values @{$ar}; # involves TIE overhead
497
498 $len = $ar->values; # ditto
499 $len = values @{$ar};
500
501 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
507 @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
512 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
520 The API resembles a subset of the Redis primitives
521 <http://redis.io/commands#strings> with key representing the array
522 index.
523
524 append ( key, string )
525 Appends a value to a key and returns its new length.
526
527 $len = $ar->append( 0, "foo" );
528
529 decr ( key )
530 Decrements the value of a key by one and returns its new value.
531
532 $num = $ar->decr( 0 );
533
534 decrby ( key, number )
535 Decrements the value of a key by the given number and returns its new
536 value.
537
538 $num = $ar->decrby( 0, 2 );
539
540 getdecr ( key )
541 Decrements the value of a key by one and returns its old value.
542
543 $old = $ar->getdecr( 0 );
544
545 getincr ( key )
546 Increments the value of a key by one and returns its old value.
547
548 $old = $ar->getincr( 0 );
549
550 getset ( key, value )
551 Sets the value of a key and returns its old value.
552
553 $old = $ar->getset( 0, "baz" );
554
555 incr ( key )
556 Increments the value of a key by one and returns its new value.
557
558 $num = $ar->incr( 0 );
559
560 incrby ( key, number )
561 Increments the value of a key by the given number and returns its new
562 value.
563
564 $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>
574
575
576
577perl v5.30.1 2020-01-30 MCE::Shared::Array(3)