MCE::Shared::Scalar(3)

NAME
MCE::Shared::Scalar - Scalar helper class

VERSION
This document describes MCE::Shared::Scalar version 1.893

DESCRIPTION
A scalar 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::Scalar;

 my $var = MCE::Shared::Scalar->new( $val );

 # construction for sharing with other threads and processes

 use MCE::Shared;

 my $var = MCE::Shared->scalar( $val );

 # scalar-like dereferencing

 my $val = ${ $var };
 ${ $var } = $val;

 # OO interface

 $val = $var->set( $val );
 $val = $var->get();
 $len = $var->len();

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

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

For normal scalar behavior, the TIE interface is supported.

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

 use MCE::Shared::Scalar;

 tie my $var, "MCE::Shared::Scalar";

 # construction for sharing with other threads and processes

 use MCE::Shared;

 tie my $var, "MCE::Shared";

 # usage

 $var = 0;

 tied($var)->incrby(20);

API DOCUMENTATION
This module may involve TIE when accessing the object via scalar dereferencing. 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::Scalar->new ( [ value ] )

  MCE::Shared->scalar ( [ value ] )
Constructs a new object. Its value is undefined when "value" is not specified.

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

 use MCE::Shared::Scalar;

 $var = MCE::Shared::Scalar->new( "foo" );
 $var = MCE::Shared::Scalar->new;

 # construction for sharing with other threads and processes

 use MCE::Shared;

 $var = MCE::Shared->scalar( "bar" );
 $var = MCE::Shared->scalar;

  set ( value )
Preferably, set the value via the OO interface. Otherwise, "TIE" is activated on-demand for setting the value. The new value is returned in scalar context.

 $val = $var->set( "baz" );
 $var->set( "baz" );
 ${$var} = "baz";

  get
Likewise, obtain the value via the OO interface. "TIE" is utilized for retrieving the value otherwise.

 $val = $var->get;
 $val = ${$var};

  len
Returns the length of the value. It returns the "undef" value if the value is not defined.

 $len = $var->len;
 length ${$var};

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 <https://redis.io/commands#strings> without the key argument.

  append ( value )
Appends a value at the end of the current value and returns its new length.

 $len = $var->append( "foo" );

  decr
Decrements the value by one and returns its new value.

 $num = $var->decr;

  decrby ( number )
Decrements the value by the given number and returns its new value.

 $num = $var->decrby( 2 );

  getdecr
Decrements the value by one and returns its old value.

 $old = $var->getdecr;

  getincr
Increments the value by one and returns its old value.

 $old = $var->getincr;

  getset ( value )
Sets the value and returns its old value.

 $old = $var->getset( "baz" );

  incr
Increments the value by one and returns its new value.

 $num = $var->incr;

  incrby ( number )
Increments the value by the given number and returns its new value.

 $num = $var->incrby( 2 );

CREDITS
The implementation is inspired by Tie::StdScalar.

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

AUTHOR
Mario E. Roy, <marioeroy AT gmail DOT com>