MDL-67594 core_lock: Deprecate extend_lock()
[moodle.git] / lib / classes / lock / lock_factory.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * Defines abstract factory class for generating locks.
19  *
20  * @package    core
21  * @copyright  Damyon Wiese 2013
22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 namespace core\lock;
27 defined('MOODLE_INTERNAL') || die();
29 /**
30  * Defines abstract factory class for generating locks.
31  *
32  * @package   core
33  * @category  lock
34  * @copyright Damyon Wiese 2013
35  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36  */
37 interface lock_factory {
39     /**
40      * Define the constructor signature required by the lock_config class.
41      *
42      * @param string $type - The type this lock is used for (e.g. cron, cache)
43      */
44     public function __construct($type);
46     /**
47      * Return information about the blocking behaviour of the locks on this platform.
48      *
49      * @return boolean - False if attempting to get a lock will block indefinitely.
50      */
51     public function supports_timeout();
53     /**
54      * Will this lock be automatically released when the process ends.
55      * This should never be relied upon in code - but is useful in the case of
56      * fatal errors. If a lock type does not support this auto release,
57      * the max lock time parameter must be obeyed to eventually clean up a lock.
58      *
59      * @return boolean - True if this lock type will be automatically released when the current process ends.
60      */
61     public function supports_auto_release();
63     /**
64      * Supports recursion.
65      *
66      * @deprecated since Moodle 4.0.
67      * @return boolean - True if attempting to get 2 locks on the same resource will "stack"
68      */
69     public function supports_recursion();
71     /**
72      * Is available.
73      *
74      * @return boolean - True if this lock type is available in this environment.
75      */
76     public function is_available();
78     /**
79      * Get a lock within the specified timeout or return false.
80      *
81      * @param string $resource - The identifier for the lock. Should use frankenstyle prefix.
82      * @param int $timeout - The number of seconds to wait for a lock before giving up.
83      *                       Not all lock types will support this.
84      * @param int $maxlifetime - The number of seconds to wait before reclaiming a stale lock.
85      *                       Not all lock types will use this - e.g. if they support auto releasing
86      *                       a lock when a process ends.
87      * @return \core\lock\lock|boolean - An instance of \core\lock\lock if the lock was obtained, or false.
88      */
89     public function get_lock($resource, $timeout, $maxlifetime = 86400);
91     /**
92      * Release a lock that was previously obtained with @lock.
93      *
94      * @param lock $lock - The lock to release.
95      * @return boolean - True if the lock is no longer held (including if it was never held).
96      */
97     public function release_lock(lock $lock);
99     /**
100      * Extend the timeout on a held lock.
101      *
102      * @deprecated since Moodle 4.0.
103      * @param lock $lock - lock obtained from this factory
104      * @param int $maxlifetime - new max time to hold the lock
105      * @return boolean - True if the lock was extended.
106      */
107     public function extend_lock(lock $lock, $maxlifetime = 86400);