NAME

MCE::Shared::Array - Array helper class

VERSION

This document describes MCE::Shared::Array version 1.876

DESCRIPTION

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

SYNOPSIS

 # non-shared or local construction for use by a single process

 use MCE::Shared::Array;

 my $ar = MCE::Shared::Array->new( @list );

 # construction for sharing with other threads and processes

 use MCE::Shared;

 my $ar = MCE::Shared->array( @list );

 # array-like dereferencing

 my $val = $ar->[$index];
 $ar->[$index] = $val;

 @{$ar} = ();

 # OO interface

 $val   = $ar->set( $index, $val );
 $val   = $ar->get( $index);
 $val   = $ar->delete( $index );            # del is an alias for delete
 $bool  = $ar->exists( $index );
 void   = $ar->clear();
 $len   = $ar->len();                       # scalar @{ $ar }
 $len   = $ar->len( $index );               # length $ar->[ $index ]
 $val   = $ar->pop();
 $len   = $ar->push( @list );
 $val   = $ar->shift();
 $len   = $ar->unshift( @list );
 @list  = $ar->splice( $offset, $length, @list );

 $ar2   = $ar->clone( @indices );           # @indices is optional
 $ar3   = $ar->flush( @indices );
 $iter  = $ar->iterator( @indices );        # ($idx, $val) = $iter->()
 @keys  = $ar->keys( @indices );
 %pairs = $ar->pairs( @indices );
 @vals  = $ar->values( @indices );          # vals is an alias for values

 $len   = $ar->assign( $idx/$val pairs );   # equivalent to ->clear, ->push
 $cnt   = $ar->mdel( @indices );
 @vals  = $ar->mget( @indices );
 $bool  = $ar->mexists( @indices );         # true if all indices exists
 $len   = $ar->mset( $idx/$val pairs );     # merge is an alias for mset

 @vals  = $ar->range( $start, $stop );

 @vals  = $ar->sort();                      # $a <=> $b default
 @vals  = $ar->sort( "desc" );              # $b <=> $a
 @vals  = $ar->sort( "alpha" );             # $a cmp $b
 @vals  = $ar->sort( "alpha desc" );        # $b cmp $a

 # included, sugar methods without having to call set/get explicitly

 $len   = $ar->append( $index, $string );   #   $val .= $string
 $val   = $ar->decr( $index );              # --$val
 $val   = $ar->decrby( $index, $number );   #   $val -= $number
 $val   = $ar->getdecr( $index );           #   $val--
 $val   = $ar->getincr( $index );           #   $val++
 $val   = $ar->incr( $index );              # ++$val
 $val   = $ar->incrby( $index, $number );   #   $val += $number
 $old   = $ar->getset( $index, $new );      #   $o = $v, $v = $n, $o

 # pipeline, provides atomicity for shared objects, MCE::Shared v1.09+

 @vals  = $ar->pipeline(                    # ( "a_a", "b_b", "c_c" )
    [ "set", 0 => "a_a" ],
    [ "set", 1 => "b_b" ],
    [ "set", 2 => "c_c" ],
    [ "mget", qw/ 0 1 2 / ]
 );

For normal array behavior, the TIE interface is supported.

 # non-shared or local construction for use by a single process

 use MCE::Shared::Array;

 tie my @ar, "MCE::Shared::Array";

 # construction for sharing with other threads and processes

 use MCE::Shared;

 tie my @ar, "MCE::Shared";

 # usage

 my $val;

 if ( !defined ( $val = $ar[some_index] ) ) {
    $val = $ar[some_index] = "some_value";
 }

 $ar[some_index] = 0;

 tied(@ar)->incrby("some_index", 20);
 tied(@ar)->incrby(some_index => 20);

SYNTAX for QUERY STRING

Several methods take a query string for an argument. The format of the string is described below. In the context of sharing, the query mechanism is beneficial for the shared-manager process. It is able to perform the query where the data resides versus the client-process grep locally involving lots of IPC.

 o Basic demonstration

   @keys = $ar->keys( "query string given here" );
   @keys = $ar->keys( "val =~ /pattern/" );

 o Supported operators: =~ !~ eq ne lt le gt ge == != < <= > >=
 o Multiple expressions delimited by :AND or :OR, mixed case allowed

   "key == 3 :or (val > 5 :and val < 9)"
   "key =~ /pattern/i :And val =~ /pattern/i"
   "val eq foo baz :OR key !~ /pattern/i"

   * key matches on indices in the array
   * likewise, val matches on values

 o Quoting is optional inside the string

   "key =~ /pattern/i :AND val eq 'foo bar'"   # val eq "foo bar"
   "key =~ /pattern/i :AND val eq foo bar"     # val eq "foo bar"

