The shm: drive

Values under names, shared by every process of the user and outliving the session, reached the way $env: is reached:

$shm:greeting = 'hello'          # this process
$shm:greeting                    # any other process of the user: hello
$shm:greeting = $null            # gone, for everyone

PowerShell resolves $drive:name through a provider’s content operations, so the syntax needs no language change and works in PowerShell 7 and in Windows PowerShell 5.1 alike. The module registers the drive when it imports, as shm, with provider SubEthaShm. Behind it is a SharedNamedValues store: a lock-free map from each name to a block in a shared arena, with an epoch table that keeps a value readable while a reader who found it is still reading.

Files

The default drive’s files are shm.map, shm.arena and shm.epochs in the user’s SubEtha directory, the one the wait calibration caches in: subetha in the per-user temporary directory on Windows, $XDG_RUNTIME_DIR/subetha or subetha-<uid> in the temporary directory on Unix. They are created by the first import that finds them absent and attached to by every later one, and they stay until removed, so a value written by a process that has exited is still there. The store holds 4,096 names; its arena is 256 MiB, in blocks of 64 bytes to 32 MiB; a value of up to 16 MiB fits; 256 readers may hold a value at once across every process.

New-PSDrive -Name work -PSProvider SubEthaShm -Root C:\work opens the shm files in another directory, creating them when absent, and $work:name reaches them.

Values

Assigning $null removes the name, as $env: does. A name the drive does not hold reads as $null. Assigning several objects at once, $shm:list = 1, 2, 3, stores them as one array.

Names

A name is one path segment, of any length. Names are compared without regard to case and listed as they were first written: after $shm:Greeting = 'hi', $shm:GREETING reads hi and Get-ChildItem shm: shows Greeting. Two different names whose 128-bit hashes collide are refused with an error naming both, never merged.

Items

The drive is a container of leaves, so the item cmdlets work on it:

Concurrent writers and readers

A write takes a fresh block, fills it, swaps its handle into the map and publishes it; the block the swap replaced is retired at the next epoch. Two processes assigning one name at once each publish a whole value and the map holds the later swap’s; a reader sees one whole value or the other, never a mixture, and a reader that found the earlier one keeps reading it until its read is done. A writer that dies part way leaves nothing a user must repair: the next write that finds the arena full walks it with the map as its root set and takes back what no name reaches.

Errors

What a read costs

A $shm:name read goes through PowerShell’s provider path and the module’s bridge on every access, so it costs what a provider access costs, not what the store’s lookup costs. Measured by crates/subetha-pwrs/bench/ShmRead.ps1 on Windows 11 / Ryzen 9 7900X with 3.8 to 4.4 of 24 logical processors busy with other work, the median of five runs of 20,000 operations each, in microseconds per operation:

A read costs 30 to 47 microseconds, between 5 and 9 times an $env: read, and a write 170 to 210 microseconds: a write takes a block, fills it, swaps and publishes it and retires the block it replaced, behind the provider’s content-writer path. Read a value once into a local variable inside a loop rather than through $shm: on every iteration.