@zukhruf/async 0.8.31 → 0.8.32
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +24 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/ref-count.d.ts +20 -0
- package/dist/ref-count.d.ts.map +1 -0
- package/dist/ref-count.js +31 -0
- package/dist/ref-count.js.map +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @zukhruf/async
|
|
2
2
|
|
|
3
|
-
Helpers for code that waits for promises: `untilAborted` cancels a wait, `Latch` holds callers until something happened, `Future` gives callers the value or the failure of work that ends once, `Lock` lets one caller at a time do a thing, `Semaphore` lets a number of callers at a time do it, `WaitGroup` waits until the work in flight is done, `Cond` wakes every caller that waits now, `delay` waits a fixed time on a clock, `timeout` stops a wait after a time on a clock, `poll` calls an attempt again until it gives a value, `Backoff` gives a longer wait before each retry, and `ChangeWatcher` reads gauges again and again and tells which values changed. `@zukhruf/mutex`, `@zukhruf/single-flight` and `@zukhruf/election` use them.
|
|
3
|
+
Helpers for code that waits for promises: `untilAborted` cancels a wait, `Latch` holds callers until something happened, `Future` gives callers the value or the failure of work that ends once, `Lock` lets one caller at a time do a thing, `Semaphore` lets a number of callers at a time do it, `WaitGroup` waits until the work in flight is done, `RefCount` keeps the process alive only while work holds a handle, `Cond` wakes every caller that waits now, `delay` waits a fixed time on a clock, `timeout` stops a wait after a time on a clock, `poll` calls an attempt again until it gives a value, `Backoff` gives a longer wait before each retry, and `ChangeWatcher` reads gauges again and again and tells which values changed. `@zukhruf/mutex`, `@zukhruf/single-flight` and `@zukhruf/election` use them.
|
|
4
4
|
|
|
5
5
|
The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
|
|
6
6
|
|
|
@@ -169,6 +169,29 @@ await commands.wait({ signal });
|
|
|
169
169
|
|
|
170
170
|
A wait group holds a latch, and puts a new latch in its place each time the count reaches zero. See [ADR 0015](./docs/adr/0015-a-wait-group-counts-disposable-tokens-and-may-count-up-again-after-zero.md).
|
|
171
171
|
|
|
172
|
+
## Keep the process alive only while work holds a handle, with a ref count
|
|
173
|
+
|
|
174
|
+
A ref count keeps a handle of the event loop ref'd while work holds it, and unrefs it when no work does, so an idle client or socket does not keep the process alive. `hold` gives a token, and the ref count holds the handle until you dispose the token. The handle is anything with `ref()` and `unref()`: a socket, a server, a timer, an SSH client.
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
import { RefCount } from '@zukhruf/async';
|
|
178
|
+
|
|
179
|
+
const refs = new RefCount(client);
|
|
180
|
+
client.unref();
|
|
181
|
+
|
|
182
|
+
async function request(command: Command) {
|
|
183
|
+
using _request = refs.hold();
|
|
184
|
+
return await client.send(command);
|
|
185
|
+
}
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
- The first hold refs the handle. The dispose of the last hold unrefs it.
|
|
189
|
+
- A second dispose of one token changes nothing.
|
|
190
|
+
- The constructor leaves the handle as it is, ref'd or unref'd.
|
|
191
|
+
- What counts as work stays with you: a channel in use, a request that waits for its answer.
|
|
192
|
+
|
|
193
|
+
libuv keeps one flag for each handle, not a count, so code that shares one handle between many users counts on top of it, as Node does for the IPC channel of a child process (`refCounted` and `unrefCounted`). See [ADR 0017](./docs/adr/0017-a-ref-count-holds-a-handle-ref-d-while-work-holds-a-token.md).
|
|
194
|
+
|
|
172
195
|
## Wake every caller that waits now, with a cond
|
|
173
196
|
|
|
174
197
|
A cond wakes the callers that wait for a change of a state. `broadcast()` ends each wait that started before it. A cond carries no value, so a woken caller checks its state again, and waits again when the state has not changed.
|
package/dist/index.d.ts
CHANGED
|
@@ -9,6 +9,7 @@ export { poll, type PollOptions } from './poll.ts';
|
|
|
9
9
|
export { type AcquireOptions, Semaphore } from './semaphore.ts';
|
|
10
10
|
export { timeout, type Timeout, type TimeoutOptions } from './timeout.ts';
|
|
11
11
|
export { untilAborted } from './until-aborted.ts';
|
|
12
|
+
export { type Referable, RefCount } from './ref-count.ts';
|
|
12
13
|
export { WaitGroup } from './wait-group.ts';
|
|
13
14
|
export { type WaitOptions } from './wait-options.ts';
|
|
14
15
|
export { type Check } from './check.ts';
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,KAAK,cAAc,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,OAAO,GACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,KAAK,cAAc,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,SAAS,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,OAAO,GACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -9,6 +9,7 @@ export { poll } from "./poll.js";
|
|
|
9
9
|
export { Semaphore } from "./semaphore.js";
|
|
10
10
|
export { timeout } from "./timeout.js";
|
|
11
11
|
export { untilAborted } from "./until-aborted.js";
|
|
12
|
+
export { RefCount } from "./ref-count.js";
|
|
12
13
|
export { WaitGroup } from "./wait-group.js";
|
|
13
14
|
export {} from "./wait-options.js";
|
|
14
15
|
export {} from "./check.js";
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAoC,MAAM,cAAc,CAAC;AACzE,OAAO,EAA8B,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAqB,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAoB,MAAM,WAAW,CAAC;AACnD,OAAO,EAAuB,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,OAAO,EAAqC,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAoB,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAc,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,aAAa,GAGd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAe,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,KAAK,EAA8B,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAoC,MAAM,cAAc,CAAC;AACzE,OAAO,EAA8B,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAqB,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAoB,MAAM,WAAW,CAAC;AACnD,OAAO,EAAuB,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,OAAO,EAAqC,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAkB,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAoB,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAc,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,aAAa,GAGd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAe,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,KAAK,EAA8B,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/** A handle of the event loop that keeps the process alive while it is ref'd: a socket, a server, a timer, a client. libuv's `uv_ref` and `uv_unref`. */
|
|
2
|
+
export interface Referable {
|
|
3
|
+
ref(): unknown;
|
|
4
|
+
unref(): unknown;
|
|
5
|
+
}
|
|
6
|
+
/**
|
|
7
|
+
* Keeps a handle ref'd while work holds it, and unrefs it when no work does,
|
|
8
|
+
* so an idle handle does not keep the process alive. Each `hold` gives a
|
|
9
|
+
* token, and the count holds the token until a dispose. The first hold refs
|
|
10
|
+
* the handle and the dispose of the last unrefs it; the constructor leaves
|
|
11
|
+
* the handle as it is. Node's own `refCounted` and `unrefCounted` of the IPC
|
|
12
|
+
* channel of a child process work the same way.
|
|
13
|
+
*/
|
|
14
|
+
export declare class RefCount {
|
|
15
|
+
#private;
|
|
16
|
+
constructor(handle: Referable);
|
|
17
|
+
/** Holds the handle ref'd until the token is disposed: `using _work = refs.hold()`. */
|
|
18
|
+
hold(): Disposable;
|
|
19
|
+
}
|
|
20
|
+
//# sourceMappingURL=ref-count.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ref-count.d.ts","sourceRoot":"","sources":["../src/ref-count.ts"],"names":[],"mappings":"AAAA,yJAAyJ;AACzJ,MAAM,WAAW,SAAS;IACxB,GAAG,IAAI,OAAO,CAAC;IACf,KAAK,IAAI,OAAO,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,qBAAa,QAAQ;;gBAKP,MAAM,EAAE,SAAS;IAI7B,uFAAuF;IACvF,IAAI,IAAI,UAAU;CAYnB"}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Keeps a handle ref'd while work holds it, and unrefs it when no work does,
|
|
3
|
+
* so an idle handle does not keep the process alive. Each `hold` gives a
|
|
4
|
+
* token, and the count holds the token until a dispose. The first hold refs
|
|
5
|
+
* the handle and the dispose of the last unrefs it; the constructor leaves
|
|
6
|
+
* the handle as it is. Node's own `refCounted` and `unrefCounted` of the IPC
|
|
7
|
+
* channel of a child process work the same way.
|
|
8
|
+
*/
|
|
9
|
+
export class RefCount {
|
|
10
|
+
#handle;
|
|
11
|
+
/** The tokens that their holders have not disposed yet, so a second dispose of one token counts nothing. */
|
|
12
|
+
#holds = new Set();
|
|
13
|
+
constructor(handle) {
|
|
14
|
+
this.#handle = handle;
|
|
15
|
+
}
|
|
16
|
+
/** Holds the handle ref'd until the token is disposed: `using _work = refs.hold()`. */
|
|
17
|
+
hold() {
|
|
18
|
+
const token = {
|
|
19
|
+
[Symbol.dispose]: () => {
|
|
20
|
+
if (this.#holds.delete(token) && this.#holds.size === 0) {
|
|
21
|
+
this.#handle.unref();
|
|
22
|
+
}
|
|
23
|
+
},
|
|
24
|
+
};
|
|
25
|
+
this.#holds.add(token);
|
|
26
|
+
if (this.#holds.size === 1)
|
|
27
|
+
this.#handle.ref();
|
|
28
|
+
return token;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
//# sourceMappingURL=ref-count.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ref-count.js","sourceRoot":"","sources":["../src/ref-count.ts"],"names":[],"mappings":"AAMA;;;;;;;GAOG;AACH,MAAM,OAAO,QAAQ;IACV,OAAO,CAAY;IAC5B,4GAA4G;IACnG,MAAM,GAAG,IAAI,GAAG,EAAc,CAAC;IAExC,YAAY,MAAiB;QAC3B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,uFAAuF;IACvF,IAAI;QACF,MAAM,KAAK,GAAe;YACxB,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE;gBACrB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;oBACxD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;gBACvB,CAAC;YACH,CAAC;SACF,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvB,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC;YAAE,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;QAC/C,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zukhruf/async",
|
|
3
|
-
"version": "0.8.
|
|
3
|
+
"version": "0.8.32",
|
|
4
4
|
"description": "Helpers for code that waits for promises: cancel a wait when an AbortSignal aborts, hold callers on a one-shot latch that never rejects, and poll an attempt until it gives a value.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|