diff --git a/README.md b/README.md
index 0bb608d..1e078c5 100644
--- a/README.md
+++ b/README.md
@@ -1,40 +1,63 @@
-
-
-
-
-
-
-
-# RoadRunner locks
-
-[](https://packagist.org/packages/roadrunner-php/lock)
-[](https://packagist.org/packages/roadrunner-php/lock)
-[](https://github.com/roadrunner-php/lock/actions)
-[](https://github.com/roadrunner-php/lock/actions)
-[](https://codecov.io/gh/roadrunner-php/lock/)
-[](https://packagist.org/packages/roadrunner-php/lock)
-
-
-This package provides a PHP integration package for the RoadRunner Lock plugin, which allows for easy management of
-distributed locks in PHP applications. The plugin provides a fast, lightweight, and reliable way to acquire, release,
-and manage locks in a distributed environment, making it ideal for use in high-traffic web applications and
-microservices.
-
-## Requirements
+
+
+
+
+This package is a PHP client for the [RoadRunner Lock plugin](https://docs.roadrunner.dev/docs/plugins/locks). It lets
+your workers acquire, release and manage exclusive and shared (read) locks on named resources, shared across all
+processes connected to the RoadRunner server.
+
+## Get Started
+
+### Requirements
Make sure that your server is configured with following PHP version and extensions:
- PHP 8.1+
-## Installation
-
-You can install the package via composer:
+### Installation
```bash
composer require roadrunner-php/lock
```
-## Usage
+[](https://packagist.org/packages/roadrunner-php/lock)
+[](https://packagist.org/packages/roadrunner-php/lock)
+[](LICENSE)
+[](https://packagist.org/packages/roadrunner-php/lock/stats)
+
+### Configuration
+
+The client talks to RoadRunner over RPC, so enable the `rpc` section in `.rr.yaml`. The Lock plugin uses the in-memory
+backend by default; see the [plugin documentation](https://docs.roadrunner.dev/docs/plugins/locks) to share locks
+between RoadRunner instances through Redis.
+
+```yaml
+version: "3"
+
+rpc:
+ listen: tcp://127.0.0.1:6001
+```
+
+### Your First Lock
+
+Create a `Lock` instance with an RPC connection to the RoadRunner server, then acquire and release a lock:
```php
use RoadRunner\Lock\Lock;
@@ -43,8 +66,22 @@ use Spiral\Goridge\RPC\RPC;
require __DIR__ . '/vendor/autoload.php';
$lock = new Lock(RPC::create('tcp://127.0.0.1:6001'));
+
+$id = $lock->lock('pdf:create', ttl: 10);
+if ($id === false) {
+ // The resource is locked by another process
+ return;
+}
+
+try {
+ // Do the work
+} finally {
+ $lock->release('pdf:create', $id);
+}
```
+## Usage
+
### Acquire lock
Locks a resource so that it can be accessed by one process at a time.
@@ -124,14 +161,15 @@ $lock->forceRelease('pdf:create');
### Check lock
-Checks if a resource is currently locked and returns information about the lock.
+Checks if a resource is currently locked. Pass a lock id to check whether that particular lock is held.
```php
-$status = $lock->exists('pdf:create');
-if($status) {
- // Lock exists
-} else {
- // Lock not exists
+if ($lock->exists('pdf:create')) {
+ // The resource is locked
+}
+
+if ($lock->exists('pdf:create', $id)) {
+ // The lock with this id is held
}
```
@@ -140,7 +178,7 @@ if($status) {
Updates the time-to-live (TTL) for the locked resource.
```php
-// Add 10 seconds to lock ttl
+// Set the lock ttl to 10 seconds
$lock->updateTTL('pdf:create', $id, 10);
// or
$lock->updateTTL('pdf:create', $id, new \DateInterval('PT10S'));
@@ -155,7 +193,3 @@ composer test
## Credits
- [butschster](https://github.com/butschster)
-
-## License
-
-The MIT License (MIT). Please see [License File](LICENSE) for more information.
-
-This package provides a PHP integration package for the RoadRunner Lock plugin, which allows for easy management of
-distributed locks in PHP applications. The plugin provides a fast, lightweight, and reliable way to acquire, release,
-and manage locks in a distributed environment, making it ideal for use in high-traffic web applications and
-microservices.
-
-## Requirements
+