MCE::Shared::Hash(3)

📦

version 1.893 · 4 versions

🌸 NAME 🌸

okay so we're on the MCE::Shared::Hash(3) page from User Contributed Perl Documentation, and the name sitch is MCE::Shared::Hash - Hash helper class 🎀. that's the whole label, bestie.

✨ VERSION ✨

this doc is describing MCE::Shared::Hash version 1.893 — noted, slay 💅.

💖 DESCRIPTION 💖

it's a hash helper class, fr fr. use it standalone, or let MCE::Shared manage it 🦋.

🎀 SYNOPSIS 🎀

okay so here's the whole construction vibe. first up, non-shared/local for one single process, then sharing with other threads and processes:

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

        use MCE::Shared::Hash;

        my $ha = MCE::Shared::Hash->new( @pairs );

        # construction for sharing with other threads and processes

        use MCE::Shared;

        my $ha = MCE::Shared->hash( @pairs );

        # hash-like dereferencing

        my $val = $ha->{$key};
        $ha->{$key} = $val;

        %{$ha} = ();

        # OO interface

        if ( !defined ( $val = $ha->get("some_key") ) ) {
           $val = $ha->set( some_key => "some_value" );
        }

        $val   = $ha->set( $key, $val );
        $ret   = $ha->setnx( $key, $val );         # set only if the key exists
        $val   = $ha->get( $key );
        $val   = $ha->delete( $key );              # del is an alias for delete
        $bool  = $ha->exists( $key );
        void   = $ha->clear();
        $len   = $ha->len();                       # scalar keys %{ $ha }
        $len   = $ha->len( $key );                 # length $ha->{ $key }

        $ha2   = $ha->clone( @keys );              # @keys is optional
        $ha3   = $ha->flush( @keys );
        $iter  = $ha->iterator( @keys );           # ($key, $val) = $iter->()
        @keys  = $ha->keys( @keys );
        %pairs = $ha->pairs( @keys );
        @vals  = $ha->values( @keys );             # vals is an alias for values

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

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

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

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

        @vals  = $ha->pipeline(                    # ( "a_a", "b_b", "c_c" )
           [ "set", foo => "a_a" ],
           [ "set", bar => "b_b" ],
           [ "set", baz => "c_c" ],
           [ "mget", qw/ foo bar baz / ]
        );

for normal hash behavior, the TIE interface is supported 👑:

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

        use MCE::Shared::Hash;

        tie my %ha, "MCE::Shared::Hash";

        # construction for sharing with other threads and processes

        use MCE::Shared;

        tie my %ha, "MCE::Shared";

        # usage

        my $val;

        if ( !defined ( $val = $ha{some_key} ) ) {
           $val = $ha{some_key} = "some_value";
        }

        $ha{some_key} = 0;

        tied(%ha)->incrby("some_key", 20);
        tied(%ha)->incrby(some_key => 20);

🌈 SYNTAX for QUERY STRING 🌈

several methods take a query string as an argument, and the format is described below 💖. in the context of sharing, this query mechanism is beneficial for the shared-manager process — it can perform the query where the data actually resides, instead of the client-process grep happening locally with lots of IPC 😭. iykyk.

Basic demonstration ✨

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

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

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

key matches on keys in the hash 🔑
likewise, val matches on values 💎
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, bestie — search capability is key/val with =~ !~ eq ne lt le gt ge == != < <= > >=, and key/val means to match against actual key/val respectively 🌸:

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

@keys  = $ha->keys( "key eq 'some key' :or (val > 5 :and val < 9)" );
@keys  = $ha->keys( "key eq some key :or (val > 5 :and val < 9)" );

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

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

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

✨ API DOCUMENTATION ✨

Okay bestie, real talk: this module may involve TIE when you access the object via hash-like behavior. Only shared instances are impacted if you do that. It’s probably fast enough for lots of use cases, but the OO interface is highkey recommended for best performance. 💅

💖 `MCE::Shared::Hash->new ( key, value [, key, value, ... ] )` and `MCE::Shared->hash ( key, value [, key, value, ... ] )`

Constructs a new object, with an optional list of key-value pairs. Iconic.

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

use MCE::Shared::Hash;

$ha = MCE::Shared::Hash->new( @pairs );
$ha = MCE::Shared::Hash->new( );

# construction for sharing with other threads and processes

use MCE::Shared;

