Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MCE::Shared::Array(3) User Contributed Perl DocumentationMCE::Shared::Array(3)

NAME
       MCE::Shared::Array - Array helper class

VERSION
       This document describes MCE::Shared::Array version 1.873

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.

   append ( key, string	)
       Appends a value to a key	and returns its	new length.

	$len = $ar->append( 0, "foo" );

   decr	( key )
       Decrements the value of a key by	one and	returns	its new	value.

	$num = $ar->decr( 0 );

   decrby ( key, number	)
       Decrements the value of a key by	the given number and returns its new
       value.

	$num = $ar->decrby( 0, 2 );

   getdecr ( key )
       Decrements the value of a key by	one and	returns	its old	value.

	$old = $ar->getdecr( 0 );

   getincr ( key )
       Increments the value of a key by	one and	returns	its old	value.

	$old = $ar->getincr( 0 );

   getset ( key, value )
       Sets the	value of a key and returns its old value.

	$old = $ar->getset( 0, "baz" );

   incr	( key )
       Increments the value of a key by	one and	returns	its new	value.

	$num = $ar->incr( 0 );

   incrby ( key, number	)
       Increments the value of a key by	the given number and returns its new
       value.

	$num = $ar->incrby( 0, 2 );

CREDITS
       The implementation is inspired by Tie::StdArray.

INDEX
       MCE, MCE::Hobo, MCE::Shared

AUTHOR
       Mario E.	Roy, <marioeroyA ATA gmailA DOTA com>

perl v5.32.0			  2020-08-01		 MCE::Shared::Array(3)

NAME | VERSION | DESCRIPTION | SYNOPSIS | SYNTAX for QUERY STRING | API DOCUMENTATION | SUGAR METHODS | CREDITS | INDEX | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MCE::Shared::Array&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help