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    /**
64     * Supports recursion.
65     *
66     * @return boolean - True if attempting to get 2 locks on the same resource will "stack"
67     */
68    public function supports_recursion();
69
70    /**
71     * Is available.
72     *
73     * @return boolean - True if this lock type is available in this environment.
74     */
75    public function is_available();
76
77    /**
78     * Get a lock within the specified timeout or return false.
79     *
80     * @param string $resource - The identifier for the lock. Should use frankenstyle prefix.
81     * @param int $timeout - The number of seconds to wait for a lock before giving up.
82     *                       Not all lock types will support this.
83     * @param int $maxlifetime - The number of seconds to wait before reclaiming a stale lock.
84     *                       Not all lock types will use this - e.g. if they support auto releasing
85     *                       a lock when a process ends.
86     * @return \core\lock\lock|boolean - An instance of \core\lock\lock if the lock was obtained, or false.
87     */
88    public function get_lock($resource, $timeout, $maxlifetime = 86400);
89
90    /**
91     * Release a lock that was previously obtained with @lock.
92     *
93     * @param lock $lock - The lock to release.
94     * @return boolean - True if the lock is no longer held (including if it was never held).
95     */
96    public function release_lock(lock $lock);
97
98    /**
99     * Extend the timeout on a held lock.
100     *
101     * @param lock $lock - lock obtained from this factory
102     * @param int $maxlifetime - new max time to hold the lock
103     * @return boolean - True if the lock was extended.
104     */
105    public function extend_lock(lock $lock, $maxlifetime = 86400);
106}
107