What the values look like

A type name says what comes back; it does not say what it looks like. Every block below was run against the built module and the output is what it answered, captured rather than written down. Generated by crates/subetha-pwrs/tools/Export-Examples.ps1.

A byte[] is shown as its length and its leading bytes, because the length is the part a reader cannot guess: a ring hands back a whole slot, payload then zeros, rather than only what was pushed.

Coordination

A lock hold, and what a refused one looks like

$l = New-SubEthaRWLock -Path 'C:\ipc\lock'
$w = $l.Write()
@(
  "Write()              -> " + (Show-Value $w)
  "Readers()            -> " + (Show-Value $l.Readers())
  "TryWrite() held      -> " + (Show-Value $l.TryWrite())
  "WriteFor(0.2) held   -> " + (Show-Value $l.WriteFor(0.2))
)
$w.Release()
$l.Dispose()

Answers:

Write()              -> [SubEtha.Hold]
  Write = $true
  Held = $true
Readers()            -> 0
TryWrite() held      -> $null
WriteFor(0.2) held   -> $null

Probabilistic

Sizing a filter and a sketch

@(
  "Measure-SubEthaBloomSize -Items 10000 -FalsePositiveRate 0.01"
  "  -> " + (Show-Value (Measure-SubEthaBloomSize -Items 10000 -FalsePositiveRate 0.01))
  "Measure-SubEthaSketchSize -Epsilon 0.01 -Delta 0.01"
  "  -> " + (Show-Value (Measure-SubEthaSketchSize -Epsilon 0.01 -Delta 0.01))
)

Answers:

Measure-SubEthaBloomSize -Items 10000 -FalsePositiveRate 0.01
  -> [SubEtha.BloomSize]
  Bits = 95851
  Hashes = 7
Measure-SubEthaSketchSize -Epsilon 0.01 -Delta 0.01
  -> [SubEtha.SketchSize]
  Depth = 5
  Width = 272

A bloom filter answering about membership

$sz = Measure-SubEthaBloomSize -Items 1000 -FalsePositiveRate 0.01
$b = New-SubEthaBloomFilter -Path 'C:\ipc\bloom' -Bits $sz.Bits -Hashes $sz.Hashes
$null = $b.Insert('alice')
@(
  "sizing               -> Bits " + (Show-Value $sz.Bits) + ', Hashes ' + (Show-Value $sz.Hashes)
  "Insert('alice')      -> (an item is a byte[] or a string, never a number)"
  "Contains('alice')    -> " + (Show-Value $b.Contains('alice'))
  "Contains('bob')      -> " + (Show-Value $b.Contains('bob'))
)
$b.Dispose()

Answers:

sizing               -> Bits 9586, Hashes 7
Insert('alice')      -> (an item is a byte[] or a string, never a number)
Contains('alice')    -> $true
Contains('bob')      -> $false

Rings

A ring: what Recv actually hands back

$r = New-SubEthaBroadcastRing -Path 'C:\ipc\bcast' -Capacity 8
$id = $r.RegisterConsumer()
$null = $r.Push('hello')
@(
  "PayloadSize          -> " + (Show-Value $r.PayloadSize)
  "Recv(id)             -> " + (Show-Value $r.Recv($id))
  "Recv(id) when empty  -> " + (Show-Value $r.Recv($id))
  "ProducerPosition()   -> " + (Show-Value $r.ProducerPosition())
  "ActiveConsumers()    -> " + (Show-Value $r.ActiveConsumers())
)
$r.UnregisterConsumer($id)
$r.Dispose()

Answers:

PayloadSize          -> 52
Recv(id)             -> byte[52] : 104, 101, 108, 108, 111, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ...
Recv(id) when empty  -> $null
ProducerPosition()   -> 1
ActiveConsumers()    -> 1

A full ring, and an empty one

$s = New-SubEthaSpscRing -Path 'C:\ipc\spsc' -Capacity 4
$pushed = for ($i = 0; $i -lt 6; $i++) { $s.Push([byte[]]@($i)) }
@(
  "Capacity             -> " + (Show-Value $s.Capacity)
  "six Push calls       -> " + (Show-Value $pushed)
  "Pop()                -> " + (Show-Value $s.Pop())
)
$s.Dispose()

Answers:

Capacity             -> 4
six Push calls       -> Object[], 6 item(s):
  $true
  $true
  $true
  $true
  ...
Pop()                -> byte[64] : 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ...

Shared state

An atomic, and what each operation answers

