Skip to content

Commit

Permalink
doc: update doc accordingly
Browse files Browse the repository at this point in the history
  • Loading branch information
Julien-R44 committed Mar 14, 2024
1 parent 94ce278 commit 1281cb5
Showing 3 changed files with 55 additions and 54 deletions.
56 changes: 31 additions & 25 deletions docs/content/docs/api.md
Original file line number Diff line number Diff line change
@@ -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.
9 changes: 3 additions & 6 deletions docs/content/docs/introduction.md
Original file line number Diff line number Diff line change
@@ -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()
}
44 changes: 21 additions & 23 deletions docs/content/docs/usage.md
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 1281cb5

Please sign in to comment.