1MCE::Shared::Array(3) User Contributed Perl DocumentationMCE::Shared::Array(3)
2
3
4

NAME

6       MCE::Shared::Array - Array helper class
7

VERSION

9       This document describes MCE::Shared::Array version 1.880
10

DESCRIPTION

12       An array helper class for use as a standalone or managed by
13       MCE::Shared.
14

SYNOPSIS

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

SYNTAX for QUERY STRING

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

API DOCUMENTATION

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

SUGAR METHODS

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       <https://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

CREDITS

567       The implementation is inspired by Tie::StdArray.
568

INDEX

570       MCE, MCE::Hobo, MCE::Shared
571

AUTHOR

573       Mario E. Roy, <marioeroy AT gmail DOT com>
574
575
576
577perl v5.36.0                      2023-01-20             MCE::Shared::Array(3)
Impressum