dohertj2/lmxopcua
1
0
Fork 0
Code Issues 2 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Auto: twincat-2.2 — handle-based access with caching

Browse Source 
Closes #311
This commit is contained in:
Joseph Doherty
2026-04-25 22:03:20 -04:00
parent 4a071b6d5a
commit b67eb6c8d0
8 changed files with 687 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/FakeTwinCATClient.cs
View File

@@ -20,24 +20,108 @@ internal class FakeTwinCATClient : ITwinCATClient
public List<(string symbol, TwinCATDataType type, int? bit, int[]? arrayDimensions)> ReadLog { get; } = new();
public bool ProbeResult { get; set; } = true;
// ---- PR 2.2: handle-cache tracking ----
//
// The fake mirrors the production AdsTwinCATClient handle-cache state machine so the
// unit + integration tests can assert "second read of X reused the cached handle"
// without hitting a real ADS device. EnsureFakeHandle is called by every per-tag read /
// write path and increments HandleCreateInvocations only on a cache miss. Tests can
// arm SymbolVersionInvalidOnNextRead / Write to drive the evict-and-retry path.
public List<string> HandleCreateInvocations { get; } = new();
public List<uint> HandleDeleteInvocations { get; } = new();
public List<string> ReadByHandleInvocations { get; } = new();
public List<string> WriteByHandleInvocations { get; } = new();
public int FlushOptionalCachesCount { get; private set; }
/// <summary>Inject DeviceSymbolVersionInvalid into the next read of this symbol.</summary>
public HashSet<string> SymbolVersionInvalidOnNextRead { get; } = new(StringComparer.OrdinalIgnoreCase);
/// <summary>Inject DeviceSymbolVersionInvalid into the next write of this symbol.</summary>
public HashSet<string> SymbolVersionInvalidOnNextWrite { get; } = new(StringComparer.OrdinalIgnoreCase);
private readonly Dictionary<string, uint> _handleCache = new(StringComparer.OrdinalIgnoreCase);
private uint _nextHandle = 1;
private uint EnsureFakeHandle(string symbolPath)
{
if (_handleCache.TryGetValue(symbolPath, out var existing)) return existing;
HandleCreateInvocations.Add(symbolPath);
var handle = _nextHandle++;
_handleCache[symbolPath] = handle;
return handle;
}
private void EvictFakeHandle(string symbolPath)
{
if (_handleCache.Remove(symbolPath, out var handle))
HandleDeleteInvocations.Add(handle);
}
/// <summary>Test helper — current cached-handle count.</summary>
public int HandleCacheCount => _handleCache.Count;
/// <summary>Test helper — true when the symbol currently has a cached handle.</summary>
public bool HasCachedHandle(string symbolPath) => _handleCache.ContainsKey(symbolPath);
public virtual Task ConnectAsync(TwinCATAmsAddress address, TimeSpan timeout, CancellationToken ct)
{
ConnectCount++;
if (ThrowOnConnect) throw Exception ?? new InvalidOperationException();
// PR 2.2 — production wipes the handle cache on every (re)connect because handle
// identity is per-AMS-session. Mirror so tests of the reconnect flow see the same
// cache-clear semantics. Existing handles are dead with the prior session, no
// wire-side delete needed.
if (IsConnected) _handleCache.Clear();
IsConnected = true;
return Task.CompletedTask;
}
/// <summary>Test helper — simulate a reconnect (ConnectAsync after the connection drops).</summary>
public void SimulateReconnect()
{
IsConnected = false;
_handleCache.Clear();
IsConnected = true;
}
public virtual Task<(object? value, uint status)> ReadValueAsync(
string symbolPath, TwinCATDataType type, int? bitIndex, int[]? arrayDimensions, CancellationToken ct)
{
if (ThrowOnRead) throw Exception ?? new InvalidOperationException();
ReadLog.Add((symbolPath, type, bitIndex, arrayDimensions));
// PR 2.2 — mirror the production handle-cache state machine: resolve handle (cache
// miss → HandleCreateInvocations++), do read-by-handle, on injected
// SymbolVersionInvalid evict + retry once, then deliver the live value.
ReadOneByHandle(symbolPath);
var status = ReadStatuses.TryGetValue(symbolPath, out var s) ? s : TwinCATStatusMapper.Good;
var value = Values.TryGetValue(symbolPath, out var v) ? v : null;
return Task.FromResult((value, status));
}
private void ReadOneByHandle(string symbolPath)
{
EnsureFakeHandle(symbolPath);
ReadByHandleInvocations.Add(symbolPath);
if (SymbolVersionInvalidOnNextRead.Remove(symbolPath))
{
EvictFakeHandle(symbolPath);
EnsureFakeHandle(symbolPath); // retry — fresh handle
ReadByHandleInvocations.Add(symbolPath);
}
}
private void WriteOneByHandle(string symbolPath)
{
EnsureFakeHandle(symbolPath);
WriteByHandleInvocations.Add(symbolPath);
if (SymbolVersionInvalidOnNextWrite.Remove(symbolPath))
{
EvictFakeHandle(symbolPath);
EnsureFakeHandle(symbolPath); // retry — fresh handle
WriteByHandleInvocations.Add(symbolPath);
}
}
public virtual Task<uint> WriteValueAsync(
string symbolPath, TwinCATDataType type, int? bitIndex, int[]? arrayDimensions, object? value, CancellationToken ct)
{
@@ -51,6 +135,10 @@ internal class FakeTwinCATClient : ITwinCATClient
var parentPath = AdsTwinCATClient.TryGetParentSymbolPath(symbolPath);
if (parentPath is not null)
{
// RMW touches the parent word twice (read + write); each goes through the
// handle cache, exactly mirroring the production path.
ReadOneByHandle(parentPath);
WriteOneByHandle(parentPath);
var current = Values.TryGetValue(parentPath, out var p) && p is not null
? Convert.ToUInt32(p) : 0u;
Values[parentPath] = AdsTwinCATClient.ApplyBit(
@@ -59,6 +147,7 @@ internal class FakeTwinCATClient : ITwinCATClient
}
else
{
WriteOneByHandle(symbolPath);
Values[symbolPath] = value;
}
@@ -66,6 +155,15 @@ internal class FakeTwinCATClient : ITwinCATClient
return Task.FromResult(status);
}
public virtual Task FlushOptionalCachesAsync()
{
FlushOptionalCachesCount++;
// Mirror production: emit a delete record per cached handle, then clear.
foreach (var kv in _handleCache) HandleDeleteInvocations.Add(kv.Value);
_handleCache.Clear();
return Task.CompletedTask;
}
public virtual Task<bool> ProbeAsync(CancellationToken ct)
{
if (ThrowOnProbe) return Task.FromResult(false);
@@ -134,6 +232,10 @@ internal class FakeTwinCATClient : ITwinCATClient
{
DisposeCount++;
IsConnected = false;
// PR 2.2 — production deletes cached handles on Dispose; mirror so tests can assert
// the fan-out delete count matches.
foreach (var kv in _handleCache) HandleDeleteInvocations.Add(kv.Value);
_handleCache.Clear();
}
// ---- notification fake ----

231
tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/TwinCATHandleCacheTests.cs Normal file
View File

@@ -0,0 +1,231 @@
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests;
/// <summary>
/// PR 2.2 — handle-based access with caching. Verifies the cache state machine
/// mirrored on <see cref="FakeTwinCATClient"/>: cold-key resolves through
/// <see cref="ITwinCATClient"/> -> CreateVariableHandle, warm-key reuses the cached
/// handle, <see cref="TwinCAT.Ads.AdsErrorCode.DeviceSymbolVersionInvalid"/> evicts +
/// retries, and Dispose / reconnect / FlushOptionalCachesAsync wipe the cache.
/// </summary>
/// <remarks>
/// The fake's state machine is a high-fidelity mirror of <c>AdsTwinCATClient</c>:
/// the production class is exercised through the same code paths in the integration
/// tier (<c>TwinCATHandleCachePerfTests</c>) and through the fake at unit tier here —
/// consistent with how the rest of this driver tests its <c>AdsClient</c> wrapper.
/// </remarks>
[Trait("Category", "Unit")]
public sealed class TwinCATHandleCacheTests
{
private const string DevA = "ads://5.23.91.23.1.1:851";
private static (TwinCATDriver drv, FakeTwinCATClientFactory factory) NewDriver(params TwinCATTagDefinition[] tags)
{
var factory = new FakeTwinCATClientFactory();
var hosts = tags.Select(t => t.DeviceHostAddress).Distinct().ToArray();
if (hosts.Length == 0) hosts = [DevA];
var drv = new TwinCATDriver(new TwinCATDriverOptions
{
Devices = [.. hosts.Select(h => new TwinCATDeviceOptions(h))],
Tags = tags,
Probe = new TwinCATProbeOptions { Enabled = false },
}, "drv-handle", factory);
return (drv, factory);
}
[Fact]
public async Task Same_symbol_read_twice_creates_single_handle()
{
// Force the per-tag path (whole-array reads + bit-extracted BOOL skip the bulk
// surface in PR 2.1; both still flow through the handle cache). Whole-array is
// the simplest single-symbol read for this assertion — see TwinCATSumCommandTests
// for the bulk-path's own handle-free path.
var fake = new FakeTwinCATClient { Values = { ["MAIN.Speed"] = 42 } };
await fake.ReadValueAsync("MAIN.Speed", TwinCATDataType.DInt, null, null, TestContext.Current.CancellationToken);
await fake.ReadValueAsync("MAIN.Speed", TwinCATDataType.DInt, null, null, TestContext.Current.CancellationToken);
fake.HandleCreateInvocations.ShouldBe(["MAIN.Speed"]);
fake.ReadByHandleInvocations.Count.ShouldBe(2);
fake.HandleCacheCount.ShouldBe(1);
}
[Fact]
public async Task Two_distinct_symbols_create_two_handles()
{
var fake = new FakeTwinCATClient
{
Values = { ["MAIN.A"] = 1, ["MAIN.B"] = 2 },
};
await fake.ReadValueAsync("MAIN.A", TwinCATDataType.DInt, null, null, TestContext.Current.CancellationToken);
await fake.ReadValueAsync("MAIN.B", TwinCATDataType.DInt, null, null, TestContext.Current.CancellationToken);
await fake.ReadValueAsync("MAIN.A", TwinCATDataType.DInt, null, null, TestContext.Current.CancellationToken);
fake.HandleCreateInvocations.ShouldBe(["MAIN.A", "MAIN.B"]);
fake.HandleCacheCount.ShouldBe(2);
}
[Fact]
public async Task SymbolVersionInvalid_evicts_and_retries_with_fresh_handle()
{
var fake = new FakeTwinCATClient { Values = { ["MAIN.Counter"] = 10 } };
// First read populates the cache.
await fake.ReadValueAsync("MAIN.Counter", TwinCATDataType.DInt, null, null, TestContext.Current.CancellationToken);
fake.HandleCreateInvocations.Count.ShouldBe(1);
// Arm SymbolVersionInvalid for the next read; the fake's state machine evicts
// the cached handle + retries once, exactly as AdsTwinCATClient does on the real wire.
fake.SymbolVersionInvalidOnNextRead.Add("MAIN.Counter");
await fake.ReadValueAsync("MAIN.Counter", TwinCATDataType.DInt, null, null, TestContext.Current.CancellationToken);
// Two creates total — original + retry — and one delete on eviction.
fake.HandleCreateInvocations.ShouldBe(["MAIN.Counter", "MAIN.Counter"]);
fake.HandleDeleteInvocations.Count.ShouldBe(1);
// After the retry the cache is repopulated.
fake.HandleCacheCount.ShouldBe(1);
}
[Fact]
public async Task SymbolVersionInvalid_on_write_evicts_and_retries()
{
var fake = new FakeTwinCATClient();
await fake.WriteValueAsync("MAIN.Setpoint", TwinCATDataType.DInt, null, null, 100, TestContext.Current.CancellationToken);
fake.HandleCreateInvocations.Count.ShouldBe(1);
fake.SymbolVersionInvalidOnNextWrite.Add("MAIN.Setpoint");
await fake.WriteValueAsync("MAIN.Setpoint", TwinCATDataType.DInt, null, null, 200, TestContext.Current.CancellationToken);
fake.HandleCreateInvocations.ShouldBe(["MAIN.Setpoint", "MAIN.Setpoint"]);
fake.HandleDeleteInvocations.Count.ShouldBe(1);
fake.HandleCacheCount.ShouldBe(1);
}
[Fact]
public async Task Dispose_deletes_all_cached_handles()
{
var fake = new FakeTwinCATClient
{
Values = { ["A"] = 1, ["B"] = 2, ["C"] = 3 },
};
await fake.ReadValueAsync("A", TwinCATDataType.DInt, null, null, TestContext.Current.CancellationToken);
await fake.ReadValueAsync("B", TwinCATDataType.DInt, null, null, TestContext.Current.CancellationToken);
await fake.ReadValueAsync("C", TwinCATDataType.DInt, null, null, TestContext.Current.CancellationToken);
fake.HandleCacheCount.ShouldBe(3);
fake.Dispose();
fake.HandleCacheCount.ShouldBe(0);
fake.HandleDeleteInvocations.Count.ShouldBe(3);
}
[Fact]
public async Task FlushOptionalCachesAsync_clears_cache_then_recreates_handle()
{
var fake = new FakeTwinCATClient { Values = { ["X"] = 1 } };
await fake.ReadValueAsync("X", TwinCATDataType.DInt, null, null, TestContext.Current.CancellationToken);
fake.HandleCreateInvocations.Count.ShouldBe(1);
fake.HasCachedHandle("X").ShouldBeTrue();
await fake.FlushOptionalCachesAsync();
fake.FlushOptionalCachesCount.ShouldBe(1);
fake.HasCachedHandle("X").ShouldBeFalse();
fake.HandleDeleteInvocations.Count.ShouldBe(1);
// Subsequent read recreates.
await fake.ReadValueAsync("X", TwinCATDataType.DInt, null, null, TestContext.Current.CancellationToken);
fake.HandleCreateInvocations.Count.ShouldBe(2);
}
[Fact]
public async Task Reconnect_clears_handle_cache()
{
var fake = new FakeTwinCATClient { Values = { ["MAIN.Y"] = 9 } };
await fake.ConnectAsync(new TwinCATAmsAddress("5.23.91.23.1.1", 851), TimeSpan.FromSeconds(5),
TestContext.Current.CancellationToken);
await fake.ReadValueAsync("MAIN.Y", TwinCATDataType.DInt, null, null, TestContext.Current.CancellationToken);
fake.HandleCacheCount.ShouldBe(1);
// Simulate a connection drop + reconnect — handles from the prior session are dead.
fake.SimulateReconnect();
fake.HandleCacheCount.ShouldBe(0);
// Next read repopulates with a fresh handle.
await fake.ReadValueAsync("MAIN.Y", TwinCATDataType.DInt, null, null, TestContext.Current.CancellationToken);
fake.HandleCreateInvocations.Count.ShouldBe(2);
}
[Fact]
public async Task Bulk_path_does_not_consume_handle_cache()
{
// PR 2.2 deviation note: bulk Sum-read / Sum-write stays on symbolic paths because
// the perf win over the per-tag handle path is marginal vs the diff cost. This test
// pins the contract — bulk does not create handles, the per-tag path does.
var (drv, factory) = NewDriver(
new TwinCATTagDefinition("X", DevA, "MAIN.X", TwinCATDataType.DInt),
new TwinCATTagDefinition("Y", DevA, "MAIN.Y", TwinCATDataType.DInt));
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
factory.Customise = () => new FakeTwinCATClient
{
Values = { ["MAIN.X"] = 1, ["MAIN.Y"] = 2 },
};
await drv.ReadAsync(["X", "Y"], TestContext.Current.CancellationToken);
await drv.ReadAsync(["X", "Y"], TestContext.Current.CancellationToken);
var client = factory.Clients[0];
client.BulkReadInvocations.Count.ShouldBe(2);
client.HandleCreateInvocations.Count.ShouldBe(0);
client.HandleCacheCount.ShouldBe(0);
}
[Fact]
public async Task Per_tag_path_through_driver_uses_handle_cache()
{
// Whole-array reads route through the per-tag ReadValueAsync path — perfect for
// exercising the handle cache via the public driver surface.
var (drv, factory) = NewDriver(
new TwinCATTagDefinition("Recipe", DevA, "MAIN.Recipe", TwinCATDataType.DInt,
ArrayDimensions: [4]));
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
factory.Customise = () => new FakeTwinCATClient
{
Values = { ["MAIN.Recipe"] = new int[] { 1, 2, 3, 4 } },
};
await drv.ReadAsync(["Recipe"], TestContext.Current.CancellationToken);
await drv.ReadAsync(["Recipe"], TestContext.Current.CancellationToken);
await drv.ReadAsync(["Recipe"], TestContext.Current.CancellationToken);
var client = factory.Clients[0];
client.HandleCreateInvocations.ShouldBe(["MAIN.Recipe"]);
client.ReadByHandleInvocations.Count.ShouldBe(3);
}
[Fact]
public async Task Bit_RMW_routes_parent_word_through_handle_cache()
{
// BOOL-in-word writes do read + write of the parent UDINT — both hops should
// share the same cached handle for the parent. After three writes there should
// still be only one handle for "Flags".
var (drv, factory) = NewDriver(
new TwinCATTagDefinition("Bit3", DevA, "GVL.Flags.3", TwinCATDataType.Bool));
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
factory.Customise = () => new FakeTwinCATClient { Values = { ["GVL.Flags"] = 0u } };
await drv.WriteAsync([new WriteRequest("Bit3", true)], TestContext.Current.CancellationToken);
await drv.WriteAsync([new WriteRequest("Bit3", false)], TestContext.Current.CancellationToken);
await drv.WriteAsync([new WriteRequest("Bit3", true)], TestContext.Current.CancellationToken);
var client = factory.Clients[0];
client.HandleCreateInvocations.ShouldBe(["GVL.Flags"]);
client.HandleCacheCount.ShouldBe(1);
// Three RMWs = three reads + three writes by handle on the parent.
client.ReadByHandleInvocations.Count(x => x == "GVL.Flags").ShouldBe(3);
client.WriteByHandleInvocations.Count(x => x == "GVL.Flags").ShouldBe(3);
}
}