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.874
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   $mutex->unlock ( void )
114       Releases the lock. A held lock by an exiting process or thread is
115       released automatically.
116
117   $mutex->synchronize ( sub { ... }, @_ )
118   $mutex->enter ( sub { ... }, @_ )
119       Obtains a lock, runs the code block, and releases the lock after the
120       block completes. Optionally, the method is "wantarray" aware.
121
122        my $val = $mutex->synchronize( sub {
123            # access shared resource
124            return 'scalar';
125        });
126
127        my @ret = $mutex->enter( sub {
128            # access shared resource
129            return @list;
130        });
131
132       The method "enter" is an alias for "synchronize", available since
133       1.822.
134
135   $mutex->timedwait ( timeout )
136       Blocks until obtaining an exclusive lock. A false value is returned if
137       the timeout is reached, and a true value otherwise. The default is 1
138       second when omitting timeout.
139
140        my $mutex = MCE::Mutex->new( path => $0 );
141
142        # terminate script if a previous instance is still running
143
144        exit unless $mutex->timedwait( 2 );
145
146        ...
147
148       Current API available since 1.822.
149

INDEX

151       MCE, MCE::Core
152

AUTHOR

154       Mario E. Roy, <marioeroy AT gmail DOT com>
155
156
157
158perl v5.34.0                      2021-07-22                     MCE::Mutex(3)