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

NAME

6       "Future::Mutex" - mutual exclusion lock around code that returns
7       Futures
8

SYNOPSIS

10          use Future::Mutex;
11
12          my $mutex = Future::Mutex->new;
13
14          sub do_atomically
15          {
16             return $mutex->enter( sub {
17                ...
18                return $f;
19             });
20          }
21

DESCRIPTION

23       Most Future-using code expects to run with some level of concurrency,
24       using future instances to represent still-pending operations that will
25       complete at some later time. There are occasions however, when this
26       concurrency needs to be restricted - some operations that, once
27       started, must not be interrupted until they are complete. Subsequent
28       requests to perform the same operation while one is still outstanding
29       must therefore be queued to wait until the first is finished. These
30       situations call for a mutual-exclusion lock, or "mutex".
31
32       A "Future::Mutex" instance provides one basic operation, which will
33       execute a given block of code which returns a future, and itself
34       returns a future to represent that. The mutex can be in one of two
35       states; either unlocked or locked. While it is unlocked, requests to
36       execute code are handled immediately. Once a block of code is invoked,
37       the mutex is now considered to be locked, causing any subsequent
38       requests to invoke code to be queued behind the first one, until it
39       completes. Once the initial code indicates completion (by its returned
40       future providing a result or failing), the next queued code is invoked.
41
42       An instance may also be a counting mutex if initialised with a count
43       greater than one. In this case, it can keep multiple blocks outstanding
44       up to that limit, with subsequent requests queued as before. This
45       allows it to act as a concurrency-bounding limit around some operation
46       that can run concurrently, but an application wishes to apply overall
47       limits to stop it growing too much, such as communications with
48       external services or executing other programs.
49

CONSTRUCTOR

51   new
52          $mutex = Future::Mutex->new( count => $n )
53
54       Returns a new "Future::Mutex" instance. It is initially unlocked.
55
56       Takes the following named arguments:
57
58       count => INT
59               Optional number to limit outstanding concurrency. Will default
60               to 1 if not supplied.
61

METHODS

63   enter
64          $f = $mutex->enter( \&code )
65
66       Returns a new "Future" that represents the eventual result of calling
67       the code. If the mutex is currently unlocked, the code will be invoked
68       immediately. If it is currently locked, the code will be queued waiting
69       for the next time it becomes unlocked.
70
71       The code is invoked with no arguments, and is expected to return a
72       "Future".  The eventual result of that future determines the result of
73       the future that "enter" returned.
74
75   available
76          $avail = $mutex->available
77
78       Returns true if the mutex is currently unlocked, or false if it is
79       locked.
80

AUTHOR

82       Paul Evans <leonerd@leonerd.org.uk>
83
84
85
86perl v5.38.0                      2023-07-20                Future::Mutex(3pm)
Impressum