docs/start: C# update with retry, tested snippet; shared snippet check
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
97fb76ad37
commit
867ff992ad
3 changed files with 98 additions and 7 deletions
|
|
@ -16,7 +16,7 @@ this page.
|
|||
|
||||
| | CultCache | CultMath | Geometry | CultNet | CultMesh |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| **C#** | [first call, tested](#c-first-call) | [package](../../packages/cultmath/README.md); snippet not yet | [package](../../src/GameCult.Geometry/README.md); snippet not yet | [first call, tested](#c-cultnet-first-call); [package](../../src/GameCult.Networking) | [quickstart](../../src/GameCult.Mesh/docs/durable-node-quickstart.md); run by `scripts/verify-eve-getting-started.ps1` |
|
||||
| **C#** | [first call, tested](#c-first-call); [update, tested](#c-update-with-retry) | [package](../../packages/cultmath/README.md); snippet not yet | [package](../../src/GameCult.Geometry/README.md); snippet not yet | [first call, tested](#c-cultnet-first-call); [package](../../src/GameCult.Networking) | [quickstart](../../src/GameCult.Mesh/docs/durable-node-quickstart.md); run by `scripts/verify-eve-getting-started.ps1` |
|
||||
| **TypeScript** | [first call, tested](#typescript-first-call) | not yet | not yet | [first call, tested](#typescript-cultnet-first-call); [package](../../packages/cultnet-ts/README.md) | [package](../../packages/cultmesh-ts/README.md); snippet not yet; [recipe: two-client .io game](io-game.md), tested with two live clients, browser page not yet run |
|
||||
| **Rust** | [first call, tested](#rust-first-call) | [native core](../../packages/cultmath/native/cultmath-core); snippet not yet | not yet | [first call, tested](#rust-cultnet-first-call); [package](../../packages/cultnet-rs/README.md), [examples](../../packages/cultnet-rs/examples) | [package](../../packages/cultmesh-rs); snippet not yet |
|
||||
| **Python** | [first call, tested](#python-first-call) | not yet | not yet | [first call, tested](#python-cultnet-first-call); [package](../../packages/cultnet-py/README.md) | [package](../../packages/cultmesh-py/README.md); snippet not yet |
|
||||
|
|
@ -70,6 +70,37 @@ public static class FirstCall
|
|||
|
||||
`FirstCall.Run` is the call; a second test in that file fails if the block above stops matching it. More: `src/GameCult.Caching/README.md`.
|
||||
|
||||
## C# update with retry
|
||||
|
||||
Change a record you may not be the only one changing. `Update` reads the record, hands your function a private
|
||||
copy, and commits the result only if the record is still the one it read. If another writer got there first, it
|
||||
reads again and runs your function again, up to five times. The source is
|
||||
[`tests/GameCult.Caching.Tests/UpdateCallTests.cs`](../../tests/GameCult.Caching.Tests/UpdateCallTests.cs); the
|
||||
snippet reuses `Item` from the first call.
|
||||
|
||||
```csharp
|
||||
using GameCult.Caching;
|
||||
using GameCult.Caching.MessagePack;
|
||||
|
||||
public static class UpdateCall
|
||||
{
|
||||
public static CultUpdateResult<Item> Restock(string path, CultRecordKey key)
|
||||
{
|
||||
var cache = CultCacheMessagePack.Create(path);
|
||||
return cache.Update<Item>(key, item =>
|
||||
{
|
||||
item ??= new Item { Name = "Potion", Category = "Consumable" };
|
||||
item.Value += 10;
|
||||
return item;
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The write is durable when `Update` returns, with no `PushAll`. A lost race re-runs the function, so keep it free of
|
||||
side effects; when the attempts run out the result says `LostRace` instead of throwing. `UpsertAsync` plus
|
||||
`PushAll` is the blind opt-out: last writer wins.
|
||||
|
||||
## TypeScript first call
|
||||
|
||||
Same shape in TypeScript: the document is a name, a schema id and a `parse`-able schema (zod here),
|
||||
|
|
|
|||
|
|
@ -62,17 +62,23 @@ namespace GameCult.Caching.Tests
|
|||
}
|
||||
|
||||
[Test]
|
||||
public void DocsShowTheTestedSnippet()
|
||||
{
|
||||
var source = File.ReadAllText(SourcePath());
|
||||
const string begin = "// snippet:begin\n";
|
||||
var start = source.IndexOf(begin, StringComparison.Ordinal) + begin.Length;
|
||||
var snippet = source[start..source.IndexOf("// snippet:end\n", StringComparison.Ordinal)];
|
||||
var docs = File.ReadAllText(Path.Combine(Path.GetDirectoryName(SourcePath())!, "..", "..", "docs", "start", "README.md"));
|
||||
Assert.That(docs.Replace("\r\n", "\n"), Does.Contain("```csharp\n" + snippet + "```"),
|
||||
"docs/start/README.md no longer shows tests/GameCult.Caching.Tests/FirstCallTests.cs verbatim");
|
||||
}
|
||||
public void DocsShowTheTestedSnippet() => StartDocs.AssertShowsSnippet(SourcePath());
|
||||
|
||||
static string SourcePath([System.Runtime.CompilerServices.CallerFilePath] string path = "") => path;
|
||||
}
|
||||
|
||||
// docs/start/README.md shows each tested snippet verbatim: the region between snippet:begin and snippet:end of its source file.
|
||||
internal static class StartDocs
|
||||
{
|
||||
public static void AssertShowsSnippet(string sourcePath)
|
||||
{
|
||||
var source = File.ReadAllText(sourcePath).Replace("\r\n", "\n");
|
||||
const string begin = "// snippet:begin\n";
|
||||
var start = source.IndexOf(begin, StringComparison.Ordinal) + begin.Length;
|
||||
var snippet = source[start..source.IndexOf("// snippet:end\n", StringComparison.Ordinal)];
|
||||
var docs = File.ReadAllText(Path.Combine(Path.GetDirectoryName(sourcePath)!, "..", "..", "docs", "start", "README.md"));
|
||||
Assert.That(docs.Replace("\r\n", "\n"), Does.Contain("```csharp\n" + snippet + "```"),
|
||||
$"docs/start/README.md no longer shows {Path.GetFileName(sourcePath)} verbatim");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
54
tests/GameCult.Caching.Tests/UpdateCallTests.cs
Normal file
54
tests/GameCult.Caching.Tests/UpdateCallTests.cs
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
#nullable enable
|
||||
using System;
|
||||
using System.IO;
|
||||
using NUnit.Framework;
|
||||
|
||||
// snippet:begin
|
||||
using GameCult.Caching;
|
||||
using GameCult.Caching.MessagePack;
|
||||
|
||||
public static class UpdateCall
|
||||
{
|
||||
public static CultUpdateResult<Item> Restock(string path, CultRecordKey key)
|
||||
{
|
||||
var cache = CultCacheMessagePack.Create(path);
|
||||
return cache.Update<Item>(key, item =>
|
||||
{
|
||||
item ??= new Item { Name = "Potion", Category = "Consumable" };
|
||||
item.Value += 10;
|
||||
return item;
|
||||
});
|
||||
}
|
||||
}
|
||||
// snippet:end
|
||||
|
||||
namespace GameCult.Caching.Tests
|
||||
{
|
||||
// The C# update snippet that docs/start/README.md shows verbatim; it reuses FirstCallTests' Item.
|
||||
public class UpdateCallTests
|
||||
{
|
||||
[Test]
|
||||
public void RestockTwiceReadsTwenty()
|
||||
{
|
||||
var path = Path.Combine(Path.GetTempPath(), $"update-call-{Guid.NewGuid():N}.cc");
|
||||
try
|
||||
{
|
||||
var key = new CultRecordKey("potion");
|
||||
Assert.That(UpdateCall.Restock(path, key).Outcome, Is.EqualTo(CultUpdateOutcome.Updated));
|
||||
Assert.That(UpdateCall.Restock(path, key).Outcome, Is.EqualTo(CultUpdateOutcome.Updated));
|
||||
|
||||
using var reader = CultCacheMessagePack.Create(path);
|
||||
Assert.That(reader.Get<Item>(key)!.Value, Is.EqualTo(20));
|
||||
}
|
||||
finally
|
||||
{
|
||||
File.Delete(path);
|
||||
}
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void DocsShowTheTestedSnippet() => StartDocs.AssertShowsSnippet(SourcePath());
|
||||
|
||||
static string SourcePath([System.Runtime.CompilerServices.CallerFilePath] string path = "") => path;
|
||||
}
|
||||
}
|
||||
Loading…
Reference in a new issue