Merge pull request #26 from TheLevti/develop

#25: Drop support for php 5.6 and 7.0

Author: Willem Stuursma-Ruwen

.gitattributes

@@ -1,5 +1,6 @@
+/.github export-ignore
 /tests export-ignore
 /.gitattributes export-ignore
 /.gitignore export-ignore
 /.travis.yml export-ignore
-/phpunit.xml export-ignore
+/phpunit.xml.dist export-ignore

.gitignore

@@ -1,3 +1,4 @@
-/.idea/
+/.idea
+/vendor
 /composer.lock
-/vendor/
+/phpunit.xml

.travis.yml

@@ -7,8 +7,6 @@ cache:
     - $HOME/.composer/cache
 
 php:
-  - 5.6
-  - 7.0
   - 7.1
   - 7.2
   - nightly
@@ -47,6 +45,6 @@ before_script:
   - psql  -c 'create database test;' -U postgres
 
 script:
-  - vendor/bin/phpunit --debug
+  - vendor/bin/phpunit 
   - vendor/bin/phpcs --standard=PSR2 classes/ tests/
 

README.md

@@ -1,68 +1,149 @@
+**[Requirements](#requirements)** |
+**[Installation](#installation)** |
+**[Usage](#usage)** |
+**[License and authors](#license-and-authors)** |
+**[Donations](#donations)**
+
+# php-lock/lock
+
+[![Latest Stable Version](https://poser.pugx.org/malkusch/lock/version)](https://packagist.org/packages/malkusch/lock)
+[![Total Downloads](https://poser.pugx.org/malkusch/lock/downloads)](https://packagist.org/packages/malkusch/lock)
+[![Latest Unstable Version](https://poser.pugx.org/malkusch/lock/v/unstable)](//packagist.org/packages/malkusch/lock)
 [![Build Status](https://travis-ci.org/php-lock/lock.svg?branch=master)](https://travis-ci.org/php-lock/lock)
+[![License](https://poser.pugx.org/malkusch/lock/license)](https://packagist.org/packages/malkusch/lock)
 
 This library helps executing critical code in concurrent situations.
 
-# Installation
+php-lock/lock follows semantic versioning. Read more on [semver.org][1].
+
+----
+
+## Requirements
+
+ - PHP 7.1 or above
+ - Optionally [nrk/predis][2] to use the predis locks.
+ - Optionally the [php-pcntl][3] extension to enable locking with flock without
+   busy waiting in CLI scripts.
 
-Use [Composer](https://getcomposer.org/):
+----
+
+## Installation
+
+### Composer
+
+To use this library through [composer][4], run the following terminal command
+inside your repository's root folder.
 
 ```sh
-composer require malkusch/lock
+composer require "malkusch/lock"
 ```
 
-# Usage
+As an alternative, you can directly add this library to your `composer.json`.
 
-The package is in the namespace
-[`malkusch\lock`](http://malkusch.github.io/lock/api/namespace-malkusch.lock.html).
+``` json
+{
+    "require": {
+        "malkusch/lock": "^1.4"
+    }
+}
+```
 
-## Mutex
+To use the newest (maybe unstable) version, use `dev-master` as the version in
+your `composer.json`.
 
-The
-[`Mutex`](http://malkusch.github.io/lock/api/class-malkusch.lock.mutex.Mutex.html)
-provides the API for this library.
+``` json
+{
+    "require": {
+        "malkusch/lock": "dev-master"
+    }
+}
+```
+
+## Usage
+
+This library uses the namespace `malkusch\lock`.
+
+### Mutex
 
-### Mutex::synchronized()
+The [`malkusch\lock\mutex\Mutex`][5] class is an abstract class and provides the
+base API for this library.
 
-[`Mutex::synchronized()`](http://malkusch.github.io/lock/api/class-malkusch.lock.mutex.Mutex.html#_synchronized)
-executes code exclusively. This method guarantees that the code is only executed
-by one process at once. Other processes have to wait until the mutex is available.
-The critical code may throw an exception, which would release the lock as well.
+#### Mutex::synchronized()
+
+[`malkusch\lock\mutex\Mutex::synchronized()`][6] executes code exclusively. This
+method guarantees that the code is only executed by one process at once. Other
+processes have to wait until the mutex is available. The critical code may throw
+an exception, which would release the lock as well.
+
+This method returns what ever is returned to the given callable. The return
+value is not checked, thus it is up to the user to decide if for example the
+return value `false` or `null` should be seen as a failed action.
 
 Example:
+
 ```php
-$mutex->synchronized(function () use ($bankAccount, $amount) {
+$newBalance = $mutex->synchronized(function () use ($bankAccount, $amount) {
     $balance = $bankAccount->getBalance();
     $balance -= $amount;
     if ($balance < 0) {
-        throw new \DomainException("You have no credit.");
-
+        throw new \DomainException('You have no credit.');
     }
     $bankAccount->setBalance($balance);
+
+    return $balance;
 });
 ```
 
-### Mutex::check()
+#### Mutex::check()
+
+[`malkusch\lock\mutex\Mutex::check()`][7] sets a callable, which will be
+executed when [`malkusch\lock\util\DoubleCheckedLocking::then()`][8] is called,
+and performs a double-checked locking pattern, where it's return value decides
+if the lock needs to be acquired and the synchronized code to be executed.
+
+See [https://en.wikipedia.org/wiki/Double-checked_locking][9] for a more
+detailed explanation of that feature.
 
-[`Mutex::check()`](http://malkusch.github.io/lock/api/class-malkusch.lock.mutex.Mutex.html#_check)
-performs a double-checked locking pattern. I.e. if the check fails, no lock
-will be acquired. Else if the check was true, a lock will be acquired and the
-check will be perfomed as well together with the critical code.
+If the check's callable returns `false`, no lock will be acquired and the
+synchronized code will not be executed. In this case the
+[`malkusch\lock\util\DoubleCheckedLocking::then()`][8] method, will also return
+`false` to indicate that the check did not pass either before or after acquiring
+the lock.
+
+In the case where the check's callable returns a value other than `false`, the
+[`malkusch\lock\util\DoubleCheckedLocking::then()`][8] method, will
+try to acquire the lock and on success will perform the check again. Only when
+the check returns something other than `false` a second time, the synchronized
+code callable, which has been passed to `then()` will be executed. In this case
+the return value of `then()` will be what ever the given callable returns and
+thus up to the user to return `false` or `null` to indicate a failed action as
+this return value will not be checked by the library.
 
 Example:
+
 ```php
-$mutex->check(function () use ($bankAccount, $amount) {
+$newBalance = $mutex->check(function () use ($bankAccount, $amount) {
     return $bankAccount->getBalance() >= $amount;
-
 })->then(function () use ($bankAccount, $amount) {
     $balance = $bankAccount->getBalance();
     $balance -= $amount;
     $bankAccount->setBalance($balance);
+
+    return $balance;
 });
+
+if (false === $newBalance) {
+    if ($balance < 0) {
+        throw new \DomainException('You have no credit.');
+    }
+}
 ```
 
 ### Implementations
 
-The `Mutex` is an abstract class. You will have to choose an implementation:
+Because the [`malkusch\lock\mutex\Mutex`](#mutex) class is an abstract class,
+you can choose from one of the provided implementations or create/extend your
+own implementation.
 
 - [`CASMutex`](#casmutex)
 - [`FlockMutex`](#flockmutex)
@@ -74,19 +155,18 @@ The `Mutex` is an abstract class. You will have to choose an implementation:
 - [`MySQLMutex`](#mysqlmutex)
 - [`PgAdvisoryLockMutex`](#pgadvisorylockmutex)
 
-
 #### CASMutex
 
-The **CASMutex**
-has to be used with a [Compare-and-swap](https://en.wikipedia.org/wiki/Compare-and-swap) operation.
-This mutex is lock free. It will repeat executing the code until the CAS operation was
-successful. The code should therefore notify the mutex by calling
-[`CASMutex::notify()`](http://malkusch.github.io/lock/api/class-malkusch.lock.mutex.CASMutex.html#_notify).
+The **CASMutex** has to be used with a [Compare-and-swap][10] operation. This
+mutex is lock free. It will repeat executing the code until the CAS operation
+was successful. The code should therefore notify the mutex by calling
+[`malkusch\lock\mutex\CASMutex::notify()`][11].
 
-As the mutex keeps executing the critical code, it must not have any side effects
-as long as the CAS operation was not successful.
+As the mutex keeps executing the critical code, it must not have any side
+effects as long as the CAS operation was not successful.
 
 Example:
+
 ```php
 $mutex = new CASMutex();
 $mutex->synchronized(function () use ($memcached, $mutex, $amount) {
@@ -118,8 +198,8 @@ $mutex->synchronized(function () use ($bankAccount, $amount) {
 });
 ```
 
-Timeouts are supported as an optional second argument. This uses the pcntl extension if 
-possible or busy waiting if not.  
+Timeouts are supported as an optional second argument. This uses the pcntl
+extension if possible or busy waiting if not.  
 
 #### MemcachedMutex
 
@@ -240,7 +320,6 @@ $mutex->synchronized(function () use ($pdo, $accountId, $amount) {
 });
 ```
 
-
 #### MySQLMutex
 
 The **MySQLMutex** uses MySQL's 
@@ -267,6 +346,7 @@ $mutex->synchronized(function () use ($bankAccount, $amount) {
     $bankAccount->setBalance($balance);
 });
 ```
+
 #### PgAdvisoryLockMutex
 
 The **PgAdvisoryLockMutex** uses PostgreSQL's 
@@ -293,9 +373,7 @@ $mutex->synchronized(function () use ($bankAccount, $amount) {
 });
 ```
 
-
-
-# License and authors
+## License and authors
 
 This project is free and under the WTFPL.
 Responsible for this project is Willem Stuursma-Ruwen <[email protected]>.
@@ -305,4 +383,14 @@ Responsible for this project is Willem Stuursma-Ruwen <[email protected]>.
 If you like this project and feel generous donate a few Bitcoins here:
 [1P5FAZ4QhXCuwYPnLZdk3PJsqePbu1UDDA](bitcoin:1P5FAZ4QhXCuwYPnLZdk3PJsqePbu1UDDA)
 
-
+[1]: http://semver.org
+[2]: https://github.com/nrk/predis
+[3]: http://php.net/manual/en/book.pcntl.php
+[4]: https://getcomposer.org
+[5]: https://github.com/php-lock/lock/blob/master/classes/mutex/Mutex.php
+[6]: https://github.com/php-lock/lock/blob/master/classes/mutex/Mutex.php#L38
+[7]: https://github.com/php-lock/lock/blob/master/classes/mutex/Mutex.php#L57
+[8]: https://github.com/php-lock/lock/blob/master/classes/util/DoubleCheckedLocking.php#L72
+[9]: https://en.wikipedia.org/wiki/Double-checked_locking
+[10]: https://en.wikipedia.org/wiki/Compare-and-swap
+[11]: https://github.com/php-lock/lock/blob/master/classes/mutex/CASMutex.php#L44

classes/mutex/CASMutex.php

@@ -33,15 +33,15 @@ class CASMutex extends Mutex
      * @param int $timeout The timeout in seconds.
      * @throws \LengthException The timeout must be greater than 0.
      */
-    public function __construct($timeout = 3)
+    public function __construct(int $timeout = 3)
     {
         $this->loop = new Loop($timeout);
     }
 
     /**
      * Notifies the Mutex about a successful CAS operation.
      */
-    public function notify()
+    public function notify(): void
     {
         $this->loop->end();
     }

classes/mutex/FlockMutex.php

@@ -20,7 +20,7 @@
  */
 class FlockMutex extends LockMutex
 {
-    const INFINITE_TIMEOUT = -1;
+    public const INFINITE_TIMEOUT = -1;
 
     /**
      * @internal
@@ -58,7 +58,7 @@ class FlockMutex extends LockMutex
      * @param resource $fileHandle The file handle.
      * @param int $timeout
      */
-    public function __construct($fileHandle, $timeout = self::INFINITE_TIMEOUT)
+    public function __construct($fileHandle, int $timeout = self::INFINITE_TIMEOUT)
     {
         if (!is_resource($fileHandle)) {
             throw new \InvalidArgumentException("The file handle is not a valid resource.");
@@ -85,7 +85,7 @@ private function determineLockingStrategy()
     /**
      * @throws LockAcquireException
      */
-    private function lockBlocking()
+    private function lockBlocking(): void
     {
         if (!flock($this->fileHandle, LOCK_EX)) {
             throw new LockAcquireException("Failed to lock the file.");
@@ -96,13 +96,13 @@ private function lockBlocking()
      * @throws LockAcquireException
      * @throws TimeoutException
      */
-    private function lockPcntl()
+    private function lockPcntl(): void
     {
         $timebox = new PcntlTimeout($this->timeout);
 
         try {
             $timebox->timeBoxed(
-                function () {
+                function (): void {
                     $this->lockBlocking();
                 }
             );
@@ -118,7 +118,7 @@ function () {
     private function lockBusy()
     {
         $loop = new Loop($this->timeout);
-        $loop->execute(function () use ($loop) {
+        $loop->execute(function () use ($loop): void {
             if ($this->acquireNonBlockingLock()) {
                 $loop->end();
             }
@@ -129,7 +129,7 @@ private function lockBusy()
      * @return bool
      * @throws LockAcquireException
      */
-    private function acquireNonBlockingLock()
+    private function acquireNonBlockingLock(): bool
     {
         if (!flock($this->fileHandle, LOCK_EX | LOCK_NB, $wouldBlock)) {
             if ($wouldBlock) {
@@ -147,7 +147,7 @@ private function acquireNonBlockingLock()
      * @throws LockAcquireException
      * @throws TimeoutException
      */
-    protected function lock()
+    protected function lock(): void
     {
         switch ($this->strategy) {
             case self::STRATEGY_BLOCK:
@@ -167,7 +167,7 @@ protected function lock()
     /**
      * @throws LockReleaseException
      */
-    protected function unlock()
+    protected function unlock(): void
     {
         if (!flock($this->fileHandle, LOCK_UN)) {
             throw new LockReleaseException("Failed to unlock the file.");