bun-shared-memory 0.1.2 โ 0.1.3
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 +87 -10
- package/package.json +9 -3
package/README.md
CHANGED
|
@@ -1,4 +1,25 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# ๐ง bun-shared-memory
|
|
4
|
+
|
|
5
|
+
**Share data between Bun workers/threads using `SharedArrayBuffer`** โ zero-copy, 4-buffer architecture, Atomics-based synchronization.
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/bun-shared-memory)
|
|
8
|
+
[](https://www.npmjs.com/package/bun-shared-memory)
|
|
9
|
+
[](https://bundlephobia.com/package/bun-shared-memory)
|
|
10
|
+
|
|
11
|
+
[](https://github.com/Kapsonfire/bun-shared-memory)
|
|
12
|
+
[](https://github.com/Kapsonfire/bun-shared-memory)
|
|
13
|
+
[](https://github.com/Kapsonfire/bun-shared-memory/issues)
|
|
14
|
+
[](https://github.com/Kapsonfire/bun-shared-memory/blob/main/LICENSE)
|
|
15
|
+
|
|
16
|
+
[](https://bun.sh)
|
|
17
|
+
[](https://www.typescriptlang.org)
|
|
18
|
+
[](https://github.com/Kapsonfire/bun-shared-memory/actions)
|
|
19
|
+
|
|
20
|
+
</div>
|
|
21
|
+
|
|
22
|
+
---
|
|
2
23
|
|
|
3
24
|
A TypeScript library for the **Bun** runtime that enables sharing data between workers/threads using `SharedArrayBuffer`.
|
|
4
25
|
|
|
@@ -7,7 +28,42 @@ A TypeScript library for the **Bun** runtime that enables sharing data between w
|
|
|
7
28
|
> onward. Core shared-memory operations (including `SharedArrayBuffer.grow()`)
|
|
8
29
|
> work on earlier versions, but the automatic worker buffer-sharing does not.
|
|
9
30
|
|
|
10
|
-
##
|
|
31
|
+
## ๐ Real-world benchmark
|
|
32
|
+
|
|
33
|
+
`bun run bench:real` compares four methodologies for serving a "get user"
|
|
34
|
+
request through an [Elysia](https://elysiajs.com) mini API. Requests are built
|
|
35
|
+
by hand and passed directly to `app.fetch()` (no HTTP server); each methodology
|
|
36
|
+
is benchmarked sequentially with 4 workers. See
|
|
37
|
+
[`bench/real-world/README.md`](bench/real-world/README.md) for setup.
|
|
38
|
+
|
|
39
|
+
Measured on Linux (Bun 1.4.4, 100,000 requests per methodology, sorted by
|
|
40
|
+
speed; MySQL/Redis benchmarked over both TCP and Unix socket):
|
|
41
|
+
|
|
42
|
+
| Methodology | Transport | Requests | Elapsed (ms) | req/s | vs. shared |
|
|
43
|
+
|-------------|-----------|----------|--------------|------------|------------|
|
|
44
|
+
| `shared` | โ | 100,000 | 52 | 1,925,042 | โ |
|
|
45
|
+
| `sqlite` | โ | 100,000 | 187 | 535,469 | 3.6ร slower |
|
|
46
|
+
| `redis` | socket | 100,000 | 1,688 | 59,233 | 32.5ร slower |
|
|
47
|
+
| `mysql` | socket | 100,000 | 1,823 | 54,861 | 35.1ร slower |
|
|
48
|
+
| `redis` | tcp | 100,000 | 2,863 | 34,923 | 55.1ร slower |
|
|
49
|
+
| `mysql` | tcp | 100,000 | 3,281 | 30,476 | 63.2ร slower |
|
|
50
|
+
|
|
51
|
+
Shared memory is the fastest by a wide margin: ~3.6ร faster than a live SQLite
|
|
52
|
+
read and ~33โ63ร faster than live MySQL/Redis reads. Unix sockets are
|
|
53
|
+
significantly faster than TCP for MySQL/Redis (~1.7ร), but both remain far
|
|
54
|
+
slower than shared memory.
|
|
55
|
+
|
|
56
|
+
## โจ Features
|
|
57
|
+
|
|
58
|
+
- ๐ **Zero-copy** shared memory between workers/threads via `SharedArrayBuffer`
|
|
59
|
+
- ๐งฉ **4-buffer architecture** โ Index Table, DataTable, append-only StringTable, ArrayTable
|
|
60
|
+
- ๐ **Atomics-based synchronization** โ re-entrant `Mutex` + `Notifier`
|
|
61
|
+
- โก **Read & offset caches** โ lock-free fast path, cross-worker invalidation via version cells
|
|
62
|
+
- ๐งน **Reference counting & defragmentation** โ automatic memory reclamation
|
|
63
|
+
- ๐ช **Proxy-based API** โ `Shared()` with direct getter/setter access
|
|
64
|
+
- ๐งต **Automatic worker integration** โ no manual buffer serialization
|
|
65
|
+
|
|
66
|
+
## ๐ฆ Install
|
|
11
67
|
|
|
12
68
|
```sh
|
|
13
69
|
bun add bun-shared-memory
|
|
@@ -15,15 +71,18 @@ bun add bun-shared-memory
|
|
|
15
71
|
|
|
16
72
|
See [SPEC.md](./SPEC.md) for the full specification.
|
|
17
73
|
|
|
18
|
-
##
|
|
19
|
-
|
|
20
|
-
โ
**M3 โ Synchronization**: `Atomics`-based locking (`Mutex`) and notifications (`Notifier`) between workers, integrated into all shared-memory operations.
|
|
74
|
+
## ๐ Stats
|
|
21
75
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
76
|
+
| | |
|
|
77
|
+
|---|---|
|
|
78
|
+
| **Version** | [](https://www.npmjs.com/package/bun-shared-memory) |
|
|
79
|
+
| **Downloads / month** | [](https://www.npmjs.com/package/bun-shared-memory) |
|
|
80
|
+
| **Stars** | [](https://github.com/Kapsonfire/bun-shared-memory) |
|
|
81
|
+
| **Forks** | [](https://github.com/Kapsonfire/bun-shared-memory) |
|
|
82
|
+
| **Open issues** | [](https://github.com/Kapsonfire/bun-shared-memory/issues) |
|
|
83
|
+
| **Open PRs** | [](https://github.com/Kapsonfire/bun-shared-memory/pulls) |
|
|
84
|
+
| **License** | [](https://github.com/Kapsonfire/bun-shared-memory/blob/main/LICENSE) |
|
|
85
|
+
| **Language** | [](https://www.typescriptlang.org) |
|
|
27
86
|
|
|
28
87
|
## Data Types
|
|
29
88
|
|
|
@@ -335,3 +394,21 @@ per-worker LRU cache grows dynamically (configurable via `internCapacity` /
|
|
|
335
394
|
`internMax` on `SharedMemory`) and evicts least-recently-used entries once it
|
|
336
395
|
reaches capacity. Because the StringTable is append-only, cached references stay
|
|
337
396
|
valid for the lifetime of the buffer.
|
|
397
|
+
|
|
398
|
+
### Real-world benchmark
|
|
399
|
+
|
|
400
|
+
See [๐ Real-world benchmark](#-real-world-benchmark) at the top of this
|
|
401
|
+
README for the measured results.
|
|
402
|
+
|
|
403
|
+
## ๐ค Contributing
|
|
404
|
+
|
|
405
|
+
Contributions are welcome! Please open an issue or pull request.
|
|
406
|
+
|
|
407
|
+
- ๐ [Report a bug](https://github.com/Kapsonfire/bun-shared-memory/issues/new?labels=bug)
|
|
408
|
+
- ๐ก [Request a feature](https://github.com/Kapsonfire/bun-shared-memory/issues/new?labels=enhancement)
|
|
409
|
+
- ๐ [Browse open issues](https://github.com/Kapsonfire/bun-shared-memory/issues)
|
|
410
|
+
- ๐ [Open a pull request](https://github.com/Kapsonfire/bun-shared-memory/pulls)
|
|
411
|
+
|
|
412
|
+
## ๐ License
|
|
413
|
+
|
|
414
|
+
[MIT](./LICENSE) ยฉ [Kapsonfire](https://github.com/Kapsonfire)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "bun-shared-memory",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"description": "Share data between Bun workers/threads using SharedArrayBuffer (zero-copy, 4-buffer architecture, Atomics-based synchronization).",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"module": "index.ts",
|
|
@@ -18,7 +18,10 @@
|
|
|
18
18
|
"scripts": {
|
|
19
19
|
"typecheck": "bun check",
|
|
20
20
|
"test": "bun test",
|
|
21
|
-
"bench": "bun bench/bench.ts"
|
|
21
|
+
"bench": "bun bench/bench.ts",
|
|
22
|
+
"bench:real": "bun bench/real-world/run.ts",
|
|
23
|
+
"bench:real:seed": "bun bench/real-world/seed.ts",
|
|
24
|
+
"bench:real:mysql": "docker compose -f bench/real-world/docker-compose.yml up -d"
|
|
22
25
|
},
|
|
23
26
|
"keywords": [
|
|
24
27
|
"bun",
|
|
@@ -41,7 +44,10 @@
|
|
|
41
44
|
"access": "public"
|
|
42
45
|
},
|
|
43
46
|
"devDependencies": {
|
|
44
|
-
"@types/bun": "latest"
|
|
47
|
+
"@types/bun": "latest",
|
|
48
|
+
"elysia": "^1.4.30",
|
|
49
|
+
"ioredis": "^6.0.0",
|
|
50
|
+
"mysql2": "^3.24.6"
|
|
45
51
|
},
|
|
46
52
|
"peerDependencies": {
|
|
47
53
|
"typescript": "^7"
|