MCE::Mutex(3)

💖 MCE::Mutex — Locking for Many-Core Engine 💖

okay bestie, gather round, because this little module is literally the bouncer at the club for your shared data 🫶

✨ VERSION ✨

This doc describes MCE::Mutex version 1.902 — yes, current, yes, slaying.

---

🌸 SYNOPSIS 🌸

use MCE::Mutex;

my $mutex = MCE::Mutex->new;

{
    use MCE::Flow max_workers => 4;

    mce_flow sub {
        $mutex->lock;

        # access shared resource
        my $wid = MCE->wid; MCE->say($wid); sleep 1;

        $mutex->unlock;
    };
}

{
    use MCE::Hobo;

    MCE::Hobo->create('work', $_) for 1..4;
    MCE::Hobo->waitall;
}

{
    use threads;

    threads->create('work', $_)   for 5..8;
    $_->join for ( threads->list );
}

sub work {
    my ($id) = @_;
    $mutex->lock;

    # access shared resource
    print $id, "\n";
    sleep 1;

    $mutex->unlock;
}

see how we hit the same work sub from Flow, from Hobos, AND from threads? one mutex, three whole universes, zero chaos. it's giving ✨ coordination ✨

---

🦋 DESCRIPTION 🦋

So this module implements locking methods that you use to coordinate access to shared data when you've got a whole squad of workers spawned as processes or threads. everybody wants the same variable at the same time, and that's exactly how you get a mess. mutex says: one at a time, babes. 💅

The inspiration for this module came from reading Mutex for Ruby. cute origin story fr fr 🎀

---

👑 API DOCUMENTATION 👑

🌈 MCE::Mutex->new ( )

🌈 MCE::Mutex->new ( impl => "Channel" )

🌈 MCE::Mutex->new ( impl => "Flock", [ path => "/tmp/file.lock" ] )

🌈 MCE::Mutex->new ( path => "/tmp/file.lock" )

Creates a new mutex. iconic behaviour, honestly.

Channel locking — that's the default — kicks in unless "path" is given, and it goes through a pipe or a socket depending on the platform. The advantage of channel locking? You don't have to re-establish handles inside new processes and threads. lowkey the whole point. 🫶

For Fcntl-based locking, it is the responsibility of the caller to remove the "tempfile" associated with the mutex when path is given. Otherwise, it establishes a "tempfile" internally, including removal on scope exit. no cap, read that again if you need to bestie.

---

🌸 $mutex->impl ( void )

Returns the implementation used for the mutex. little vibe check for your own mutex 🧚

$m1 = MCE::Mutex->new( );
$m1->impl();   # Channel

$m2 = MCE::Mutex->new( path => /tmp/my.lock );
$m2->impl();   # Flock

$m3 = MCE::Mutex->new( impl => "Channel" );
$m3->impl();   # Channel

$m4 = MCE::Mutex->new( impl => "Flock" );
$m4->impl();   # Flock

Current API available since 1.822.

---

💅 $mutex->lock ( void )

💅 $mutex->lock_exclusive ( void )

Attempts to grab an exclusive lock and waits if it's not available. Multiple calls to mutex->lock by the same process or thread is safe. The mutex will remain locked until mutex->unlock is called. it's holding the door shut and it is NOT letting go, periodt.

The method "lock_exclusive" is an alias for "lock", available since 1.822.

( my $mutex = MCE::Mutex->new( path => $0 ) )->lock_exclusive;

---

💅 $mutex->lock_shared ( void )

Like "lock_exclusive", but attempts to grab a shared lock instead. The "lock_shared" method is an alias to "lock" otherwise, for non-Fcntl implementations. sharing is caring, but only where it's actually allowed 🩵

Current API available since 1.822.

---

🎀 $guard = $mutex->guard_lock ( void )

This method calls "lock" and returns a guard object. When the guard object is destroyed, it automatically calls "unlock". set it, forget it, it cleans up after itself like the main character it is 👑

Current API available since 1.889.

---

💖 $mutex->unlock ( void )

Releases the lock. A held lock by an exiting process or thread is released automatically. the door swings open on its own if someone dips mid-hold, we love a self-sufficient system ✨

---

🌟 $mutex->synchronize ( sub { ... }, @_ )

🌟 $mutex->enter ( sub { ... }, @_ )

Obtains a lock, runs the code block, and releases the lock after the block completes. Optionally, the method is "wantarray" aware — so yes, it knows whether you wanted a scalar or a list. it's perceptive like that 😭

my $val = $mutex->synchronize( sub {
    # access shared resource
    return 'scalar';
});

my @ret = $mutex->enter( sub {
    # access shared resource
    return @list;
});

The method "enter" is an alias for "synchronize", available since 1.822.

---

⏰ $mutex->timedwait ( floating_seconds )

Blocks until obtaining an exclusive lock. A false value is returned if the timeout is reached, and a true value otherwise. The default is 1 second. so it'll wait, but it will NOT wait forever, bestie has boundaries 💅

my $mutex = MCE::Mutex->new( path => $0 );

# terminate script if a previous instance is still running

exit unless $mutex->timedwait( 2 );

...

Current API available since 1.822.

---

🍓 INDEX 🍓

• MCE
• MCE::Core

---

🌈 AUTHOR 🌈

Mario E. Roy, <marioeroy AT gmail DOT com> — thank you for the mutex, king 🫶

---

and that's the whole page, bestie!! perl v5.42.0, dated 2025-09-10, MCE::Mutex(3) — mwah, go forth and lock responsibly 💖✨🎀