$ha = MCE::Shared->hash( @pairs );
$ha = MCE::Shared->hash( );

🎀 `assign ( key, value [, key, value, ... ] )`

Clears the hash, then sets multiple key-value pairs and returns the number of keys stored in the hash. This is equivalent to clear, mset.

$len = $ha->assign( "key1" => "val1", "key2" => "val2" );  # 2
$len = %{$ha} = ( "key1" => "val1", "key2" => "val2" );    # 4

API available since 1.007.

🧚 `clear`

Removes all key-value pairs from the hash. Poof, gone.

$ha->clear;
%{$ha} = ();

🦋 `clone ( key [, key, ... ] )`

Creates a shallow copy, a MCE::Shared::Hash object. It returns an exact copy if no arguments are given. Otherwise, the object includes only the given keys. Keys that do not exist in the hash will have the undef value.

$ha2 = $ha->clone( "key1", "key2" );
$ha2 = $ha->clone;

🌸 `delete ( key )`

Deletes and returns the value by given key or undef if the key does not exists in the hash. (Yes, the original says “exists” — we’re keeping it exactly, bestie.)

$val = $ha->delete( "some_key" );
$val = delete $ha->{ "some_key" };

💫 `del`

del is an alias for delete.

🍓 `exists ( key )`

Determines if a key exists in the hash.

if ( $ha->exists( "some_key" ) ) { ... }
if ( exists $ha->{ "some_key" } ) { ... }

🌈 `flush ( key [, key, ... ] )`

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

⭐ `get ( key )`

Gets the value of a hash key or undef if the key does not exists.

$val = $ha->get( "some_key" );
$val = $ha->{ "some_key" };

💜 `iterator ( key [, key, ... ] )`

Returns a code reference for iterating a list of key-value pairs stored in the hash when no arguments are given. Otherwise, returns a code reference for iterating the given keys in the same order. Keys that do not exist will have the undef value.

The list of keys to return is set when the closure is constructed. Later keys added to the hash are not included. Subsequently, the undef value is returned for deleted keys. No cap.

$iter = $ha->iterator;
$iter = $ha->iterator( "key1", "key2" );

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

🫶 `iterator ( "query string" )`