Examples.

 # search capability key/val: =~ !~ eq ne lt le gt ge == != < <= > >=
 # key/val means to match against actual key/val respectively

 @keys  = $ar->keys( "key == 3 :or (val > 5 :and val < 9)" );

 @keys  = $ar->keys( "key =~ /$pattern/i" );
 @keys  = $ar->keys( "key !~ /$pattern/i" );
 @keys  = $ar->keys( "val =~ /$pattern/i" );
 @keys  = $ar->keys( "val !~ /$pattern/i" );

 %pairs = $ar->pairs( "key == $number" );
 %pairs = $ar->pairs( "key != $number :and val > 100" );
 %pairs = $ar->pairs( "key <  $number :or key > $number" );
 %pairs = $ar->pairs( "val <= $number" );
 %pairs = $ar->pairs( "val >  $number" );
 %pairs = $ar->pairs( "val >= $number" );

 @vals  = $ar->vals( "key eq $string" );
 @vals  = $ar->vals( "key ne $string with space" );
 @vals  = $ar->vals( "key lt $string :or val =~ /$pat1|$pat2/" );
 @vals  = $ar->vals( "val le $string :and val eq 'foo bar'" );
 @vals  = $ar->vals( "val le $string :and val eq foo bar" );
 @vals  = $ar->vals( "val gt $string" );
 @vals  = $ar->vals( "val ge $string" );

API DOCUMENTATION

This module may involve TIE when accessing the object via array-like behavior. Only shared instances are impacted if doing so. Although likely fast enough for many use cases, the OO interface is recommended for best performance.

MCE::Shared::Array->new ( val [, val, ... ] )

MCE::Shared->array ( val [, val, ... ] )

Constructs a new object, with an optional list of values.

 # non-shared or local construction for use by a single process

 use MCE::Shared::Array;

 $ar = MCE::Shared::Array->new( @list );
 $ar = MCE::Shared::Array->new( );

 # construction for sharing with other threads and processes

 use MCE::Shared;

 $ar = MCE::Shared->array( @list );
 $ar = MCE::Shared->array( );

assign ( value [, value, ... ] )

Clears the list, then appends one or multiple values and returns the new length. This is equivalent to "clear", "push".

 $len = $ar->assign( "val1", "val2" );
 $len = @{$ar} = ( "val1", "val2" );

API available since 1.007.

clear

Removes all elements from the array.

 $ar->clear;
 @{$ar} = ();

clone ( index [, index, ... ] )

Creates a shallow copy, a "MCE::Shared::Array" object. It returns an exact copy if no arguments are given. Otherwise, the object includes only the given indices in the same order. Indices that do not exist in the array will have the "undef" value.

 $ar2 = $ar->clone( 0, 1 );
 $ar2 = $ar->clone;

delete ( index )

Deletes and returns the value associated by index or "undef" if index exceeds the size of the list.

 $val = $ar->delete( 20 );
 $val = delete $ar->[ 20 ];

del

"del" is an alias for "delete".

exists ( index )

Determines if an element by its index exists in the array. The behavior is strongly tied to the use of delete on lists.

 $ar->push(qw/ value0 value1 value2 value3 /);

 $ar->exists( 2 );   # True
 $ar->delete( 2 );   # value2
 $ar->exists( 2 );   # False

 $ar->exists( 3 );   # True
 exists $ar->[ 3 ];  # True

flush ( index [, index, ... ] )

Same as "clone". Though, clears all existing items before returning.

get ( index )

Gets the value of an element by its index or "undef" if the index does not exists.

 $val = $ar->get( 2 );
 $val = $ar->[ 2 ];

iterator ( index [, index, ... ] )

Returns a code reference for iterating a list of index-value pairs stored in the array when no arguments are given. Otherwise, returns a code reference for iterating the given indices in the same order. Indices that do not exist will have the "undef" value.

