MDL-69521 core: Move all comments in code from 4.0 to 3.10
[moodle.git] / lib / classes / lock / lock_factory.php
CommitLineData
9843e5ec
DW
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/>.
16
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 */
24
25namespace core\lock;
26
27defined('MOODLE_INTERNAL') || die();
28
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 */
37interface lock_factory {
38
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);
45
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();
52
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();
62
63 /**
34027f15 64 * Supports recursion.
9843e5ec 65 *
709b46db 66 * @deprecated since Moodle 3.10.
9843e5ec
DW
67 * @return boolean - True if attempting to get 2 locks on the same resource will "stack"
68 */
69 public function supports_recursion();
70
71 /**
72 * Is available.
73 *
74 * @return boolean - True if this lock type is available in this environment.
75 */
76 public function is_available();
77
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);
90
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);
98
99 /**
100 * Extend the timeout on a held lock.
101 *
709b46db 102 * @deprecated since Moodle 3.10.
9843e5ec
DW
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);
108}