$a = New-SubEthaAtomic -Path 'C:\ipc\atom' -Init 10
@(
  "Store(40)            -> " + (Show-Value $a.Store(40))
  "FetchAdd(2)          -> " + (Show-Value $a.FetchAdd(2))
  "Load()               -> " + (Show-Value $a.Load())
  "Swap(99)             -> " + (Show-Value $a.Swap(99))
  "CompareExchange(99,1)-> " + (Show-Value $a.CompareExchange(99, 1))
  "Load()               -> " + (Show-Value $a.Load())
  "Path                 -> " + (Show-Value $a.Path)
)
$a.Dispose()

Answers:

Store(40)            -> $null
FetchAdd(2)          -> 40
Load()               -> 42
Swap(99)             -> 42
CompareExchange(99,1)-> 99
Load()               -> 1
Path                 -> 'C:\ipc\atom'

A map: keys and values are byte[] of the declared size

$m = New-SubEthaHashMap -Path 'C:\ipc\map' -Capacity 64 -KeySize 8 -ValueSize 8
$k = [BitConverter]::GetBytes([uint64]7)
$v = [BitConverter]::GetBytes([uint64]70)
$other = [BitConverter]::GetBytes([uint64]999)
@(
  "KeySize / ValueSize  -> " + (Show-Value $m.KeySize) + ' / ' + (Show-Value $m.ValueSize)
  "Insert(k, v)         -> " + (Show-Value $m.Insert($k, $v))
  "Insert(k, v) again   -> " + (Show-Value $m.Insert($k, $v))
  "Get(k)               -> " + (Show-Value $m.Get($k))
  "Get(absent)          -> " + (Show-Value $m.Get($other))
  "Contains(k)          -> " + (Show-Value $m.Contains($k))
  "Count()              -> " + (Show-Value $m.Count())
  "Remove(k)            -> " + (Show-Value $m.Remove($k))
  "Get(k) after remove  -> " + (Show-Value $m.Get($k))
)
$m.Dispose()

Answers:

KeySize / ValueSize  -> 8 / 8
Insert(k, v)         -> Inserted  [SubEtha.InsertOutcome]
Insert(k, v) again   -> Updated  [SubEtha.InsertOutcome]
Get(k)               -> byte[8] : 70, 0, 0, 0, 0, 0, 0, 0
Get(absent)          -> $null
Contains(k)          -> $true
Count()              -> 1
Remove(k)            -> byte[8] : 70, 0, 0, 0, 0, 0, 0, 0
Get(k) after remove  -> $null

Transports

What the module reports and what a certificate is

$cert = New-SubEthaSelfSignedCert -Name 'subetha-example'
@(
  "Get-SubEthaTransport -> " + (Show-Value (Get-SubEthaTransport))
  "New-SubEthaSelfSignedCert -Name 'subetha-example'"
  "  -> " + (Show-Value $cert)
)

Answers:

Get-SubEthaTransport -> Object[], 3 item(s):
  'sens'
  'tcp'
  'quic'
New-SubEthaSelfSignedCert -Name 'subetha-example'
  -> [SubEtha.Certificate]
  Name = 'subetha-example'
  Cert = Object[], 360 item(s):
    48
    130
    1
    100
    ...
  Key = Object[], 138 item(s):
    48
    129
    135
    2
    ...

Versioned

A pin, and the entries a scan answers

$vm = New-SubEthaVersionedMap -Path 'C:\ipc\vmap' -Capacity 64 -EpochsPath 'C:\ipc\vepochs'
$null = $vm.Insert(7, 70)
$null = $vm.Insert(9, 90)
$pin = $vm.Pin()
@(
  "Pin()                -> " + (Show-Value $pin)
  "pin.Epoch()          -> " + (Show-Value $pin.Epoch())
  "pin.Get(7)           -> " + (Show-Value $pin.Get(7))
  "pin.Scan(0,100,10)   -> " + (Show-Value $pin.Scan(0, 100, 10))
  "pin.ScanFrom(0,100,1)-> " + (Show-Value $pin.ScanFrom(0, 100, 1))
)
$pin.Release()
$vm.Dispose()

Answers:

Pin()                -> [SubEtha.MapPin]
pin.Epoch()          -> 2
pin.Get(7)           -> 70
pin.Scan(0,100,10)   -> Entry[], 2 item(s):
  [SubEtha.Entry]
    Key = 7
    Value = 70
  [SubEtha.Entry]
    Key = 9
    Value = 90
pin.ScanFrom(0,100,1)-> [SubEtha.Scan]
  Entries = [SubEtha.Entry]
    Key = 7
    Value = 70
  ResumeFrom = 7

The shm: drive Every cmdlet, in full