dohertj2/lmxopcua
1
0
Fork 0
Code Issues 13 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

107
tests/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests/TwinCATHandleCachePerfTests.cs Normal file
View File

@@ -0,0 +1,107 @@
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.IntegrationTests;
/// <summary>
/// PR 2.2 integration test — exercises the live <see cref="AdsTwinCATClient"/>
/// handle cache against a real XAR runtime. Reads 50 distinct symbols twice and
/// asserts the second pass issues zero new <c>CreateVariableHandleAsync</c> calls.
/// </summary>
/// <remarks>
/// Hooks into <c>AdsTwinCATClient.HandleCreateCount</c> + <c>HandleCacheCount</c> via
/// the <c>InternalsVisibleTo</c> bridge added in PR 2.1. The fixture's skip-reason is
/// surfaced through <see cref="TwinCATFactAttribute"/> so the test stays green on a
/// dev box without the XAR VM (and its expiring trial license).
/// </remarks>
[Collection("TwinCATXar")]
[Trait("Category", "Integration")]
[Trait("Simulator", "TwinCAT-XAR")]
public sealed class TwinCATHandleCachePerfTests(TwinCATXarFixture sim)
{
private const int TagCount = 50;
[TwinCATFact]
public async Task Driver_handle_cache_avoids_repeat_symbol_resolution()
{
if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
var deviceAddress = $"ads://{sim.TargetNetId}:{sim.AmsPort}";
var tags = new TwinCATTagDefinition[TagCount];
var refs = new string[TagCount];
for (var i = 0; i < TagCount; i++)
{
// GVL_Perf.aTags is 1-based per IEC 61131-3 ARRAY declaration. The 1000-element
// perf array is shared with TwinCATSumCommandPerfTests; this test only touches
// the first 50 indices so it stays cheap on every CI run.
var name = $"Perf{i + 1}";
refs[i] = name;
tags[i] = new TwinCATTagDefinition(
Name: name,
DeviceHostAddress: deviceAddress,
SymbolPath: $"GVL_Perf.aTags[{i + 1}]",
DataType: TwinCATDataType.DInt,
// ArrayDimensions = [1] forces the per-tag (handle-cached) path rather
// than the bulk Sum-read path, which still flows through symbolic paths
// by the PR 2.2 deviation note.
ArrayDimensions: [1]);
}
var options = new TwinCATDriverOptions
{
Devices = [new TwinCATDeviceOptions(deviceAddress, "XAR-VM")],
Tags = tags,
UseNativeNotifications = false,
Timeout = TimeSpan.FromSeconds(15),
Probe = new TwinCATProbeOptions { Enabled = false },
};
// Factory wrapper to capture the live AdsTwinCATClient and expose its internal
// counters back up to the test. Driver-side code only sees ITwinCATClient so this
// doesn't leak the implementation type out of the test.
var capture = new CapturingFactory();
await using var drv = new TwinCATDriver(options, "tc3-handle-cache", capture);
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
// First pass: every symbol is a cache miss. After this pass HandleCreateCount
// should equal TagCount.
var firstResults = await drv.ReadAsync(refs, TestContext.Current.CancellationToken);
firstResults.Count.ShouldBe(TagCount);
firstResults.ShouldAllBe(s => s.StatusCode == TwinCATStatusMapper.Good);
capture.Client.ShouldNotBeNull("CapturingFactory should have produced exactly one AdsTwinCATClient");
var firstPassCreates = capture.Client!.HandleCreateCount;
capture.Client!.HandleCacheCount.ShouldBe(TagCount);
firstPassCreates.ShouldBe(TagCount);
// Second pass: every symbol is a cache hit. HandleCreateCount must not have moved.
var secondResults = await drv.ReadAsync(refs, TestContext.Current.CancellationToken);
secondResults.Count.ShouldBe(TagCount);
secondResults.ShouldAllBe(s => s.StatusCode == TwinCATStatusMapper.Good);
capture.Client!.HandleCreateCount.ShouldBe(
firstPassCreates,
$"Second pass over {TagCount} symbols should have created zero new handles, " +
$"but HandleCreateCount went {firstPassCreates} -> {capture.Client!.HandleCreateCount}.");
capture.Client!.HandleCacheCount.ShouldBe(TagCount);
}
/// <summary>
/// Routes <see cref="ITwinCATClientFactory.Create"/> through the production
/// <see cref="AdsTwinCATClientFactory"/> and snapshots the produced client so the
/// test can read its internal handle-cache counters.
/// </summary>
private sealed class CapturingFactory : ITwinCATClientFactory
{
public AdsTwinCATClient? Client { get; private set; }
public ITwinCATClient Create()
{
var c = new AdsTwinCATClient();
Client ??= c; // first one wins — single-device test path.
return c;
}
}
}

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);
}
}