Returns a code reference for iterating a list of key-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 = $ha->iterator( "val eq some_value" );
$iter = $ha->iterator( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
$iter = $ha->iterator( "val eq sun :OR val eq moon :OR val eq foo" );
$iter = $ha->iterator( "key =~ /$pattern/" );

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

👑 `keys ( key [, key, ... ] )`

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

@keys = $ha->keys( "key1", "key2" );

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

$len  = $ha->keys;     # ditto
$len  = keys %{$ha};

✨ `keys ( "query string" )`

Returns only keys 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. Slay.

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

💅 `len ( key )`

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

$size = $ha->len;
$len  = $ha->len( "key1" );
$len  = length $ha->{ "key1" };

🔥 `mdel ( key [, key, ... ] )`

Deletes one or more keys in the hash and returns the number of keys deleted. A given key which does not exist in the hash is not counted.

$cnt = $ha->mdel( "key1", "key2" );

🌟 `mexists ( key [, key, ... ] )`

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

if ( $ha->mexists( "key1", "key2" ) ) { ... }

🧁 `mget ( key [, key, ... ] )`

Gets the values of all given keys. It returns undef for keys which do not exists in the hash.

( $val1, $val2 ) = $ha->mget( "key1", "key2" );

🎀 `mset ( key, value [, key, value, ... ] )`

Sets multiple key-value pairs in a hash and returns the number of keys stored in the hash.

$len = $ha->mset( "key1" => "val1", "key2" => "val2" );

🦋 `merge`

merge is an alias for mset.

🌸 `pairs ( key [, key, ... ] )`

Returns key-value pairs in the hash when no arguments are given. Otherwise, returns key-value pairs for the given keys in the same order. Keys that do not exist will have the undef value. In scalar context, returns the size of the hash.

@pairs = $ha->pairs( "key1", "key2" );

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

💖 `pairs ( "query string" )`

Returns only key-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 = $ha->pairs( "val eq some_value" );
@pairs = $ha->pairs( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
@pairs = $ha->pairs( "val eq sun :OR val eq moon :OR val eq foo" );
$len   = $ha->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 = $ha->pipeline(                     # ( "a_a", "b_b", "c_c" )
   [ "set", foo => "a_a" ],
   [ "set", bar => "b_b" ],
   [ "set", baz => "c_c" ],
   [ "mget", qw/ foo bar baz / ]
);

$len = $ha->pipeline(                      # 3, same as $ha->len
   [ "set", foo => "i_i" ],
   [ "set", bar => "j_j" ],
   [ "set", baz => "k_k" ],
   [ "len" ]
);

$ha->pipeline(
   [ "set", foo => "m_m" ],
   [ "set", bar => "n_n" ],
   [ "set", baz => "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 = $ha->pipeline_ex(                  # ( "a_a", "b_b", "c_c" )
   [ "set", foo => "a_a" ],
   [ "set", bar => "b_b" ],
   [ "set", baz => "c_c" ]
);

Current API available since 1.809.

⭐ `set ( key, value )`

Sets the value of the given hash key and returns its new value.

$val = $ha->set( "key", "value" );
$val = $ha->{ "key" } = "value";

🧚 `setnx ( key, value )`

Sets the value of a hash key, only if the key does not exist. Returns a 1 for new key or 0 if the key already exists and no operation was performed.

$ret = $ha->setnx( "key", "value" );

Current API available since 1.872.

🌈 `values ( key [, key, ... ] )`

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

@vals = $ha->values( "key1", "key2" );

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

$len  = $ha->values;     # ditto
$len  = values %{$ha};

💜 `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.

@vals = $ha->values( "val eq some_value" );
@vals = $ha->values( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
@vals = $ha->values( "val eq sun :OR val eq moon :OR val eq foo" );
$len  = $ha->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. Obsessed, honestly.

The API resembles a subset of the Redis primitives at https://redis.io/commands#strings with key representing the hash key. 💅

🌸 `append ( key, string )`

Appends a value to a key and returns its new length.

$len = $ha->append( $key, "foo" );

🦋 `decr ( key )`

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

$num = $ha->decr( $key );

💫 `decrby ( key, number )`

Decrements the value of a key by the given number and returns its new value.

$num = $ha->decrby( $key, 2 );

🎀 `getdecr ( key )`

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

$old = $ha->getdecr( $key );

⭐ `getincr ( key )`

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

$old = $ha->getincr( $key );

🧁 `getset ( key, value )`

Sets the value of a key and returns its old value.

$old = $ha->getset( $key, "baz" );

🔥 `incr ( key )`

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

$num = $ha->incr( $key );

👑 `incrby ( key, number )`

Increments the value of a key by the given number and returns its new value.

$num = $ha->incrby( $key, 2 );

🌈 CREDITS 🌈

The implementation is inspired by Tie::StdHash.

👑 INDEX 👑

MCE, MCE::Hobo, MCE::Shared

💜 AUTHOR 💜

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

okay that’s the whole page bestie — this one’s from perl v5.40.0, dated 2024-09-10, and it’s literally MCE::Shared::Hash(3). byeeee 💅✨

📦 where this page comes from

epel 10: perl-MCE-Shared 1.893-1.el10_0 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

MCE::Shared::Hash(3)

🌸 NAME 🌸

✨ VERSION ✨

💖 DESCRIPTION 💖

🎀 SYNOPSIS 🎀

🌈 SYNTAX for QUERY STRING 🌈

✨ API DOCUMENTATION ✨

💖 MCE::Shared::Hash->new ( key, value [, key, value, ... ] ) and MCE::Shared->hash ( key, value [, key, value, ... ] )

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

🧚 clear

🦋 clone ( key [, key, ... ] )

🌸 delete ( key )

💫 del

🍓 exists ( key )

🌈 flush ( key [, key, ... ] )

⭐ get ( key )

💜 iterator ( key [, key, ... ] )

🫶 iterator ( "query string" )

👑 keys ( key [, key, ... ] )

✨ keys ( "query string" )

💅 len ( key )

🔥 mdel ( key [, key, ... ] )

🌟 mexists ( key [, key, ... ] )

🧁 mget ( key [, key, ... ] )

🎀 mset ( key, value [, key, value, ... ] )

🦋 merge

🌸 pairs ( key [, key, ... ] )

💖 pairs ( "query string" )

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

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

⭐ set ( key, value )

🧚 setnx ( key, value )

🌈 values ( key [, key, ... ] )

💜 values ( "query string" )

🍓 vals