win-shared-memory 0.1.0

A library to easily access windows shared memory.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# Agent Guidelines

This is a Windows-only Rust library (`win-shared-memory`) that wraps Win32 named file-mapping
APIs into a typed, RAII interface. Read this before making changes.

## Build and check

```bash
cargo build
cargo test
cargo clippy -- -D warnings
cargo doc --no-deps
```

There is no cross-platform CI; the crate is `windows` only and will not compile on Linux/macOS.

## Architecture

All public API lives in `src/lib.rs`. The design is intentionally minimal — no modules, no
traits, no generics beyond `<T, Access>`.

Key types:

- `SharedMemoryLink<T, Access>` — the single public handle type.
- `ReadOnly` / `ReadWrite` — zero-sized access-mode markers; control which constructors and
  methods are available via separate `impl` blocks.
- `SharedMemoryError` — `thiserror`-derived enum; every variant that wraps a Win32 failure
  carries a `#[source] windows::core::Error`.

Constructor matrix:

| Method          | Marker      | Behaviour                                                             |
| --------------- | ----------- | --------------------------------------------------------------------- |
| `open`          | `ReadOnly`  | Opens existing mapping read-only                                      |
| `create`        | `ReadWrite` | Creates new mapping; errors with `AlreadyExists` if the name is taken |
| `get_or_create` | `ReadWrite` | Creates or opens existing mapping                                     |
| `open_existing` | `ReadWrite` | Opens existing mapping read-write                                     |

## Invariants to preserve

- **Handle leak safety**: if `MapViewOfFile` fails, the mapping handle must be closed before
  returning the error. The `map_view` helper handles this — don't bypass it.
- **`SetLastError(0)` before `CreateFileMappingW`** in `create`: required to distinguish a
  stale `ERROR_ALREADY_EXISTS` from a prior call versus one set by `CreateFileMappingW` itself.
  Do not remove this without careful reasoning.
- **`unsafe` on `get` and `get_mut`**: these must remain `unsafe` — they cannot enforce
  cross-process aliasing rules and callers must opt in explicitly.
- **`Send`/`Sync` bounds follow `T`**: the `unsafe impl` blocks are intentional; do not
  loosen or remove them.

## Dependencies

- `windows = "0.62"` with features `Win32_Foundation`, `Win32_Security`, `Win32_System_Memory`.
- `thiserror = "2"` for error derivation.

Do not add further dependencies without a strong reason — the crate is intentionally
low-dependency.

## What NOT to do

- Do not add Linux/macOS shims or cfg-gates; this crate is Windows-only by design.
- Do not introduce async, traits, or additional abstraction layers beyond the current design.
- Do not change the `unsafe` surface of `get`/`get_mut` to safe — the cross-process aliasing
  hazard is real and callers must acknowledge it explicitly.
- Do not change the coding style if not explicitly requested