diff --git a/Source/Core/ExpressiveCommandBase.cs b/Source/Core/ExpressiveCommandBase.cs index 25ceb15..97cfb1f 100644 --- a/Source/Core/ExpressiveCommandBase.cs +++ b/Source/Core/ExpressiveCommandBase.cs @@ -37,6 +37,9 @@ protected IDbConnectionPool ConnectionProvider readonly object _poolOrConnection; int _busy; + // Set while a parameter added by AddParam(value) or AddParams(object) is still waiting for its name to be resolved. + bool _hasDerivedParams; + // The rarely-set members live in a block that is only allocated when one is set, so the usual // conn.Command(sql) object stays small (it is allocated on every call). private protected sealed class CommandOptions @@ -46,9 +49,6 @@ private protected sealed class CommandOptions public CancellationToken CancellationToken; public ushort Timeout = CommandTimeout.DEFAULT_SECONDS; public bool UseAsyncRead; - - // Set while a parameter added by AddParam(value) is still waiting for its name to be resolved. - public bool HasDerivedParams; } private protected CommandOptions? _options; @@ -403,7 +403,7 @@ public TThis AddParams(T source) for (int i = 0; i < members.Names.Length; i++) own.Add(Param.OfObject(members.Names[i], members.Getters[i](source), members.Types[i])); - EnsureOptions().HasDerivedParams = true; + _hasDerivedParams = true; return (TThis)this; } @@ -416,18 +416,19 @@ public TThis AddParams(T source) for (int i = 0; i < names.Length; i++) list.Add(Param.OfObject(names[i], getters[i](source), types[i])); - EnsureOptions().HasDerivedParams = true; + _hasDerivedParams = true; return (TThis)this; } TThis AddDerivedParam(object? value, string? expression, Type clrType) { - if (!ParameterNames.IsDerivable(expression)) + // The facts of the expression are worked out once per expression string (see ParameterNames.Describe). + if (ParameterNames.Describe(expression) is not { } described) throw NotDerivable(expression); // Name is the last member as written; the real name replaces it at execution when the procedure's names are known. - Params.Add(Param.Derived(ParameterNames.LastMember(expression!), expression!, value, clrType)); - EnsureOptions().HasDerivedParams = true; + Params.Add(Param.Derived(described.LastMember, expression!, value, clrType)); + _hasDerivedParams = true; return (TThis)this; } @@ -573,63 +574,67 @@ protected virtual ImmutableArray GetProcedureParameterNames(TConnection protected virtual ValueTask> GetProcedureParameterNamesAsync(TConnection connection, string procedure, CancellationToken cancellationToken) => new(GetProcedureParameterNames(connection, procedure)); + // The names of a text command, by the command text itself (by reference): a literal or a kept string stays remembered, and the entry goes when the string is released. + // A text with no @name marker has a set with no names, which means "not known". + static readonly ConditionalWeakTable TextNames = new(); + // Runs after the connection is open and before the command is built, once per command: it replaces the provisional names with the real ones. + // What is remembered is a NameSet (the names and the match found for each argument), so a repeat execution allocates nothing to resolve. void ResolveDerivedParams(TConnection connection) { - if (_options is not { HasDerivedParams: true }) return; + if (!_hasDerivedParams) return; - ImmutableArray names = default; + NameSet? names = null; bool remembered = false; if (Type == CommandType.StoredProcedure) { - string key = ProcedureKey(connection); + ProcedureKey key = ProcedureKey(connection); remembered = ProcedureNameCache.TryGet(NameCacheOwner, key, out names); - if (!remembered) - { - names = GetProcedureParameterNames(connection, Command); - if (!names.IsDefaultOrEmpty) ProcedureNameCache.Set(NameCacheOwner, key, names); - } + if (!remembered) names = Remember(key, GetProcedureParameterNames(connection, Command)); } else if (Type == CommandType.Text) { - names = SqlTextParameters.Parse(Command); // the @name markers found in the text + names = TextNames.GetValue(Command, static text => new NameSet(SqlTextParameters.Parse(text))); // the @name markers found in the text } if (ApplyDerivedNames(names, final: !remembered)) return; // The remembered names did not fit: the procedure may have changed since they were read. Read them again before deciding that nothing matches. - names = GetProcedureParameterNames(connection, Command); - if (!names.IsDefaultOrEmpty) ProcedureNameCache.Set(NameCacheOwner, ProcedureKey(connection), names); + names = Remember(ProcedureKey(connection), GetProcedureParameterNames(connection, Command)); ApplyDerivedNames(names, final: true); } - async ValueTask ResolveDerivedParamsAsync(TConnection connection, CancellationToken cancellationToken) + // Not an async method itself: when the names are remembered (the usual case) it finishes without a state machine or an await; only reading them is asynchronous. + ValueTask ResolveDerivedParamsAsync(TConnection connection, CancellationToken cancellationToken) { - ImmutableArray names = default; + NameSet? names = null; bool remembered = false; if (Type == CommandType.StoredProcedure) { - string key = ProcedureKey(connection); - remembered = ProcedureNameCache.TryGet(NameCacheOwner, key, out names); - if (!remembered) - { - names = await GetProcedureParameterNamesAsync(connection, Command, cancellationToken).ConfigureAwait(false); - if (!names.IsDefaultOrEmpty) ProcedureNameCache.Set(NameCacheOwner, key, names); - } + remembered = ProcedureNameCache.TryGet(NameCacheOwner, ProcedureKey(connection), out names); + if (!remembered) return ReadNamesAndApplyAsync(connection, cancellationToken); } else if (Type == CommandType.Text) { - names = SqlTextParameters.Parse(Command); // the @name markers found in the text + names = TextNames.GetValue(Command, static text => new NameSet(SqlTextParameters.Parse(text))); // the @name markers found in the text } - if (ApplyDerivedNames(names, final: !remembered)) return; + if (ApplyDerivedNames(names, final: !remembered)) return default; // The remembered names did not fit: the procedure may have changed since they were read. Read them again before deciding that nothing matches. - names = await GetProcedureParameterNamesAsync(connection, Command, cancellationToken).ConfigureAwait(false); - if (!names.IsDefaultOrEmpty) ProcedureNameCache.Set(NameCacheOwner, ProcedureKey(connection), names); + return ReadNamesAndApplyAsync(connection, cancellationToken); + } + + async ValueTask ReadNamesAndApplyAsync(TConnection connection, CancellationToken cancellationToken) + { + NameSet? names = Remember(ProcedureKey(connection), await GetProcedureParameterNamesAsync(connection, Command, cancellationToken).ConfigureAwait(false)); ApplyDerivedNames(names, final: true); } + // Remembers the names a procedure reported and returns the set made from them; an empty answer is "not known" (null) and is not remembered. + NameSet? Remember(ProcedureKey key, ImmutableArray names) + => names.IsDefaultOrEmpty ? null : ProcedureNameCache.Set(NameCacheOwner, key, names); + // Remembered names belong to the object commands take connections from: a factory (not the wrapper made around it for each command), a pool, or the bare connection. object NameCacheOwner => _poolOrConnection switch { @@ -640,72 +645,98 @@ async ValueTask ResolveDerivedParamsAsync(TConnection connection, CancellationTo // The server and the database are part of the key: one connection can be switched to another database, and one factory can hand out connections to different servers, // where the same procedure name may be a different procedure. IDbConnection has no server name, so a connection that is not a DbConnection contributes none. - string ProcedureKey(TConnection connection) => (connection as DbConnection)?.DataSource + "\n" + connection.Database + "\n" + Command; + // The key is a struct of the three parts, so no string is built. + ProcedureKey ProcedureKey(TConnection connection) => new((connection as DbConnection)?.DataSource, connection.Database, Command); // Returns false, leaving the parameters untouched, when an argument named by the caller matches none of the real names and `final` is false (the names may be out of date). - bool ApplyDerivedNames(ImmutableArray real, bool final) + // `real` is null when the names are not known (and has no names for a text without markers): each argument then keeps its last member as written. + bool ApplyDerivedNames(NameSet? real, bool final) { List list = Params; - var kept = new List(list.Count); - var original = new List(list.Count); // aligned with kept: the parameter as it was added, to say what the caller wrote and whether it is a member of an object given to AddParams + int count = list.Count; - foreach (Param p in list) + // The name each parameter ends up with (null: not sent), in a pooled array; only the used part is cleared when it goes back. + string?[] names = ArrayPool.Shared.Rent(count); + try + { + return Apply(list, count, names, real, final); + } + finally { + Array.Clear(names, 0, count); + ArrayPool.Shared.Return(names); + } + } + + bool Apply(List list, int count, string?[] names, NameSet? real, bool final) + { + bool known = real is { Names.Length: > 0 }; + + // Resolve each name. Without the real names the last member is used as written. + for (int i = 0; i < count; i++) + { + Param p = list[i]; if (p.Expression is not { } expression) { - kept.Add(p); - original.Add(p); + names[i] = p.Name; continue; } - // Without the real names the last member is used as written. - string? name = real.IsDefaultOrEmpty ? p.Name : ParameterNames.Match(ParameterNames.Candidates(expression), real, expression, Command); + string? name = known ? real!.Match(expression, Command) : p.Name; if (name is null) { // A member of an object that the procedure does not take is simply not sent; an argument named by the caller must match. - if (p.FromObject) continue; + if (p.FromObject) continue; // names[i] stays null if (!final) return false; - throw NoMatch(expression, real); + throw NoMatch(expression, real!.Names); } - kept.Add(p.Resolved(name)); - original.Add(p); + names[i] = name; } // A parameter named by the caller wins over a member of an object that resolves to the same name. - for (int i = kept.Count - 1; i >= 0; i--) + // The ones compared against are never members of an object, so dropping a member does not change the answer for another. + for (int i = 0; i < count; i++) { - if (!original[i].FromObject) continue; - for (int j = 0; j < kept.Count; j++) + if (names[i] is not { } member || !list[i].FromObject) continue; + for (int j = 0; j < count; j++) { - if (j != i && !original[j].FromObject && SameName(kept[i].Name, kept[j].Name)) + if (j != i && names[j] is { } other && !list[j].FromObject && SameName(member, other)) { - kept.RemoveAt(i); - original.RemoveAt(i); + names[i] = null; break; } } } // Two arguments that resolve to one parameter would silently overwrite each other. - for (int i = 0; i < kept.Count; i++) + for (int i = 0; i < count; i++) { - for (int j = i + 1; j < kept.Count; j++) + if (names[i] is not { } first) continue; + for (int j = i + 1; j < count; j++) { - if (SameName(kept[i].Name, kept[j].Name)) - throw Collision(kept[i].Name, original[i], original[j], real); + if (names[j] is { } second && SameName(first, second)) + throw Collision(first, list[i], list[j], real?.Names ?? default); } } - list.Clear(); - list.AddRange(kept); - _options!.HasDerivedParams = false; + // Keep what is sent, in order, under its resolved name. + int written = 0; + for (int i = 0; i < count; i++) + { + if (names[i] is not { } name) continue; + Param p = list[i]; + list[written++] = p.Expression is null ? p : p.Resolved(name); + } + + list.RemoveRange(written, count - written); + _hasDerivedParams = false; return true; } - static bool SameName(string a, string b) => string.Equals(BareName(a), BareName(b), StringComparison.OrdinalIgnoreCase); + static bool SameName(string a, string b) => Bare(a).Equals(Bare(b), StringComparison.OrdinalIgnoreCase); - static string BareName(string name) => name.Length > 0 && name[0] == '@' ? name[1..] : name; + static ReadOnlySpan Bare(string name) => name.Length > 0 && name[0] == '@' ? name.AsSpan(1) : name.AsSpan(); // What the caller wrote for a parameter, for the message of a collision. static string Written(Param original) @@ -768,7 +799,7 @@ private protected async ValueTask ExecuteCoreAsync(TSt try { ConnectionState prior = await OpenIfNeededAsync(single, cancellationToken).ConfigureAwait(false); - if (_options is { HasDerivedParams: true }) await ResolveDerivedParamsAsync(single, cancellationToken).ConfigureAwait(false); + if (_hasDerivedParams) await ResolveDerivedParamsAsync(single, cancellationToken).ConfigureAwait(false); using TCommand cmd = PrepareCommand(single); return await func(cmd, prior, state).ConfigureAwait(false); } @@ -783,7 +814,7 @@ private protected async ValueTask ExecuteCoreAsync(TSt try { ConnectionState prior = await OpenIfNeededAsync(conn, cancellationToken).ConfigureAwait(false); - if (_options is { HasDerivedParams: true }) await ResolveDerivedParamsAsync(conn, cancellationToken).ConfigureAwait(false); + if (_hasDerivedParams) await ResolveDerivedParamsAsync(conn, cancellationToken).ConfigureAwait(false); using TCommand cmd = PrepareCommand(conn); return await func(cmd, prior, state).ConfigureAwait(false); } diff --git a/Source/Core/NameSet.cs b/Source/Core/NameSet.cs new file mode 100644 index 0000000..83ac749 --- /dev/null +++ b/Source/Core/NameSet.cs @@ -0,0 +1,55 @@ +using System.Diagnostics; + +namespace Open.Database.Extensions; + +/// +/// One set of real parameter names (a procedure's, or the @name markers of a SQL text) and what is worked out from it: +/// the names without their @, once, and the real name each argument expression matched, so a repeat execution allocates nothing to match. +/// +sealed class NameSet +{ + // The real name each expression matched (null: it matches nothing), by the expression as the caller wrote it. + // Bounded by the call sites and member names that run against this set; the set is replaced when its procedure's names expire (5 minutes) or are read again, so no limit is needed. + readonly Dictionary _matches = new(StringComparer.Ordinal); + + /// Makes the set from the names as the provider reported them (a leading @ is fine); never the default array, but may be empty (a text without markers). + /// The names. + internal NameSet(ImmutableArray names) + { + Debug.Assert(!names.IsDefault, "A set is made from names, not from 'not known'."); + Names = names; + BareNames = ParameterNames.BareNames(names); + } + + /// The names as the provider reported them. + internal ImmutableArray Names { get; } + + /// The same names without a leading @. + internal ImmutableArray BareNames { get; } + + /// + /// The real name that the argument expression stands for, or when it matches none. The answer is remembered, so the next call with the same expression does no matching. + /// An ambiguity throws (see ) and is not remembered, so it throws on every call. + /// + /// The expression is not derivable. + /// The expression fits more than one name equally well. + internal string? Match(string expression, string procedure) + { + lock (_matches) + { + if (_matches.TryGetValue(expression, out string? remembered)) return remembered; + } + + // An argument of AddParam(value) was described when it was added; the member of an AddParams object is not derivable if it is a verbatim keyword, which Candidates reports. + ImmutableArray candidates = ParameterNames.Describe(expression)?.Candidates ?? ParameterNames.Candidates(expression); + + // Two threads may both match and store: the answer is the same. + string? found = ParameterNames.MatchBare(candidates, Names, BareNames, expression, procedure); + lock (_matches) + { + _matches[expression] = found; + } + + return found; + } +} diff --git a/Source/Core/ParameterNames.cs b/Source/Core/ParameterNames.cs index f4152c6..5dd46be 100644 --- a/Source/Core/ParameterNames.cs +++ b/Source/Core/ParameterNames.cs @@ -27,6 +27,25 @@ readonly struct Segment(int start, int length) public readonly int Length = length; } + /// The facts of a derivable expression, worked out once. + internal sealed class DerivedExpression(string lastMember, ImmutableArray candidates) + { + internal string LastMember { get; } = lastMember; + internal ImmutableArray Candidates { get; } = candidates; + } + + // By the expression string itself: the text of an argument comes from [CallerArgumentExpression], a literal at the call site, so it is the same object on every call. + // An entry goes when its string is released. A text that is not derivable is not stored. + static readonly ConditionalWeakTable Described = new(); + + /// The last member and the candidates of the expression, remembered on the string; when it is or not derivable. + internal static DerivedExpression? Describe(string? expression) + { + if (expression is null) return null; + if (Described.TryGetValue(expression, out DerivedExpression? known)) return known; + return IsDerivable(expression) ? Described.GetValue(expression, static e => new DerivedExpression(LastMember(e), Candidates(e))) : null; + } + /// True when the expression is a chain of plain member accesses a name can be derived from. Allocates nothing. internal static bool IsDerivable(string? expression) => TryScan(expression, null, out _, out _); @@ -191,9 +210,17 @@ static bool ClosesAt(string s, int open, int close) /// The real name as the provider reported it, or when no candidate matches any parameter. /// One candidate matches more than one parameter at the same tier. The message says what the caller wrote, the candidate, the tier and what the procedure declares. internal static string? Match(ImmutableArray candidates, ImmutableArray parameterNames, string expression, string procedure) - { // Every candidate in every tier compares against the same bare names: remove the @ once, here. - ImmutableArray bareNames = BareNames(parameterNames); + => MatchBare(candidates, parameterNames, BareNames(parameterNames), expression, procedure); + + /// The same as , with the names without their @ already made (a makes them once). + /// The candidates from . + /// The real names as the provider reports them. + /// The same names without a leading @. + /// The text of the argument, for the message of an ambiguity. + /// The procedure's name, for the message of an ambiguity. + internal static string? MatchBare(ImmutableArray candidates, ImmutableArray parameterNames, ImmutableArray bareNames, string expression, string procedure) + { foreach (string candidate in candidates) { if (Find(expression, procedure, candidate, parameterNames, bareNames) is { } found) return found; @@ -239,7 +266,7 @@ static bool ClosesAt(string s, int open, int close) } // The real names without a leading @. A set with none is returned as it is; otherwise one copy holds the bare names, and a name without an @ is the same string in it. - static ImmutableArray BareNames(ImmutableArray names) + internal static ImmutableArray BareNames(ImmutableArray names) { string[]? bare = null; for (int i = 0; i < names.Length; i++) diff --git a/Source/Core/ProcedureNameCache.cs b/Source/Core/ProcedureNameCache.cs index 71ea875..6f6598a 100644 --- a/Source/Core/ProcedureNameCache.cs +++ b/Source/Core/ProcedureNameCache.cs @@ -3,12 +3,54 @@ namespace Open.Database.Extensions; /// -/// Remembers the parameter names of stored procedures, so a command with derived parameter names asks the database once, not on every execution. +/// The server, the database and the procedure a set of names belongs to. A small struct compared part by part, so looking a procedure up builds no string. +/// +/// +/// Each part is compared ignoring case. A part that is is the empty string. +/// +readonly struct ProcedureKey : IEquatable +{ + internal ProcedureKey(string? server, string? database, string? procedure) + { + // StringComparer.GetHashCode(null) throws, and a missing server or database is the same key as an empty one. + Server = server ?? string.Empty; + Database = database ?? string.Empty; + Procedure = procedure ?? string.Empty; + } + + internal string Server { get; } + internal string Database { get; } + internal string Procedure { get; } + + public bool Equals(ProcedureKey other) + => string.Equals(Procedure, other.Procedure, StringComparison.OrdinalIgnoreCase) + && string.Equals(Database, other.Database, StringComparison.OrdinalIgnoreCase) + && string.Equals(Server, other.Server, StringComparison.OrdinalIgnoreCase); + + public override bool Equals(object? obj) => obj is ProcedureKey other && Equals(other); + + // System.HashCode is not in netstandard2.0. + public override int GetHashCode() + { + StringComparer comparer = StringComparer.OrdinalIgnoreCase; + unchecked + { + int hash = comparer.GetHashCode(Server); + hash = (hash * 397) ^ comparer.GetHashCode(Database); + hash = (hash * 397) ^ comparer.GetHashCode(Procedure); + return hash; + } + } +} + +/// +/// Remembers the parameter names of stored procedures, and what is worked out from them, so a command with derived parameter names asks the database once, not on every execution. /// /// /// An entry belongs to the object commands take their connections from (the connection factory, the pool, or the bare connection), held weakly, /// so the application's own objects decide how long names are remembered and nothing here keeps anything alive. -/// Names expire so that a procedure whose parameters change is read again, and one object remembers at most 1024 procedures. An empty answer ("not known") is never remembered. +/// An entry is a : the names, and the real name each argument expression has matched so far, so a repeat execution matches nothing again. +/// Names expire so that a procedure whose parameters change is read again (the matches go with them), and one object remembers at most 1024 procedures. An empty answer ("not known") is never remembered. /// static class ProcedureNameCache { @@ -20,18 +62,18 @@ static class ProcedureNameCache static readonly ConditionalWeakTable Sources = new(); - sealed class Entry(long expires, ImmutableArray names) + sealed class Entry(long expires, NameSet names) { public readonly long Expires = expires; - public readonly ImmutableArray Names = names; + public readonly NameSet Names = names; } sealed class Entries { - public readonly Dictionary ByProcedure = [with(StringComparer.OrdinalIgnoreCase)]; + public readonly Dictionary ByProcedure = []; } - internal static bool TryGet(object source, string key, out ImmutableArray names) + internal static bool TryGet(object source, ProcedureKey key, out NameSet? names) { if (Sources.TryGetValue(source, out Entries? entries)) { @@ -50,35 +92,39 @@ internal static bool TryGet(object source, string key, out ImmutableArray names) + /// Remembers the names and returns the set made from them. + internal static NameSet Set(object source, ProcedureKey key, ImmutableArray names) { Debug.Assert(!names.IsDefaultOrEmpty, "An empty answer means 'not known' and is not remembered."); + var set = new NameSet(names); Entries entries = Sources.GetValue(source, static _ => new Entries()); lock (entries) { - Dictionary byProcedure = entries.ByProcedure; + Dictionary byProcedure = entries.ByProcedure; if (byProcedure.Count >= MaxProcedures && !byProcedure.ContainsKey(key)) Trim(byProcedure); - byProcedure[key] = new Entry(Stopwatch.GetTimestamp() + LifetimeTicks, names); + byProcedure[key] = new Entry(Stopwatch.GetTimestamp() + LifetimeTicks, set); } + + return set; } // An expired entry is dropped when it is read again, so a source used with a stream of different procedures would keep every one of them. // At the limit the expired entries go; if every entry is still fresh, they all go and are read again when needed (as the row-map layouts do). - static void Trim(Dictionary byProcedure) + static void Trim(Dictionary byProcedure) { long now = Stopwatch.GetTimestamp(); - List expired = []; - foreach (KeyValuePair pair in byProcedure) + List expired = []; + foreach (KeyValuePair pair in byProcedure) { if (now >= pair.Value.Expires) expired.Add(pair.Key); } - foreach (string key in expired) byProcedure.Remove(key); + foreach (ProcedureKey key in expired) byProcedure.Remove(key); if (byProcedure.Count >= MaxProcedures) byProcedure.Clear(); } } diff --git a/Tests/Open.Database.Extensions.Core.Tests/DerivedNameCostTests.cs b/Tests/Open.Database.Extensions.Core.Tests/DerivedNameCostTests.cs new file mode 100644 index 0000000..773922d --- /dev/null +++ b/Tests/Open.Database.Extensions.Core.Tests/DerivedNameCostTests.cs @@ -0,0 +1,539 @@ +using System.Data.Common; +using System.Runtime.CompilerServices; + +namespace Open.Database.Extensions.Tests; + +#nullable enable + +/// +/// What a repeat execution costs when the parameter names are derived (AddParam(value), AddParams(object)) compared with the hand-written +/// AddParam("@name", value) measured in the same run, and the behaviour that the cost work must not change. Everything runs on in-memory fakes. +/// +[Collection("Heap measurements")] +[ExcludeFromCodeCoverage] +public static class DerivedNameCostTests +{ + // ---- measuring ---- + + // Bytes per call: after a warm-up, the smallest of three rounds of 1,000 calls (the allocated-bytes counter of this thread is exact, so only a stray JIT or GC adds noise). + static long BytesPerCall(Action call) + { + for (int i = 0; i < 100; i++) call(); + long best = long.MaxValue; + for (int round = 0; round < 3; round++) + { + long before = GC.GetAllocatedBytesForCurrentThread(); + for (int i = 0; i < 1000; i++) call(); + best = Math.Min(best, (GC.GetAllocatedBytesForCurrentThread() - before) / 1000); + } + + return best; + } + + // What the derived version may cost beyond the hand-written one: the two differ by no more than a rounding of the measurement. + const int Slack = 16; + + // The numbers are carried by the failure message; when ODE_ALLOC_LOG names a file they are also appended there, so a passing run can be read too. + static void Report(string label, long derived, long explicitName) + { + string line = $"{label}: derived {derived} B, explicit {explicitName} B, difference {derived - explicitName} B"; + if (Environment.GetEnvironmentVariable("ODE_ALLOC_LOG") is { Length: > 0 } path) File.AppendAllText(path, line + Environment.NewLine); + } + + static void AssertWithinBudget(string label, long derived, long explicitName) + { + Report(label, derived, explicitName); + Assert.True(derived <= explicitName + Slack, $"{label}: derived {derived} B per call, explicit {explicitName} B, budget explicit + {Slack}."); + } + + // ---- the fakes ---- + + sealed class Filter + { + public int OrderId { get; set; } = 5; + public int CustomerId { get; set; } = 7; + public DateTime StartDate { get; set; } = new(2026, 1, 2); + } + + sealed class Args + { + public int OrderId { get; set; } = 5; + public int CustomerId { get; set; } = 7; + public DateTime StartDate { get; set; } = new(2026, 1, 2); + } + + sealed class NamedDbCommand(DbConnection connection, CommandType type, string text, ImmutableArray names) + : ExpressiveDbCommand(connection, type, text) + { + protected override ImmutableArray GetProcedureParameterNames(DbConnection connection, string procedure) => names; + + protected override ValueTask> GetProcedureParameterNamesAsync(DbConnection connection, string procedure, CancellationToken cancellationToken) => new(names); + } + + // One connection and one procedure for the whole measurement, so the names are read once and every later run is a repeat. + sealed class Rig + { + static readonly ImmutableArray Real = + [ + "@order_id", "@customer_id", "@start_date", "@end_date", "@status", "@page", "@page_size", "@sort", "@region", "@flag", + ]; + + readonly DerivedParameterNameTests.RecordingDbCommand _db = new(); + readonly DbConnection _connection; + readonly CommandType _type; + readonly string _procedure = ParameterNameHarness.NewProcedure(); + + public Rig(CommandType type) + { + _type = type; + _connection = new DerivedParameterNameTests.OpenDbConnection(_db); + } + + public NamedDbCommand Command() => new(_connection, _type, _procedure, Real); + + public NamedDbCommand Command(string text) => new(_connection, _type, text, Real); + + public string[] Sent => [.. _db.Sent.Select(p => p.ParameterName)]; + + public void Run(ExpressiveDbCommand command) + { + command.ExecuteNonQuery(); + _db.Sent.Clear(); + } + + public void RunThroughAsyncApi(ExpressiveDbCommand command) + { + command.ExecuteNonQueryAsync().AsTask().GetAwaiter().GetResult(); + _db.Sent.Clear(); + } + } + + const string Sql = "select * from orders where order_id = @order_id and customer_id = @customer_id and start_date >= @start_date"; + + // ---- stored procedure, AddParam(value) ---- + + [Fact] + public static void StoredProcedure_PlainLocals_DerivedCostsNoMoreThanExplicit() + { + var rig = new Rig(CommandType.StoredProcedure); + const int orderId = 5, customerId = 7; + var startDate = new DateTime(2026, 1, 2); + + long derived = BytesPerCall(() => rig.Run(rig.Command().AddParam(orderId).AddParam(customerId).AddParam(startDate))); + long explicitName = BytesPerCall(() => rig.Run(rig.Command().AddParam("@order_id", orderId).AddParam("@customer_id", customerId).AddParam("@start_date", startDate))); + + AssertWithinBudget("stored procedure, three plain locals", derived, explicitName); + } + + [Fact] + public static void StoredProcedure_MemberChains_DerivedCostsNoMoreThanExplicit() + { + var rig = new Rig(CommandType.StoredProcedure); + var filter = new Filter(); + + long derived = BytesPerCall(() => rig.Run(rig.Command().AddParam(filter.OrderId).AddParam(filter.CustomerId).AddParam(filter.StartDate))); + long explicitName = BytesPerCall(() => rig.Run(rig.Command().AddParam("@order_id", filter.OrderId).AddParam("@customer_id", filter.CustomerId).AddParam("@start_date", filter.StartDate))); + + AssertWithinBudget("stored procedure, three member chains", derived, explicitName); + } + + // ---- stored procedure, AddParams(object) ---- + + [Fact] + public static void StoredProcedure_AddParamsObject_CostsNoMoreThanExplicit() + { + var rig = new Rig(CommandType.StoredProcedure); + var args = new Args(); + + long derived = BytesPerCall(() => rig.Run(rig.Command().AddParams(args))); + long explicitName = BytesPerCall(() => rig.Run(rig.Command().AddParam("@order_id", args.OrderId).AddParam("@customer_id", args.CustomerId).AddParam("@start_date", args.StartDate))); + + AssertWithinBudget("stored procedure, AddParams with three members", derived, explicitName); + } + + // ---- text command ---- + + [Fact] + public static void Text_LiteralSql_DerivedCostsNoMoreThanExplicit() + { + var rig = new Rig(CommandType.Text); + const int orderId = 5, customerId = 7; + var startDate = new DateTime(2026, 1, 2); + + long derived = BytesPerCall(() => rig.Run(rig.Command(Sql).AddParam(orderId).AddParam(customerId).AddParam(startDate))); + long explicitName = BytesPerCall(() => rig.Run(rig.Command(Sql).AddParam("@order_id", orderId).AddParam("@customer_id", customerId).AddParam("@start_date", startDate))); + + AssertWithinBudget("text command, literal SQL", derived, explicitName); + } + + // The SQL text is a new string object on every call (same characters). Nothing is asserted about the cost beyond "it works": it is reported. + // A weak-table entry also costs a GC handle, which the allocated bytes do not show. + [Fact] + public static void Text_SqlBuiltOnEveryCall_Works_AndTheCostIsReported() + { + var rig = new Rig(CommandType.Text); + const int orderId = 5, customerId = 7; + var startDate = new DateTime(2026, 1, 2); + + long derived = BytesPerCall(() => rig.Run(rig.Command(new string(Sql.AsSpan())).AddParam(orderId).AddParam(customerId).AddParam(startDate))); + long explicitName = BytesPerCall(() => rig.Run(rig.Command(new string(Sql.AsSpan())).AddParam("@order_id", orderId).AddParam("@customer_id", customerId).AddParam("@start_date", startDate))); + Report("text command, SQL built on every call", derived, explicitName); + + ExpressiveDbCommand command = rig.Command(new string(Sql.AsSpan())).AddParam(orderId).AddParam(customerId).AddParam(startDate); + command.ExecuteNonQuery(); + Assert.Equal(["@order_id", "@customer_id", "@start_date"], rig.Sent); + } + + // ---- the asynchronous twins (the fake completes synchronously, so the per-thread counter sees all of it) ---- + + [Fact] + public static void StoredProcedureAsync_PlainLocals_DerivedCostsNoMoreThanExplicit() + { + var rig = new Rig(CommandType.StoredProcedure); + const int orderId = 5, customerId = 7; + var startDate = new DateTime(2026, 1, 2); + + long derived = BytesPerCall(() => rig.RunThroughAsyncApi(rig.Command().AddParam(orderId).AddParam(customerId).AddParam(startDate))); + long explicitName = BytesPerCall(() => rig.RunThroughAsyncApi(rig.Command().AddParam("@order_id", orderId).AddParam("@customer_id", customerId).AddParam("@start_date", startDate))); + + AssertWithinBudget("stored procedure async, three plain locals", derived, explicitName); + } + + [Fact] + public static void StoredProcedureAsync_AddParamsObject_CostsNoMoreThanExplicit() + { + var rig = new Rig(CommandType.StoredProcedure); + var args = new Args(); + + long derived = BytesPerCall(() => rig.RunThroughAsyncApi(rig.Command().AddParams(args))); + long explicitName = BytesPerCall(() => rig.RunThroughAsyncApi(rig.Command().AddParam("@order_id", args.OrderId).AddParam("@customer_id", args.CustomerId).AddParam("@start_date", args.StartDate))); + + AssertWithinBudget("stored procedure async, AddParams with three members", derived, explicitName); + } + + // A plain command object: the size of what conn.Command(sql) allocates, reported for the record (the field that marks derived parameters must not grow it). + [Fact] + public static void PlainCommand_SizeIsReported() + { + var db = new DerivedParameterNameTests.RecordingDbCommand(); + var connection = new DerivedParameterNameTests.OpenDbConnection(db); + long bytes = BytesPerCall(() => connection.Command("select 1")); + if (Environment.GetEnvironmentVariable("ODE_ALLOC_LOG") is { Length: > 0 } path) + File.AppendAllText(path, $"plain command, bytes per conn.Command(sql): {bytes}" + Environment.NewLine); + + Assert.True(bytes > 0); + } + + // ---- behaviour that must not change ---- + + // A fake connection that can be switched to another server or database, as one pooled connection or one factory can be. + sealed class SwitchableConnection(DerivedParameterNameTests.RecordingDbCommand command) : DbConnection + { + public string Server = ""; + public string CurrentDatabase = ""; + + [AllowNull] + public override string ConnectionString { get; set; } = ""; + public override string Database => CurrentDatabase; + public override string DataSource => Server; + public override string ServerVersion => "1.0"; + public override ConnectionState State => ConnectionState.Open; + public override void ChangeDatabase(string databaseName) => CurrentDatabase = databaseName; + public override void Open() { } + public override void Close() { } + protected override DbTransaction BeginDbTransaction(IsolationLevel isolationLevel) => throw new NotSupportedException(); + protected override DbCommand CreateDbCommand() => command; + } + + // A procedure whose names the test can change, on a connection the test can switch. + sealed class ProcRig(params string[] initial) + { + readonly DerivedParameterNameTests.RecordingDbCommand _db = new(); + public string[] Names = initial; + public int Lookups; + public string Procedure { get; } = ParameterNameHarness.NewProcedure(); + public SwitchableConnection Connection => field ??= new(_db); + + sealed class Cmd(DbConnection connection, string procedure, ProcRig owner) : ExpressiveDbCommand(connection, CommandType.StoredProcedure, procedure) + { + protected override ImmutableArray GetProcedureParameterNames(DbConnection connection, string procedure) + { + owner.Lookups++; + return [.. owner.Names]; + } + } + + public string[] Run(Action add) + { + _db.Sent.Clear(); + var command = new Cmd(Connection, Procedure, this); + add(command); + command.ExecuteNonQuery(); + return [.. _db.Sent.Select(p => p.ParameterName)]; + } + } + + // The same procedure name on another database, and on another server, is read on its own: the parts of the key are not mixed. + [Fact] + public static void TheSameProcedureOnAnotherDatabaseOrServer_ResolvesAgainstItsOwnNames() + { + var rig = new ProcRig("@order_id"); + const int orderId = 1; + + rig.Connection.Server = "srv1"; + rig.Connection.CurrentDatabase = "dbA"; + Assert.Equal(["@order_id"], rig.Run(c => c.AddParam(orderId))); + + rig.Names = ["@orderid"]; + rig.Connection.CurrentDatabase = "dbB"; + Assert.Equal(["@orderid"], rig.Run(c => c.AddParam(orderId))); + + rig.Names = ["@p_order_id"]; + rig.Connection.Server = "srv2"; + rig.Connection.CurrentDatabase = "dbA"; + Assert.Equal(["@p_order_id"], rig.Run(c => c.AddParam(orderId))); + Assert.Equal(3, rig.Lookups); + + // Back on the first server and database (written in another case): its own names, remembered, not read again. + rig.Names = ["@never_read"]; + rig.Connection.Server = "SRV1"; + rig.Connection.CurrentDatabase = "DBA"; + Assert.Equal(["@order_id"], rig.Run(c => c.AddParam(orderId))); + Assert.Equal(3, rig.Lookups); + } + + // The remembered names no longer fit: they are read again and the call succeeds, and what the old set answered is not used for the new one. + [Fact] + public static void StaleNames_AreReadAgain_AndTheOldSetsAnswersAreNotReused() + { + var rig = new ProcRig("@order_id"); + const int orderId = 1, customerId = 2; + + Assert.Equal(["@order_id"], rig.Run(c => c.AddParam(orderId))); + Assert.Equal(1, rig.Lookups); + + rig.Names = ["@orderid", "@customer_id"]; // the procedure changed after the first read + Assert.Equal(["@orderid", "@customer_id"], rig.Run(c => c.AddParam(orderId).AddParam(customerId))); + Assert.Equal(2, rig.Lookups); + + // The new set is remembered now: no more reads. + Assert.Equal(["@orderid", "@customer_id"], rig.Run(c => c.AddParam(orderId).AddParam(customerId))); + Assert.Equal(2, rig.Lookups); + } + + // An ambiguous argument throws on every call, not only the first. + [Fact] + public static void AmbiguousArgument_ThrowsOnEveryCall() + { + var rig = new ProcRig("@company_serial_num", "@companyserial_num"); + const int companySerialNum = 1; + + for (int i = 0; i < 3; i++) + { + var ex = Assert.Throws(() => rig.Run(c => c.AddParam(companySerialNum))); + Assert.Equal( + $"The argument 'companySerialNum' matches both '@company_serial_num' and '@companyserial_num' of '{rig.Procedure}'. Its candidate name 'companySerialNum' fits each of them ignoring case and underscores. " + + "The procedure declares: @company_serial_num, @companyserial_num. Name the parameter explicitly: AddParam(\"name\", value).", + ex.Message); + } + } + + sealed class Item + { + public int Id { get; set; } = 1; + public string Junk { get; set; } = "x"; + public string Name { get; set; } = "n"; + } + + // A member of an object that the procedure does not take is not sent, on every call. + [Fact] + public static void ObjectMemberTheProcedureDoesNotDeclare_IsDropped_OnEveryCall() + { + var rig = new ProcRig("@id", "@name"); + var item = new Item(); + + for (int i = 0; i < 3; i++) + Assert.Equal(["@id", "@name"], rig.Run(c => c.AddParams(item))); + } + + // A parameter named by the caller wins over an object member that resolves to the same name. + [Fact] + public static void CallerNamedParameter_WinsOverAnObjectMember() + { + var rig = new ProcRig("@id", "@name"); + var item = new Item(); + + for (int i = 0; i < 3; i++) + Assert.Equal(["@ID", "@name"], rig.Run(c => c.AddParam("@ID", 99).AddParams(item))); + } + + sealed class Regional + { + public int Region { get; set; } = 3; + } + + // Two arguments that resolve to one parameter: the messages are pinned. + [Fact] + public static void Collision_MessagesArePinned() + { + var rig = new ProcRig("@region"); + const int region = 1, Region = 2; + string tail = $" The procedure '{rig.Procedure}' declares: @region. Name one of them explicitly: AddParam(\"name\", value)."; + + var twoArguments = Assert.Throws(() => rig.Run(c => c.AddParam(region).AddParam(Region))); + Assert.Equal("Two parameters resolve to '@region': the argument 'region' and the argument 'Region'." + tail, twoArguments.Message); + + var named = Assert.Throws(() => rig.Run(c => c.AddParam("@REGION", 1).AddParam(region))); + Assert.Equal("Two parameters resolve to '@REGION': the name '@REGION' you passed and the argument 'region'." + tail, named.Message); + + var member = Assert.Throws(() => rig.Run(c => c.AddParams(new Regional()).AddParams(new Regional()))); + Assert.Equal("Two parameters resolve to '@region': the member 'Region' of the AddParams object and the member 'Region' of the AddParams object." + tail, member.Message); + } + + // The message of an argument that matches nothing. + [Fact] + public static void NoMatch_MessageIsPinned() + { + var rig = new ProcRig("@a", "@b"); + const int orderId = 1; + + var ex = Assert.Throws(() => rig.Run(c => c.AddParam(orderId))); + Assert.Equal($"The argument 'orderId' matches none of the parameters of '{rig.Procedure}' (tried orderId). The procedure declares: @a, @b. Name the parameter explicitly: AddParam(\"name\", value).", ex.Message); + } + + sealed class Keyword + { + [SuppressMessage("Naming", "IDE1006:Naming Styles", Justification = "The member is named like a keyword on purpose: its name cannot be derived.")] + public int @default { get; set; } = 1; + } + + // A member of an AddParams object whose name cannot be derived (a verbatim keyword) reaches the match without a description and fails the same way on every call. + [Fact] + public static void ObjectMemberThatCannotBeDerived_ThrowsArgumentException_OnEveryCall() + { + var rig = new ProcRig("@id", "@name"); + var item = new Keyword(); + + for (int i = 0; i < 2; i++) + { + var ex = Assert.Throws(() => rig.Run(c => c.AddParams(item))); + Assert.Equal("expression", ex.ParamName); + Assert.Equal("Cannot derive a parameter name from the expression 'default'. (Parameter 'expression')", ex.Message); + } + } + + // A text command whose SQL has no @name marker: the names are not known, each argument keeps its last member, and two that read as one name collide. + [Fact] + public static void TextCommandWithoutMarkers_CollisionMessageSaysTheNamesAreNotKnown() + { + var db = new DerivedParameterNameTests.RecordingDbCommand(); + var connection = new DerivedParameterNameTests.OpenDbConnection(db); + const int region = 1, Region = 2; + + var ex = Assert.Throws( + () => new ExpressiveDbCommand(connection, CommandType.Text, "select 1").AddParam(region).AddParam(Region).ExecuteNonQuery()); + Assert.Equal( + "Two parameters resolve to 'region': the argument 'region' and the argument 'Region'. " + + "The parameter names are not known, so each argument is used under its last member as written. " + + "Name one of them explicitly: AddParam(\"name\", value).", + ex.Message); + } + + // ---- text commands ---- + + [Fact] + public static void TwoStringObjectsWithTheSameSql_BothResolve() + { + var db = new DerivedParameterNameTests.RecordingDbCommand(); + var connection = new DerivedParameterNameTests.OpenDbConnection(db); + const int orderId = 1; + + for (int i = 0; i < 3; i++) + { + string sql = new("select * from t where order_id = @order_id".AsSpan()); + db.Sent.Clear(); + new ExpressiveDbCommand(connection, CommandType.Text, sql).AddParam(orderId).ExecuteNonQuery(); + Assert.Equal(["@order_id"], db.Sent.Select(p => p.ParameterName)); + } + + for (int i = 0; i < 3; i++) // a literal is one object for every call + { + db.Sent.Clear(); + new ExpressiveDbCommand(connection, CommandType.Text, "select * from t where order_id = @order_id").AddParam(orderId).ExecuteNonQuery(); + Assert.Equal(["@order_id"], db.Sent.Select(p => p.ParameterName)); + } + } + + [MethodImpl(MethodImplOptions.NoInlining)] + static WeakReference RunWithADynamicText() + { + var db = new DerivedParameterNameTests.RecordingDbCommand(); + var connection = new DerivedParameterNameTests.OpenDbConnection(db); + string sql = new("select * from t where order_id = @order_id and x = @leak_check_marker".AsSpan()); + const int orderId = 1; + new ExpressiveDbCommand(connection, CommandType.Text, sql).AddParam(orderId).ExecuteNonQuery(); + Assert.Equal(["@order_id"], db.Sent.Select(p => p.ParameterName)); + return new WeakReference(sql); + } + + // What is remembered about a text command does not keep its text alive. + [Fact] + public static void ATextCommandsSql_IsNotKeptAliveByWhatIsRemembered() + { + WeakReference weak = RunWithADynamicText(); + for (int i = 0; i < 3 && weak.IsAlive; i++) + { + GC.Collect(); + GC.WaitForPendingFinalizers(); + GC.Collect(); + } + + Assert.False(weak.IsAlive); + } + + // ---- concurrency ---- + + // One connection object serves every thread (so they share one remembered name set); each thread has its own fake database command. + sealed class ThreadConnection : DbConnection + { + public readonly ThreadLocal Commands = new(() => new()); + + [AllowNull] + public override string ConnectionString { get; set; } = ""; + public override string Database => "fake"; + public override string DataSource => "fake"; + public override string ServerVersion => "1.0"; + public override ConnectionState State => ConnectionState.Open; + public override void ChangeDatabase(string databaseName) { } + public override void Open() { } + public override void Close() { } + protected override DbTransaction BeginDbTransaction(IsolationLevel isolationLevel) => throw new NotSupportedException(); + protected override DbCommand CreateDbCommand() => Commands.Value!; + } + + sealed class SharedCommand(DbConnection connection, string procedure, ImmutableArray names) : ExpressiveDbCommand(connection, CommandType.StoredProcedure, procedure) + { + protected override ImmutableArray GetProcedureParameterNames(DbConnection connection, string procedure) => names; + } + + [Fact] + public static void ConcurrentExecutions_ShareOneNameSet_AndAllResolveTheSame() + { + string procedure = ParameterNameHarness.NewProcedure(); + ImmutableArray names = ["@order_id", "@customer_id", "@start_date"]; + var results = new System.Collections.Concurrent.ConcurrentBag(); + using var connection = new ThreadConnection(); + + Parallel.For(0, 1000, i => + { + DerivedParameterNameTests.RecordingDbCommand db = connection.Commands.Value!; + db.Sent.Clear(); + int orderId = i, customerId = i, startDate = i; + new SharedCommand(connection, procedure, names).AddParam(orderId).AddParam(customerId).AddParam(startDate).ExecuteNonQuery(); + results.Add(string.Join(",", db.Sent.Select(p => p.ParameterName))); + }); + + Assert.Equal(1000, results.Count); + Assert.All(results, r => Assert.Equal("@order_id,@customer_id,@start_date", r)); + } +}