The list of indices to return is set when the closure is constructed. New indices added later are not included. Subsequently, the "undef" value is returned for deleted indices.

 $iter = $ar->iterator;
 $iter = $ar->iterator( 0, 1 );

 while ( my ( $index, $val ) = $iter->() ) {
    ...
 }

iterator ( "query string" )

Returns a code reference for iterating a list of index-value pairs that match the given criteria. It returns an empty list if the search found nothing. The syntax for the "query string" is described above.

 $iter = $ar->iterator( "val eq some_value" );
 $iter = $ar->iterator( "key >= 50 :AND val =~ /sun|moon|air|wind/" );
 $iter = $ar->iterator( "val eq sun :OR val eq moon :OR val eq foo" );
 $iter = $ar->iterator( "key =~ /$pattern/" );

 while ( my ( $index, $val ) = $iter->() ) {
    ...
 }

keys ( index [, index, ... ] )

Returns all indices in the array when no arguments are given. Otherwise, returns the given indices in the same order. Indices that do not exist will have the "undef" value. In scalar context, returns the size of the array.

 @keys = $ar->keys( 0, 1 );

 @keys = $ar->keys;     # faster
 @keys = keys @{$ar};   # involves TIE overhead

 $len  = $ar->keys;     # ditto
 $len  = keys @{$ar};

keys ( "query string" )

Returns only indices that match the given criteria. It returns an empty list if the search found nothing. The syntax for the "query string" is described above. In scalar context, returns the size of the resulting list.

 @keys = $ar->keys( "val eq some_value" );
 @keys = $ar->keys( "key >= 50 :AND val =~ /sun|moon|air|wind/" );
 @keys = $ar->keys( "val eq sun :OR val eq moon :OR val eq foo" );
 $len  = $ar->keys( "key =~ /$pattern/" );

len ( index )

Returns the size of the array when no arguments are given. For the given index, returns the length of the value stored at index or the "undef" value if the index does not exists.

 $len = $ar->len;
 $len = $ar->len( 0 );
 $len = length $ar->[ 0 ];

mdel ( index [, index, ... ] )

Deletes one or more elements by its index and returns the number of indices deleted. A given index which does not exist in the list is not counted.

 $cnt = $ar->mdel( 0, 1 );

mexists ( index [, index, ... ] )

Returns a true value if all given indices exists in the list. A false value is returned otherwise.

 if ( $ar->mexists( 0, 1 ) ) { ... }

mget ( index [, index, ... ] )

Gets multiple values from the list by its index. It returns "undef" for indices which do not exists in the list.

 ( $val1, $val2 ) = $ar->mget( 0, 1 );

mset ( index, value [, index, value, ... ] )

Sets multiple index-value pairs in the list and returns the length of the list.

 $len = $ar->mset( 0 => "val1", 1 => "val2" );

merge

"merge" is an alias for "mset".

pairs ( index [, index, ... ] )

Returns index-value pairs in the array when no arguments are given. Otherwise, returns index-value pairs for the given indices in the same order. Indices that do not exist will have the "undef" value. In scalar context, returns the size of the array.

 @pairs = $ar->pairs( 0, 1 );

 @pairs = $ar->pairs;
 $len   = $ar->pairs;

pairs ( "query string" )

Returns only index-value pairs that match the given criteria. It returns an empty list if the search found nothing. The syntax for the "query string" is described above. In scalar context, returns the size of the resulting list.

 @pairs = $ar->pairs( "val eq some_value" );
 @pairs = $ar->pairs( "key >= 50 :AND val =~ /sun|moon|air|wind/" );
 @pairs = $ar->pairs( "val eq sun :OR val eq moon :OR val eq foo" );
 $len   = $ar->pairs( "key =~ /$pattern/" );

pipeline ( [ func1, @args ], [ func2, @args ], ... )

Combines multiple commands for the object to be processed serially. For shared objects, the call is made atomically due to single IPC to the shared-manager process. The "pipeline" method is fully "wantarray"-aware and receives a list of commands and their arguments. In scalar or list context, it returns data from the last command in the pipeline.

 @vals = $ar->pipeline(                     # ( "a_a", "b_b", "c_c" )
    [ "set", 0 => "a_a" ],
    [ "set", 1 => "b_b" ],
    [ "set", 2 => "c_c" ],
    [ "mget", qw/ 0 1 2 / ]
 );

 $len = $ar->pipeline(                      # 3, same as $ar->len
    [ "set", 0 => "i_i" ],
    [ "set", 1 => "j_j" ],
    [ "set", 2 => "k_k" ],
    [ "len" ]
 );

 $ar->pipeline(
    [ "set", 0 => "m_m" ],
    [ "set", 1 => "n_n" ],
    [ "set", 2 => "o_o" ]
 );

