Cleaned up README.md

Author: TheLevti

README.md

@@ -1,6 +1,8 @@
 **[Requirements](#requirements)** |
 **[Installation](#installation)** |
-**[Usage](#usage)**
+**[Usage](#usage)** |
+**[License and authors](#license-and-authors)** |
+**[Donations](#donations)**
 
 # php-lock/lock
 
@@ -17,73 +19,131 @@ php-lock/lock follows semantic versioning. Read more on [semver.org][1].
 ----
 
 ## Requirements
+
  - PHP 7.1 or above
- - Optionally [nrk/predis](https://github.com/nrk/predis) to use the predis locks.
- - Optionally the [php-pcntl](http://php.net/manual/en/book.pcntl.php) extension to enable locking with flock without busy waiting in CLI scripts.
+ - 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.
 
 ----
 
 ## Installation
 
-Use [Composer](https://getcomposer.org/):
+### Composer
+
+To use this library through [composer][4], run the following terminal command
+inside your repository's root folder.
 
 ```sh
 composer require "malkusch/lock"
 ```
 
+As an alternative, you can directly add this library to your `composer.json`.
+
+``` json
+{
+    "require": {
+        "malkusch/lock": "^1.4"
+    }
+}
+```
+
+To use the newest (maybe unstable) version, use `dev-master` as the version in
+your `composer.json`.
+
+``` json
+{
+    "require": {
+        "malkusch/lock": "dev-master"
+    }
+}
+```
+
 ## Usage
 
-The package is in the namespace
-[`malkusch\lock`](http://malkusch.github.io/lock/api/namespace-malkusch.lock.html).
+This library uses the namespace `malkusch\lock`.
 
 ### Mutex
 
-The
-[`Mutex`](http://malkusch.github.io/lock/api/class-malkusch.lock.mutex.Mutex.html)
-provides the API for this library.
+The [`malkusch\lock\mutex\Mutex`][5] class is an abstract class and provides the
+base API for this library.
 
 #### Mutex::synchronized()
 
-[`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.
+[`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()`](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.
+[`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.
+
+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
+### 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)
@@ -95,19 +155,18 @@ The `Mutex` is an abstract class. You will have to choose an implementation:
 - [`MySQLMutex`](#mysqlmutex)
 - [`PgAdvisoryLockMutex`](#pgadvisorylockmutex)
 
+#### CASMutex
 
-##### 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) {
@@ -121,7 +180,7 @@ $mutex->synchronized(function () use ($memcached, $mutex, $amount) {
 });
 ```
 
-##### FlockMutex
+#### FlockMutex
 
 The **FlockMutex** is a lock implementation based on [`flock()`](http://php.net/manual/en/function.flock.php).
 
@@ -139,10 +198,10 @@ $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
+#### MemcachedMutex
 
 The **MemcachedMutex**
 is a spinlock implementation which uses the [`Memcached` API](http://php.net/manual/en/book.memcached.php).
@@ -164,7 +223,7 @@ $mutex->synchronized(function () use ($bankAccount, $amount) {
 });
 ```
 
-##### PHPRedisMutex
+#### PHPRedisMutex
 
 The **PHPRedisMutex** is the distributed lock implementation of [RedLock](http://redis.io/topics/distlock)
 which uses the [`phpredis` extension](https://github.com/phpredis/phpredis).
@@ -191,7 +250,7 @@ $mutex->synchronized(function () use ($bankAccount, $amount) {
 });
 ```
 
-##### PredisMutex
+#### PredisMutex
 
 The **PredisMutex** is the distributed lock implementation of [RedLock](http://redis.io/topics/distlock)
 which uses the [`Predis` API](https://github.com/nrk/predis).
@@ -212,7 +271,7 @@ $mutex->synchronized(function () use ($bankAccount, $amount) {
 });
 ```
 
-##### SemaphoreMutex
+#### SemaphoreMutex
 
 The **SemaphoreMutex**
 is a lock implementation based on [Semaphore](http://php.net/manual/en/ref.sem.php).
@@ -232,7 +291,7 @@ $mutex->synchronized(function () use ($bankAccount, $amount) {
 });
 ```
 
-##### TransactionalMutex
+#### TransactionalMutex
 
 The **TransactionalMutex**
 delegates the serialization to the DBS. The exclusive code is executed within
@@ -261,7 +320,7 @@ $mutex->synchronized(function () use ($pdo, $accountId, $amount) {
 });
 ```
 
-##### MySQLMutex
+#### MySQLMutex
 
 The **MySQLMutex** uses MySQL's 
 [`GET_LOCK`](https://dev.mysql.com/doc/refman/8.0/en/miscellaneous-functions.html#function_get-lock)
@@ -288,7 +347,7 @@ $mutex->synchronized(function () use ($bankAccount, $amount) {
 });
 ```
 
-##### PgAdvisoryLockMutex
+#### PgAdvisoryLockMutex
 
 The **PgAdvisoryLockMutex** uses PostgreSQL's 
 [advisory locking](https://www.postgresql.org/docs/9.4/static/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS)
@@ -324,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/
+[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