moodle/lib/classes/lock/postgres_lock_factory.php

<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

namespace core\lock;

use coding_exception;

/**
 * Postgres advisory locking factory.
 *
 * Postgres locking implementation using advisory locks. Some important points. Postgres has
 * 2 different forms of lock functions, some accepting a single int, and some accepting 2 ints. This implementation
 * uses the 2 int version so that it uses a separate namespace from the session locking. The second note,
 * is because postgres uses integer keys for locks, we first need to map strings to a unique integer. This is done
 * using a prefix of a sha1 hash converted to an integer. There is a realistic chance of collisions by using this
 * prefix when locking multiple resources at the same time (multiple resource identifiers leading to the
 * same token/prefix). We need to deal with that.
 *
 * @package   core
 * @category  lock
 * @copyright Damyon Wiese 2013
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class postgres_lock_factory implements lock_factory {

    /** @var int $dblockid - used as a namespace for these types of locks (separate from session locks) */
    protected $dblockid = -1;

    /** @var array $lockidcache - static cache for string -> int conversions required for pg advisory locks. */
    protected static $lockidcache = array();

    /** @var \moodle_database $db Hold a reference to the global $DB */
    protected $db;

    /** @var string $type Used to prefix lock keys */
    protected $type;

    /** @var int[] $resourcetokens Mapping of held locks (resource identifier => internal token) */
    protected $resourcetokens = [];

    /** @var int[] $locksbytoken Mapping of held locks (db connection => internal token => number of locks held) */
    static protected $locksbytoken = [];

    /**
     * Calculate a unique instance id based on the database name and prefix.
     * @return int.
     */
    protected function get_unique_db_instance_id() {
        global $CFG;

        $strkey = $CFG->dbname . ':' . $CFG->prefix;
        $intkey = crc32($strkey);
        // Normalize between 64 bit unsigned int and 32 bit signed ints. Php could return either from crc32.
        if (PHP_INT_SIZE == 8) {
            if ($intkey > 0x7FFFFFFF) {
                $intkey -= 0x100000000;
            }
        }

        return $intkey;
    }

    /**
     * Almighty constructor.
     * @param string $type - Used to prefix lock keys.
     */
    public function __construct($type) {
        global $DB;

        $this->type = $type;
        $this->dblockid = $this->get_unique_db_instance_id();
        // Save a reference to the global $DB so it will not be released while we still have open locks.
        $this->db = $DB;

        \core_shutdown_manager::register_function(array($this, 'auto_release'));
    }

    /**
     * Is available.
     * @return boolean - True if this lock type is available in this environment.
     */
    public function is_available() {
        return $this->db->get_dbfamily() === 'postgres';
    }

    /**
     * Return information about the blocking behaviour of the lock type on this platform.
     * @return boolean - Defer to the DB driver.
     */
    public function supports_timeout() {
        return true;
    }

    /**
     * Will this lock type will be automatically released when a process ends.
     *
     * @return boolean - Via shutdown handler.
     */
    public function supports_auto_release() {
        return true;
    }

    /**
     * @deprecated since Moodle 3.10.
     */
    public function supports_recursion() {
        throw new coding_exception('The function supports_recursion() has been removed, please do not use it anymore.');
    }

    /**
     * This function generates the unique index for a specific lock key using
     * a sha1 prefix converted to decimal.
     *
     * @param string $key
     * @return int
     * @throws \moodle_exception
     */
    protected function get_index_from_key($key) {

        // A prefix of 7 hex chars is chosen as fffffff is the largest hex code
        // which when converted to decimal (268435455) fits inside a 4 byte int
        // which is the second param to pg_try_advisory_lock().
        $hash = substr(sha1($key), 0, 7);
        $index = hexdec($hash);
        return $index;
    }

    /**
     * Create and get a lock
     *
     * @param string $resource - The identifier for the lock. Should use frankenstyle prefix.
     * @param int $timeout - The number of seconds to wait for a lock before giving up.
     * @param int $maxlifetime - Unused by this lock type.
     * @return \core\lock\lock|boolean - An instance of \core\lock\lock if the lock was obtained, or false.
     */
    public function get_lock($resource, $timeout, $maxlifetime = 86400) {
        $dbid = spl_object_id($this->db);
        $giveuptime = time() + $timeout;
        $resourcekey = $this->type . '_' . $resource;
        $token = $this->get_index_from_key($resourcekey);

        if (isset($this->resourcetokens[$resourcekey])) {
            return false;
        }

        if (isset(self::$locksbytoken[$dbid][$token])) {
            // There is a hash collision, another resource identifier leads to the same token.
            // As we already hold an advisory lock for this token, we just increase the counter.
            self::$locksbytoken[$dbid][$token]++;
            $this->resourcetokens[$resourcekey] = $token;
            return new lock($resourcekey, $this);
        }

        $params = [
            'locktype' => $this->dblockid,
            'token' => $token
        ];

        $locked = false;

        do {
            $result = $this->db->get_record_sql('SELECT pg_try_advisory_lock(:locktype, :token) AS locked', $params);
            $locked = $result->locked === 't';
            if (!$locked && $timeout > 0) {
                usleep(rand(10000, 250000)); // Sleep between 10 and 250 milliseconds.
            }
            // Try until the giveup time.
        } while (!$locked && time() < $giveuptime);

        if ($locked) {
            self::$locksbytoken[$dbid][$token] = 1;
            $this->resourcetokens[$resourcekey] = $token;
            return new lock($resourcekey, $this);
        }
        return false;
    }

    /**
     * Release a lock that was previously obtained with @lock.
     * @param lock $lock - a lock obtained from this factory.
     * @return boolean - true if the lock is no longer held (including if it was never held).
     */
    public function release_lock(lock $lock) {
        $dbid = spl_object_id($this->db);
        $resourcekey = $lock->get_key();

        if (isset($this->resourcetokens[$resourcekey])) {
            $token = $this->resourcetokens[$resourcekey];
        } else {
            return true;
        }

        if (self::$locksbytoken[$dbid][$token] > 1) {
            // There are multiple resource identifiers that lead to the same token.
            // We will unlock the token later when the last resource is released.
            unset($this->resourcetokens[$resourcekey]);
            self::$locksbytoken[$dbid][$token]--;
            return true;
        }

        $params = [
            'locktype' => $this->dblockid,
            'token' => $token,
        ];
        $result = $this->db->get_record_sql('SELECT pg_advisory_unlock(:locktype, :token) AS unlocked', $params);
        $result = $result->unlocked === 't';
        if ($result) {
            unset($this->resourcetokens[$resourcekey]);
            unset(self::$locksbytoken[$dbid][$token]);
        }
        return $result;
    }

    /**
     * @deprecated since Moodle 3.10.
     */
    public function extend_lock() {
        throw new coding_exception('The function extend_lock() has been removed, please do not use it anymore.');
    }

    /**
     * Auto release any open locks on shutdown.
     * This is required, because we may be using persistent DB connections.
     */
    public function auto_release() {
        // Called from the shutdown handler. Must release all open locks.
        foreach ($this->resourcetokens as $resourcekey => $unused) {
            $lock = new lock($resourcekey, $this);
            $lock->release();
        }
    }

}