Current API available since 1.809.

pipeline_ex ( [ func1, @args ], [ func2, @args ], ... )

Same as "pipeline", but returns data for every command in the pipeline.

 @vals = $ar->pipeline_ex(                  # ( "a_a", "b_b", "c_c" )
    [ "set", 0 => "a_a" ],
    [ "set", 1 => "b_b" ],
    [ "set", 2 => "c_c" ]
 );

Current API available since 1.809.

pop

Removes and returns the last value of the list. If there are no elements in the list, returns the undefined value.

 $val = $ar->pop;
 $val = pop @{$ar};

push ( value [, value, ... ] )

Appends one or multiple values to the tail of the list and returns the new length.

 $len = $ar->push( "val1", "val2" );
 $len = push @{$ar}, "val1", "val2";

set ( index, value )

Sets the value of the given array index and returns its new value.

 $val = $ar->set( 2, "value" );
 $val = $ar->[ 2 ] = "value";

shift

Removes and returns the first value of the list. If there are no elements in the list, returns the undefined value.

 $val = $ar->shift;
 $val = shift @{$ar};

range ( start, stop )

Returns the specified elements of the list. The offsets "start" and "stop" can also be negative numbers indicating offsets starting at the end of the list.

An empty list is returned if "start" is larger than the end of the list. "stop" is set to the last index of the list if larger than the actual end of the list.

 @list = $ar->range( 20, 29 );
 @list = $ar->range( -4, -1 );

sort ( "BY val [ ASC | DESC ] [ ALPHA ]" )

Returns sorted values in list context, leaving the elements intact. In void context, sorts the list in-place. By default, sorting is numeric when no arguments are given. The "BY val" modifier is optional and may be omitted.

 @vals = $ar->sort( "BY val" );

 $ar->sort();

If the list contains string values and you want to sort them lexicographically, specify the "ALPHA" modifier.

 @vals = $ar->sort( "BY val ALPHA" );

 $ar->sort( "ALPHA" );

The default is "ASC" for sorting the list from small to large. In order to sort the list from large to small, specify the "DESC" modifier.

 @vals = $ar->sort( "DESC ALPHA" );

 $ar->sort( "DESC ALPHA" );

splice ( offset [, length [, list ] ] )

Removes the elements designated by "offset" and "length" from the array, and replaces them with the elements of "list", if any. The behavior is similar to the Perl "splice" function.

 @items = $ar->splice( 20, 2, @list );
 @items = $ar->splice( 20, 2 );
 @items = $ar->splice( 20 );

unshift ( value [, value, ... ] )

Prepends one or multiple values to the head of the list and returns the new length.

 $len = $ar->unshift( "val1", "val2" );
 $len = unshift @{$ar}, "val1", "val2";

values ( index [, index, ... ] )

Returns all values in the array when no arguments are given. Otherwise, returns values for the given indices in the same order. Indices that do not exist will have the "undef" value. In scalar context, returns the size of the array.

 @vals = $ar->values( 0, 1 );

 @vals = $ar->values;     # faster
 @vals = values @{$ar};   # involves TIE overhead

 $len  = $ar->values;     # ditto
 $len  = values @{$ar};

values ( "query string" )

Returns only values that match the given criteria. It returns an empty list if the search found nothing. The syntax for the "query string" is described above. In scalar context, returns the size of the resulting list.

 @keys = $ar->values( "val eq some_value" );
 @keys = $ar->values( "key >= 50 :AND val =~ /sun|moon|air|wind/" );
 @keys = $ar->values( "val eq sun :OR val eq moon :OR val eq foo" );
 $len  = $ar->values( "key =~ /$pattern/" );

vals

"vals" is an alias for "values".

SUGAR METHODS

This module is equipped with sugar methods to not have to call "set" and "get" explicitly. In shared context, the benefit is atomicity and reduction in inter-process communication.

The API resembles a subset of the Redis primitives <http://redis.io/commands#strings> with key representing the array index.