Lock.php

TLDR

The Lock.php file is a part of the Illuminate\Cache namespace in the Demo Projects project. It provides an abstract class called Lock that implements the LockContract interface. The class is used to create and manage locks for caching purposes.

Methods

acquire

This is an abstract method that attempts to acquire the lock. The implementation of this method is provided by the child classes that extend the Lock class.

release

This is an abstract method that releases the lock. The implementation of this method is provided by the child classes that extend the Lock class.

getCurrentOwner

This is an abstract method that returns the owner value written into the driver for this lock. The implementation of this method is provided by the child classes that extend the Lock class.

get

Attempts to acquire the lock and calls the provided callback function if the lock is successfully acquired. Returns the result of the callback function or true if no callback is provided. If the lock is acquired successfully, it is automatically released after the callback function is executed.

block

Attempts to acquire the lock for the given number of seconds. If the lock cannot be acquired within the specified time, a LockTimeoutException is thrown. If a callback function is provided, it is called after the lock is acquired and released automatically after the callback function is executed. Returns the result of the callback function or true if no callback is provided.

owner

Returns the current owner of the lock.

isOwnedByCurrentProcess

Determines whether this lock is owned by the current process.

betweenBlockedAttemptsSleepFor

Specifies the number of milliseconds to sleep in between blocked lock acquisition attempts.

Class

Lock

This is an abstract class that implements the LockContract interface. It provides common methods and properties for creating and managing locks. Child classes provide the implementation for the abstract methods acquire, releae, and getCurrentOwner.

<?php

namespace Illuminate\Cache;

use Illuminate\Contracts\Cache\Lock as LockContract;
use Illuminate\Contracts\Cache\LockTimeoutException;
use Illuminate\Support\InteractsWithTime;
use Illuminate\Support\Sleep;
use Illuminate\Support\Str;

abstract class Lock implements LockContract
{
    use InteractsWithTime;

    /**
     * The name of the lock.
     *
     * @var string
     */
    protected $name;

    /**
     * The number of seconds the lock should be maintained.
     *
     * @var int
     */
    protected $seconds;

    /**
     * The scope identifier of this lock.
     *
     * @var string
     */
    protected $owner;

    /**
     * The number of milliseconds to wait before re-attempting to acquire a lock while blocking.
     *
     * @var int
     */
    protected $sleepMilliseconds = 250;

    /**
     * Create a new lock instance.
     *
     * @param  string  $name
     * @param  int  $seconds
     * @param  string|null  $owner
     * @return void
     */
    public function __construct($name, $seconds, $owner = null)
    {
        if (is_null($owner)) {
            $owner = Str::random();
        }

        $this->name = $name;
        $this->owner = $owner;
        $this->seconds = $seconds;
    }

    /**
     * Attempt to acquire the lock.
     *
     * @return bool
     */
    abstract public function acquire();

    /**
     * Release the lock.
     *
     * @return bool
     */
    abstract public function release();

    /**
     * Returns the owner value written into the driver for this lock.
     *
     * @return string
     */
    abstract protected function getCurrentOwner();

    /**
     * Attempt to acquire the lock.
     *
     * @param  callable|null  $callback
     * @return mixed
     */
    public function get($callback = null)
    {
        $result = $this->acquire();

        if ($result && is_callable($callback)) {
            try {
                return $callback();
            } finally {
                $this->release();
            }
        }

        return $result;
    }

    /**
     * Attempt to acquire the lock for the given number of seconds.
     *
     * @param  int  $seconds
     * @param  callable|null  $callback
     * @return mixed
     *
     * @throws \Illuminate\Contracts\Cache\LockTimeoutException
     */
    public function block($seconds, $callback = null)
    {
        $starting = $this->currentTime();

        while (! $this->acquire()) {
            Sleep::usleep($this->sleepMilliseconds * 1000);

            if ($this->currentTime() - $seconds >= $starting) {
                throw new LockTimeoutException;
            }
        }

        if (is_callable($callback)) {
            try {
                return $callback();
            } finally {
                $this->release();
            }
        }

        return true;
    }

    /**
     * Returns the current owner of the lock.
     *
     * @return string
     */
    public function owner()
    {
        return $this->owner;
    }

    /**
     * Determines whether this lock is allowed to release the lock in the driver.
     *
     * @return bool
     */
    public function isOwnedByCurrentProcess()
    {
        return $this->getCurrentOwner() === $this->owner;
    }

    /**
     * Specify the number of milliseconds to sleep in between blocked lock acquisition attempts.
     *
     * @param  int  $milliseconds
     * @return $this
     */
    public function betweenBlockedAttemptsSleepFor($milliseconds)
    {
        $this->sleepMilliseconds = $milliseconds;

        return $this;
    }
}