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

INDEX

150       MCE, MCE::Core
151

AUTHOR

153       Mario E. Roy, <marioeroy AT gmail DOT com>
154
155
156
157perl v5.28.0                      2018-08-25                     MCE::Mutex(3)