Skip to content

Commit a39d332

Browse files
committed
Add installation and usage of TypeErasedMailbox to README
1 parent 34bf99e commit a39d332

2 files changed

Lines changed: 51 additions & 14 deletions

File tree

README.md

Lines changed: 50 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ where, if an object isn't there, it has the option of *waiting for any
2323
desired length of time*..."
2424
> **iRMX 86™ NUCLEUS REFERENCE MANUAL** _Copyright @ 1980, 1981 Intel Corporation.
2525
26-
Since than I have used it in:
26+
Since then, I have used it in:
2727

2828
| OS | Language(s) |
2929
|:-----------:|:-----------:|
@@ -171,7 +171,7 @@ MailBox supports following operations:
171171

172172
## Intrusive mailbox
173173

174-
In order to be intrusive, Envelope should looks like
174+
In order to be intrusive, Envelope should look like
175175

176176
```zig
177177
pub const T = struct {
@@ -195,6 +195,43 @@ For curious:
195195
- [What does it mean for a data structure to be "intrusive"?](https://stackoverflow.com/questions/5004162/what-does-it-mean-for-a-data-structure-to-be-intrusive)
196196
- [libxev intrusive queue](https://github.com/mitchellh/libxev/blob/main/src/queue.zig#L4)
197197

198+
## TypeErased Mailbox
199+
200+
**TypeErased Mailbox** is an _intrusive_ mailbox that does **not know the message type**.
201+
202+
This implementation relies on [De-Genericify Linked Lists](https://ziglang.org/download/0.15.1/release-notes.html#De-Genericify-Linked-Lists) introduced in Zig 0.15.1.
203+
204+
In order to work with **_TypeErased Mailbox_** each message must embed a linked list node:
205+
```zig
206+
const Msg = struct {
207+
<your data>
208+
node: std.DoublyLinkedList.Node,
209+
};
210+
```
211+
212+
Example:
213+
```zig
214+
const Node = std.DoublyLinkedList.Node;
215+
const Mbx = mailbox.TypeErasedMailbox;
216+
217+
// Message envelope (intrusive)
218+
const Msg = struct {
219+
value: usize = 0,
220+
node: Node = .{},
221+
};
222+
223+
var mbox: Mbx = .{};
224+
225+
var msg: Msg = .{
226+
.value = 1,
227+
};
228+
229+
try mbox.send(&msg.node);
230+
231+
const node: *Node = try mbox.receive(1000);
232+
const rcvdMsg: *Msg = @fieldParentPtr("node", node);
233+
var shouldBeOne: usize = rcvdMsg.*.value;
234+
```
198235

199236
## Eat your own dog food
200237

@@ -211,20 +248,16 @@ With an existing Zig project, adding Mailbox to it is easy:
211248
1. Add mailbox to your `build.zig.zon`
212249
2. Add mailbox to your `build.zig`
213250

214-
To add mailbox to `build.zig.zon` simply run the following in your terminal:
251+
To add mailbox to `build.zig.zon` simply run the following from your project root:
215252

216253
```sh
217-
cd my-example-project
218254
zig fetch --save=mailbox git+https://github.com/g41797/mailbox
219255
```
220256

221257
and in your `build.zig.zon` you should find a new dependency like:
222258

223259
```zig
224260
.{
225-
.name = "My example project",
226-
.version = "0.0.1",
227-
228261
.dependencies = .{
229262
.mailbox = .{
230263
.url = "git+https://github.com/g41797/mailbox#3f794f34f5d859e7090c608da998f3b8856f8329",
@@ -237,6 +270,12 @@ and in your `build.zig.zon` you should find a new dependency like:
237270
}
238271
```
239272

273+
**NOTE**: If you still need version for zig 0.14.1 , run
274+
```sh
275+
zig fetch --save https://github.com/g41797/mailbox/archive/refs/tags/v0.0.12.tar.gz
276+
```
277+
278+
240279
Then, in your `build.zig`'s `build` function, add the following before
241280
`b.installArtifact(exe)`:
242281

@@ -248,9 +287,11 @@ Then, in your `build.zig`'s `build` function, add the following before
248287
249288
exe.root_module.addImport("mailbox", mailbox.module("mailbox"));
250289
```
251-
From then on, you can use the Mailbox package in your project.
290+
From then on, you can use the Mailbox package in your code:
291+
```zig
292+
const mailbox = @import("mailbox");
293+
```
252294

253-
See [build.zig of the real project](https://github.com/g41797/nats/blob/main/build.zig)
254295

255296
## License
256297
[MIT](LICENSE)

build.zig.zon

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,7 @@
44

55
.fingerprint = 0xa69fe20bb0079b78,
66

7-
// This is a [Semantic Version](https://semver.org/).
8-
// In a future version of Zig it will be used for package deduplication.
9-
.version = "0.0.0",
10-
11-
.minimum_zig_version = "0.14.0",
7+
.minimum_zig_version = "0.15.2",
128

139
.dependencies = .{},
1410

0 commit comments

Comments
 (0)