1MCE::Mutex(3)         User Contributed Perl Documentation        MCE::Mutex(3)
2
3
4

NAME

6       MCE::Mutex - Locking for Many-Core Engine
7

VERSION

9       This document describes MCE::Mutex version 1.889
10

SYNOPSIS

12        use MCE::Mutex;
13
14        my $mutex = MCE::Mutex->new;
15
16        {
17            use MCE::Flow max_workers => 4;
18
19            mce_flow sub {
20                $mutex->lock;
21
22                # access shared resource
23                my $wid = MCE->wid; MCE->say($wid); sleep 1;
24
25                $mutex->unlock;
26            };
27        }
28
29        {
30            use MCE::Hobo;
31
32            MCE::Hobo->create('work', $_) for 1..4;
33            MCE::Hobo->waitall;
34        }
35
36        {
37            use threads;
38
39            threads->create('work', $_)   for 5..8;
40            $_->join for ( threads->list );
41        }
42
43        sub work {
44            my ($id) = @_;
45            $mutex->lock;
46
47            # access shared resource
48            print $id, "\n";
49            sleep 1;
50
51            $mutex->unlock;
52        }
53

DESCRIPTION

55       This module implements locking methods that can be used to coordinate
56       access to shared data from multiple workers spawned as processes or
57       threads.
58
59       The inspiration for this module came from reading Mutex for Ruby.
60

API DOCUMENTATION

62   MCE::Mutex->new ( )
63   MCE::Mutex->new ( impl => "Channel" )
64   MCE::Mutex->new ( impl => "Flock", [ path => "/tmp/file.lock" ] )
65   MCE::Mutex->new ( path => "/tmp/file.lock" )
66       Creates a new mutex.
67
68       Channel locking (the default), unless "path" is given, is through a
69       pipe or socket depending on the platform. The advantage of channel
70       locking is not having to re-establish handles inside new processes and
71       threads.
72
73       For Fcntl-based locking, it is the responsibility of the caller to
74       remove the "tempfile", associated with the mutex, when path is given.
75       Otherwise, it establishes a "tempfile" internally including removal on
76       scope exit.
77
78   $mutex->impl ( void )
79       Returns the implementation used for the mutex.
80
81        $m1 = MCE::Mutex->new( );
82        $m1->impl();   # Channel
83
84        $m2 = MCE::Mutex->new( path => /tmp/my.lock );
85        $m2->impl();   # Flock
86
87        $m3 = MCE::Mutex->new( impl => "Channel" );
88        $m3->impl();   # Channel
89
90        $m4 = MCE::Mutex->new( impl => "Flock" );
91        $m4->impl();   # Flock
92
93       Current API available since 1.822.
94
95   $mutex->lock ( void )
96   $mutex->lock_exclusive ( void )
97       Attempts to grab an exclusive lock and waits if not available. Multiple
98       calls to mutex->lock by the same process or thread is safe. The mutex
99       will remain locked until mutex->unlock is called.
100
101       The method "lock_exclusive" is an alias for "lock", available since
102       1.822.
103
104        ( my $mutex = MCE::Mutex->new( path => $0 ) )->lock_exclusive;
105
106   $mutex->lock_shared ( void )
107       Like "lock_exclusive", but attempts to grab a shared lock instead.  The
108       "lock_shared" method is an alias to "lock" otherwise for non-Fcntl
109       implementations.
110
111       Current API available since 1.822.
112
113   $guard = $mutex->guard_lock ( void )
114       This method calls "lock" and returns a guard object. When the guard
115       object is destroyed, it automatically calls "unlock".
116
117       Current API available since 1.889.
118
119   $mutex->unlock ( void )
120       Releases the lock. A held lock by an exiting process or thread is
121       released automatically.
122
123   $mutex->synchronize ( sub { ... }, @_ )
124   $mutex->enter ( sub { ... }, @_ )
125       Obtains a lock, runs the code block, and releases the lock after the
126       block completes. Optionally, the method is "wantarray" aware.
127
128        my $val = $mutex->synchronize( sub {
129            # access shared resource
130            return 'scalar';
131        });
132
133        my @ret = $mutex->enter( sub {
134            # access shared resource
135            return @list;
136        });
137
138       The method "enter" is an alias for "synchronize", available since
139       1.822.
140
141   $mutex->timedwait ( floating_seconds )
142       Blocks until obtaining an exclusive lock. A false value is returned if
143       the timeout is reached, and a true value otherwise. The default is 1
144       second.
145
146        my $mutex = MCE::Mutex->new( path => $0 );
147
148        # terminate script if a previous instance is still running
149
150        exit unless $mutex->timedwait( 2 );
151
152        ...
153
154       Current API available since 1.822.
155

INDEX

157       MCE, MCE::Core
158

AUTHOR

160       Mario E. Roy, <marioeroy AT gmail DOT com>
161
162
163
164perl v5.38.0                      2023-09-14                     MCE::Mutex(3)