Skip to content

Commit 596bba5

Browse files
prezaeiprezaei
authored
Consolidate website documentation and prevent stale deployed assets (#65)
1 parent 1c06eda commit 596bba5

26 files changed

Lines changed: 550 additions & 562 deletions

‎.github/workflows/website.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,4 @@ jobs:
2222
node --check src/website/site.js
2323
node --check src/website/theme.js
2424
node --check src/website/docs.js
25+
node --check src/website/protocol.js

‎README.md‎

Lines changed: 10 additions & 216 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
# Interprocess
44

5-
[Website](https://cloudtoid.com) · [Languages and packages](#languages) · [Quick start](#quick-start) · [Performance](#performance) · [Protocol v3](docs/protocol.md)
5+
[Website](https://cloudtoid.com) · [Documentation](https://cloudtoid.com/docs/) · [Languages and packages](#languages) · [Quick start](https://cloudtoid.com/docs/) · [Performance](#performance) · [Protocol v3](https://cloudtoid.com/docs/protocol/)
66

77
[![NuGet](https://img.shields.io/nuget/v/Cloudtoid.Interprocess?label=NuGet)](https://www.nuget.org/packages/Cloudtoid.Interprocess)
88
[![Rust](https://img.shields.io/crates/v/cloudtoid-interprocess?label=Rust)](https://crates.io/crates/cloudtoid-interprocess)
@@ -31,211 +31,20 @@ Interprocess is used internally by Microsoft.
3131

3232
| Language | Package | Setup and API guide |
3333
| --- | --- | --- |
34-
| Rust | [`cloudtoid-interprocess`](https://crates.io/crates/cloudtoid-interprocess) (Cargo) | [Rust core](src/rust/README.md) |
35-
| C / C++ | [C SDK](https://github.com/cloudtoid/interprocess/releases/latest); [`cloudtoid-interprocess-ffi`](https://crates.io/crates/cloudtoid-interprocess-ffi) (Cargo) | [C ABI, headers, and shared library](src/c/README.md) |
36-
| Python | Source build (PyPI pending); import `cloudtoid_interprocess` | [Python 3.9+](src/python/README.md) |
37-
| Node.js | [`@cloudtoid/interprocess`](https://www.npmjs.com/package/@cloudtoid/interprocess) (npm) | [Node.js 18+, JavaScript and TypeScript](src/node/README.md) |
38-
| Go | [`github.com/cloudtoid/interprocess/src/go/v3`](https://pkg.go.dev/github.com/cloudtoid/interprocess/src/go/v3) | [Go 1.24+, cgo, and the C SDK](src/go/README.md) |
39-
| .NET | [`Cloudtoid.Interprocess`][NuGet] (NuGet) | [.NET 10+, C# and dependency injection](src/dotnet/README.md) |
34+
| Rust | [`cloudtoid-interprocess`](https://crates.io/crates/cloudtoid-interprocess) (Cargo) | [Rust core](https://cloudtoid.com/docs/rust/) |
35+
| C / C++ | [C SDK](https://github.com/cloudtoid/interprocess/releases/latest); [`cloudtoid-interprocess-ffi`](https://crates.io/crates/cloudtoid-interprocess-ffi) (Cargo) | [C ABI, headers, and shared library](https://cloudtoid.com/docs/c/) |
36+
| Python | Source build (PyPI pending); import `cloudtoid_interprocess` | [Python 3.9+](https://cloudtoid.com/docs/python/) |
37+
| Node.js | [`@cloudtoid/interprocess`](https://www.npmjs.com/package/@cloudtoid/interprocess) (npm) | [Node.js 18+, JavaScript and TypeScript](https://cloudtoid.com/docs/node/) |
38+
| Go | [`github.com/cloudtoid/interprocess/src/go/v3`](https://pkg.go.dev/github.com/cloudtoid/interprocess/src/go/v3) | [Go 1.24+, cgo, and the C SDK](https://cloudtoid.com/docs/go/) |
39+
| .NET | [`Cloudtoid.Interprocess`][NuGet] (NuGet) | [.NET 10+, C# and dependency injection](https://cloudtoid.com/docs/dotnet/) |
4040

4141
Rust supplies the native engine; C, Python, Node.js, and Go use that engine. .NET has its own managed implementation of the same protocol. Node's platform binaries are companion `@cloudtoid/interprocess-*` packages; applications use the main package.
4242

4343
## Quick start
4444

45-
These examples send and receive in one process so both endpoints remain connected. In separate programs, use the same queue name, capacity, and shared directory, and keep at least one endpoint connected throughout the handoff. Each message goes to one subscriber.
45+
Choose a language in the table above for installation commands, a working example, and its API reference. Start with [queue concepts](https://cloudtoid.com/docs/concepts/) when connecting separate processes or mixing languages.
4646

47-
<details open>
48-
<summary>Rust</summary>
49-
50-
Run in your Cargo project. Requires Rust 1.87 or later.
51-
52-
```sh
53-
cargo add cloudtoid-interprocess
54-
```
55-
56-
```rust
57-
use cloudtoid_interprocess::{Options, Publisher, Subscriber};
58-
59-
let options = Options::new("example", 65536);
60-
let subscriber = Subscriber::open(&options)?;
61-
let publisher = Publisher::open(&options)?;
62-
publisher.try_send(b"hello")?;
63-
let message = subscriber.try_recv()?;
64-
println!("{message:?}");
65-
```
66-
67-
Endpoints close when dropped. Use `recv()` to wait indefinitely or `recv_timeout(Duration)` for a bounded wait.
68-
69-
</details>
70-
71-
<details>
72-
<summary>C / C++</summary>
73-
74-
macOS Apple Silicon example, using the GitHub CLI. For other platforms, choose darwin-x64, linux-arm64, linux-x64, or win32-x64 in both archive names. See the C guide for Windows setup.
75-
76-
```sh
77-
gh release download native-v3.0.1 --repo cloudtoid/interprocess --pattern "*-darwin-arm64.tar.gz"
78-
mkdir -p cloudtoid-sdk
79-
tar -xzf cloudtoid-interprocess-3.0.1-darwin-arm64.tar.gz -C cloudtoid-sdk --strip-components=1
80-
export PKG_CONFIG_PATH="$PWD/cloudtoid-sdk/lib/pkgconfig:$PKG_CONFIG_PATH"
81-
```
82-
83-
[Complete C SDK setup](src/c/README.md).
84-
85-
```c
86-
#include <interprocess.h>
87-
88-
int main(void) {
89-
cip_subscriber *subscriber = NULL;
90-
cip_publisher *publisher = NULL;
91-
if (cip_subscriber_open("example", NULL, 65536, &subscriber) != 1)
92-
return 1;
93-
if (cip_publisher_open("example", NULL, 65536, &publisher) != 1) {
94-
cip_subscriber_close(subscriber);
95-
return 1;
96-
}
97-
if (cip_try_send(publisher, (const uint8_t *)"hello", 5) == 1) {
98-
cip_buffer message;
99-
if (cip_receive(subscriber, 1000, &message) == 1)
100-
cip_buffer_free(message);
101-
}
102-
cip_publisher_close(publisher);
103-
cip_subscriber_close(subscriber);
104-
return 0;
105-
}
106-
```
107-
108-
Timeouts are milliseconds; free returned buffers with `cip_buffer_free`.
109-
110-
</details>
111-
112-
<details>
113-
<summary>Python</summary>
114-
115-
PyPI publishing is pending. Run in an activated Python 3.9+ virtual environment with Git, Rust, and a native linker installed.
116-
117-
```sh
118-
python -m pip install "git+https://github.com/cloudtoid/interprocess.git@native-v3.0.1#subdirectory=src/python"
119-
```
120-
121-
```python
122-
from cloudtoid_interprocess import Publisher, Subscriber
123-
124-
with Subscriber("example", 65536) as subscriber, Publisher("example", 65536) as publisher:
125-
if publisher.try_send(b"hello"):
126-
print(subscriber.receive(timeout=1.0))
127-
```
128-
129-
Context managers close endpoints. Timeouts are seconds; `receive()` waits indefinitely and permits Python signal handling.
130-
131-
</details>
132-
133-
<details>
134-
<summary>Node.js / TypeScript</summary>
135-
136-
Run in your Node.js project. Requires Node.js 18 or later; platform binaries install automatically.
137-
138-
```sh
139-
npm install @cloudtoid/interprocess
140-
```
141-
142-
```js
143-
import { Publisher, Subscriber } from '@cloudtoid/interprocess';
144-
145-
const subscriber = new Subscriber('example', 65536);
146-
const publisher = new Publisher('example', 65536);
147-
try {
148-
if (publisher.trySend(Buffer.from('hello'))) {
149-
const message = await subscriber.receive({
150-
signal: AbortSignal.timeout(1000)
151-
});
152-
console.log(message.toString());
153-
}
154-
} finally {
155-
publisher.close();
156-
subscriber.close();
157-
}
158-
```
159-
160-
CommonJS `require` is also supported. Async receive accepts an optional `AbortSignal`; empty queues wait on a one-millisecond timer without occupying libuv workers.
161-
162-
</details>
163-
164-
<details>
165-
<summary>Go</summary>
166-
167-
Install the C SDK first ([C guide](src/c/README.md)), then run in your Go module. Requires Go 1.24+, cgo enabled, a C compiler, and pkg-config.
168-
169-
```sh
170-
go get github.com/cloudtoid/interprocess/src/go/v3@latest
171-
```
172-
173-
```go
174-
package main
175-
176-
import (
177-
"context"
178-
"fmt"
179-
"github.com/cloudtoid/interprocess/src/go/v3"
180-
"time"
181-
)
182-
183-
func main() {
184-
options := interprocess.Options{Name: "example", Capacity: 65536}
185-
subscriber, err := interprocess.OpenSubscriber(options)
186-
if err != nil {
187-
panic(err)
188-
}
189-
defer subscriber.Close()
190-
publisher, err := interprocess.OpenPublisher(options)
191-
if err != nil {
192-
panic(err)
193-
}
194-
defer publisher.Close()
195-
196-
ctx, cancel := context.WithTimeout(context.Background(), time.Second)
197-
defer cancel()
198-
if sent, err := publisher.TrySend([]byte("hello")); err != nil {
199-
panic(err)
200-
} else if sent {
201-
message, err := subscriber.Receive(ctx)
202-
if err != nil {
203-
panic(err)
204-
}
205-
fmt.Println(string(message))
206-
}
207-
}
208-
```
209-
210-
Use `context.Context` for cancellation and deadlines. Install the C SDK before building the Go package.
211-
212-
</details>
213-
214-
<details>
215-
<summary>.NET / C#</summary>
216-
217-
```sh
218-
dotnet add package Cloudtoid.Interprocess
219-
```
220-
221-
```csharp
222-
using Cloudtoid.Interprocess;
223-
224-
var factory = new QueueFactory();
225-
var options = new QueueOptions("example", 65536);
226-
using var subscriber = factory.CreateSubscriber(options);
227-
using var publisher = factory.CreatePublisher(options);
228-
using var cancellation = new CancellationTokenSource(TimeSpan.FromSeconds(1));
229-
230-
if (publisher.TryEnqueue("hello"u8)) {
231-
var message = subscriber.Dequeue(cancellation.Token);
232-
Console.WriteLine(System.Text.Encoding.UTF8.GetString(message.Span));
233-
}
234-
```
235-
236-
Blocking receives accept a `CancellationToken`. For dependency injection, register `services.AddInterprocessQueue()` and resolve `IQueueFactory`. See the [.NET package guide](src/dotnet/README.md) and [publisher/subscriber samples](src/dotnet/Sample/).
237-
238-
</details>
47+
Queues are transient: keep at least one publisher or subscriber connected throughout the handoff. Once all endpoints are gone, unread messages are lost and reopening the queue starts fresh.
23948

24049
## Faster with v3
24150

@@ -251,15 +60,6 @@ Measured with .NET 10. [Original results and comparison harness](https://github.
25160

25261
Upgrade existing v1/v2 applications together: drain the queue, stop all participants, and reopen a fresh queue using v3. All participants sharing a queue must use the same protocol.
25362

254-
## Queue behavior
255-
256-
- Use the same name, capacity, and storage path in every participant. Queue names must be unique even across different paths; Windows uses the name and ignores the path.
257-
- Each queue supports **2,048 connected publisher objects**. Slots are reused after disposal or confirmed process exit. The publisher table adds **256 KiB** plus 256 bytes of header/alignment storage; `Capacity` is the message-buffer size.
258-
- On Windows, use the same user session for all participants. Cross-account connections are not supported.
259-
- The queue is transient and remains available while any publisher or subscriber is connected. Once all are gone, unread messages are lost. Reopening the same name creates a fresh, empty queue. Keep a subscriber connected before a short-lived publisher exits. Dispose participants when finished.
260-
- A paused live participant keeps ownership. Recovery can reclaim abandoned work after a process exits, but may discard queued messages, including completed messages behind an unfinished reservation. This is an IPC queue, not durable storage.
261-
- Supply a destination buffer large enough for the message. A smaller buffer consumes the message and returns only the bytes that fit.
262-
26363
## Performance
26464

26565
Send means enqueue; receive means dequeue. A send + receive operation includes both operations; a send-only measurement excludes receiving. All benchmarks keep publishers and subscribers connected throughout measurement, with queue creation and cleanup outside the timed work.
@@ -324,13 +124,7 @@ Measured September 13, 2026, on an **Apple M5 Max**, Ubuntu 24.04 ARM64 VM (Lima
324124

325125
Same .NET workloads and allocation conventions as the Mac suite. Two launches and eight measured iterations; single-thread runs used one pinned vCPU and 20 warmups (200 for send-only), while concurrent runs used all four vCPUs and three warmups. [.NET benchmark source](src/dotnet/Interprocess.Benchmark/) · [Original reports](https://github.com/cloudtoid/interprocess/tree/95c512672d580dd836ba2554cd1f78c0c3826f6c/docs/benchmarks/2026-09-13).
326126

327-
[Protocol v3](docs/protocol.md) documents the complete shared-memory format and synchronization rules. [Interoperability tests](tests/interop/README.md) exercise every publisher/subscriber language pair and mixed-language concurrent delivery across participant crashes.
328-
329-
## Implementation Notes
330-
331-
Messages travel through a shared, circular memory-mapped buffer. Coalesced notifications reduce operating-system calls while keeping blocked subscribers responsive. Rust and .NET blocking readers also retry after five-millisecond waits when notifications are missed; bindings follow their documented waiting and cancellation behavior. Cross-process wakeups use named semaphores, with POSIX implementations on [Linux](src/dotnet/Interprocess/Semaphore/Linux/Interop.cs) and [macOS](src/dotnet/Interprocess/Semaphore/MacOS/Interop.cs).
332-
333-
Positions advance monotonically while the physical buffer wraps. Before the queue reaches `INT64_MAX` bytes reserved or `INT32_MAX` participant registrations over its lifetime, drain it and move all participants to a fresh queue.
127+
[Protocol v3](https://cloudtoid.com/docs/protocol/) documents the complete shared-memory format and synchronization rules. [Interoperability tests](tests/interop/README.md) exercise every publisher/subscriber language pair and mixed-language concurrent delivery across participant crashes.
334128

335129
## How to Contribute
336130

0 commit comments

Comments
 (0)