From 0e430cf2f4936e1fa15b2f18281fff50a2e2c08c Mon Sep 17 00:00:00 2001 From: Julien Ripouteau Date: Thu, 14 Mar 2024 12:34:56 +0100 Subject: [PATCH] doc: update doc accordingly --- docs/content/docs/api.md | 56 +++++++++++++++++-------------- docs/content/docs/introduction.md | 9 ++--- docs/content/docs/usage.md | 44 ++++++++++++------------ 3 files changed, 55 insertions(+), 54 deletions(-) diff --git a/docs/content/docs/api.md b/docs/content/docs/api.md index cf46e58..c607fb0 100644 --- a/docs/content/docs/api.md +++ b/docs/content/docs/api.md @@ -14,18 +14,38 @@ Acquire the lock. If the lock is already acquired, it will wait until it is rele ```ts const lock = verrou.createLock('key', '10s') -await lock.acquire() -await lock.acquire({ retry: { timeout: 1000 } }) -await lock.acquire({ retry: { timeout: '1s' } }) +const acquired = await lock.acquire() +const acquired = await lock.acquire({ retry: { timeout: 1000 } }) +const acquired = await lock.acquire({ retry: { timeout: '1s' } }) + +if (acquired) { + await criticalSection() +} ``` Accept an optional object with the following properties: - `retry`: An object with the following properties: - - `timeout`: The maximum time to wait for the lock to be acquired. If the timeout is reached, an `E_LOCK_TIMEOUT` error will be thrown. Defaults to `Infinity`. + - `timeout`: The maximum time to wait for the lock to be acquired. Defaults to `Infinity`. - `delay`: The delay in miliseconds between each retry. Defaults to `250` - `attempts`: The maximum number of attempts to acquire the lock. +`acquire` will return a boolean indicating if the lock was acquired or not + +### `acquireImmediately` + +Try to acquire the lock immediately ( without retrying ). If the lock is already acquired, it will return `false` immediately. + +```ts +import { errors } from '@verrou/core' + +const lock = verrou.createLock('key') +const acquired = await lock.acquireImmediately() +if (acquired) { + await criticalSection() +} +``` + ### `release` Release the lock. Note that only the lock owner can release the lock. @@ -39,45 +59,31 @@ await lock.release() ### `run` -Acquire the lock, run the callback, and release the lock. +Acquire the lock, run the callback, and release the lock. The method will return a tuple with the first value being a boolean indicating if the lock was acquired or not, and the second value being the result of the callback. ```ts const lock = verrou.createLock('key') -await lock.run(() => { +const [executed, result] = await lock.run(() => { // do something + return 'result' }) ``` + ### `runImmediately` -Same as `run`, but try to acquire the lock immediately ( without retrying ). If the lock is already acquired, it will throws a `E_LOCK_ALREADY_ACQUIRED` error. +Same as `run`, but try to acquire the lock immediately ( without retrying ). ```ts const lock = verrou.createLock('key') -await lock.runImmediately(async () => { +const [executed, result] = await lock.runImmediately(async () => { // do something + return 'result' }) ``` Accept an optional object with the same properties as `acquire`. -### `acquireImmediately` - -Try to acquire the lock immediately ( without retrying ). If the lock is already acquired, it will throws a `E_LOCK_ALREADY_ACQUIRED` error. - -```ts -import { errors } from '@verrou/core' - -const lock = verrou.createLock('key') -try { - await lock.acquireImmediately() -} catch (err) { - if (err instanceof E_LOCK_ALREADY_ACQUIRED) { - - } -} -``` - ### `isLocked` Check if the lock is acquired. diff --git a/docs/content/docs/introduction.md b/docs/content/docs/introduction.md index eda4fd8..f59e4fe 100644 --- a/docs/content/docs/introduction.md +++ b/docs/content/docs/introduction.md @@ -36,16 +36,13 @@ const verrou = new Verrou({ ```ts // title: Manual lock -import { Verrou, E_LOCK_TIMEOUT } from '@verrou/core' +import { Verrou } from '@verrou/core' const lock = verrou.createLock('my-resource') +const acquired = await lock.acquire() + try { - await lock.acquire() await doSomething() -} catch (error) { - if (error instanceof E_LOCK_TIMEOUT) { - // handle timeout - } } finally { await lock.release() } diff --git a/docs/content/docs/usage.md b/docs/content/docs/usage.md index 15edcbb..892cb87 100644 --- a/docs/content/docs/usage.md +++ b/docs/content/docs/usage.md @@ -38,13 +38,13 @@ import { verrou } from './verrou.js' const lock = verrou.createLock('my-resource', null) // We gonna wait for the lock to be acquired -await lock.acquire() - -// Do your critical code here -doSomething() +if (await lock.acquire()) { + // Do your critical code here + doSomething() -// Once you are done, release the lock. -await lock.release() + // Once you are done, release the lock. + await lock.release() +} ``` But we are still missing error handling. What if my `doSomething` method throws an error? The lock will never be released. To prevent this, always make sure to wrap your code with a try/catch/finaly block. @@ -53,10 +53,10 @@ But we are still missing error handling. What if my `doSomething` method throws import { verrou } from './verrou.js' const lock = verrou.createLock('my-resource', null) +const acquired = await lock.acquire() +if (!acquired) return 'Lock not acquired' try { - await lock.acquire() - // Do your critical code here doSomething() } catch (error) { @@ -115,29 +115,27 @@ await lock.acquire({ In general, you will either use the `retry.attempts` or `retry.timeout` options. -### Handling errors +### Handling lock acquisition failure -If ever you can't acquire a lock, an error will be thrown. You can catch it and handle it like this : +If ever you can't acquire a lock, `acquire` and `acquireImmediately` will return `false`. You can check if the lock was acquired by checking this value. ```ts import { errors } from '@verrou/core' -try { - await lock.acquire() -} catch (error) { - if (error instanceof errors.E_LOCK_TIMEOUT) { - // Handle the error - } +const acquired = await lock.acquire() +if (!acquired) { + return 'Lock not acquired' } +``` -await lock.run(async () => { - // Do your critical code here - doSomething() -}).catch(error => { - if (error instanceof errors.E_LOCK_TIMEOUT) { - // Handle the error - } +`run` and `runImmediately` methods will return a tuple with the first value being a boolean indicating if the lock was acquired or not. + +```ts +const [acquired, result] = await lock.run(async () => { + return doSomething() }) + +if (!acquired) return 'Lock not acquired' ``` ### Sharing a lock between multiple processes