v5.3.3: NOMINMAX guards, thread safety documentation (Issue #24)

- Add #ifndef NOMINMAX guards to live_client_wrapper.cpp and
  live_blocking_wrapper.cpp preventing <windows.h> min/max macro
  conflicts (Issue #24)
- Add thread safety documentation to ILiveClient and
  ILiveBlockingClient interfaces documenting databento-cpp calling
  convention
- Add thread safety callout to README
- Add concurrent Subscribe pitfall to coding agent guide
- Create future_improvements.md for tracked polish items

Author: Alparse

CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to databento-dotnet will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.3.3] - 2026-05-29
+
+### Fixed
+
+- **Add NOMINMAX guards to native wrappers** — prevents `<windows.h>` min/max macro conflicts that could cause compilation failures with certain build configurations (Issue #24)
+
+### Changed
+
+- **Thread safety documentation** — added class-level and method-level thread safety remarks to `ILiveClient` and `ILiveBlockingClient` documenting the databento-cpp calling convention: complete all Subscribe calls before StartAsync, await each call sequentially
+- **README thread safety callout** — added thread safety guidance between LiveClient and LiveBlockingClient API reference sections
+- **Coding agent guide** — updated to v5.3.3, added pitfall #6 documenting concurrent Subscribe call risks with correct/incorrect code examples
+
 ## [5.3.2] - 2026-05-26
 
 ### Fixed

README.md

@@ -1,6 +1,6 @@
 # databento-dotnet
 
-[![NuGet](https://img.shields.io/badge/NuGet-v5.3.2-blue)](https://www.nuget.org/packages/Databento.Client)
+[![NuGet](https://img.shields.io/badge/NuGet-v5.3.3-blue)](https://www.nuget.org/packages/Databento.Client)
 [![Downloads](https://img.shields.io/badge/Downloads-18.4K-blue)](https://www.nuget.org/packages/Databento.Client)
 [![.NET](https://img.shields.io/badge/.NET-8.0%20%7C%209.0-purple)](https://dotnet.microsoft.com/)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
@@ -329,6 +329,8 @@ client.DataReceived += (s, e) => { };
 client.ErrorOccurred += (s, e) => { };
 ```
 
+> **Thread safety:** `SubscribeAsync` is not thread-safe. Always `await` each call sequentially and complete all subscriptions before calling `StartAsync`. The `await` pattern shown above naturally serializes calls and is safe by construction. This mirrors the databento-cpp calling convention.
+
 ### LiveBlockingClient
 
 Pull-based API for explicit control over record retrieval:

Readme_For_Coding_Agents.md

@@ -2,7 +2,7 @@
 
 > **For AI coding agents**: This document is optimized for programmatic consumption by agentic code tools (Claude Code CLI, Cursor, GitHub Copilot Workspace, etc.). Use this as your primary reference when working with the Databento.Client library.
 
-**Library**: `Databento.Client` v5.1.4
+**Library**: `Databento.Client` v5.3.3
 **Package**: `dotnet add package Databento.Client`
 **Runtime**: .NET 8.0 / 9.0
 **Platforms**: Windows x64 (NuGet) | Linux/macOS (build from source)
@@ -450,6 +450,20 @@ await client.StartAsync();
 await foreach (var record in client.StreamAsync()) { }
 ```
 
+### 6. Concurrent Subscribe Calls (Thread Safety)
+```csharp
+// WRONG - Data race in native layer (unsynchronized socket writes and std::vector mutation)
+var t1 = Task.Run(() => client.SubscribeAsync("GLBX.MDP3", Schema.Mbp1, new[] { "ESM5" }));
+var t2 = Task.Run(() => client.SubscribeAsync("GLBX.MDP3", Schema.Trades, new[] { "NQM5" }));
+await Task.WhenAll(t1, t2);
+
+// CORRECT - Await each call sequentially, then start
+await client.SubscribeAsync("GLBX.MDP3", Schema.Mbp1, new[] { "ESM5" });
+await client.SubscribeAsync("GLBX.MDP3", Schema.Trades, new[] { "NQM5" });
+await client.StartAsync();
+```
+`SubscribeAsync` is not thread-safe. Using `await` on each call naturally serializes them and mitigates this risk. This mirrors the databento-cpp calling convention where thread safety is by design (single-threaded setup), not by enforcement (no internal locks).
+
 ---
 
 ## Method Signatures Quick Reference

future_improvements.md

@@ -0,0 +1,45 @@
+# Future Improvements
+
+## Polish
+
+### Safe (non-breaking)
+
+**1. Add logging to `SubscribeWithSnapshotAsync` in `LiveClient.cs`**
+- File: `src/Databento.Client/Live/LiveClient.cs` (lines ~327-370)
+- `SubscribeAsync` logs on entry and success. `SubscribeWithSnapshotAsync` has zero logging.
+- Fix: Add `_logger.LogInformation(...)` for entry and success to match `SubscribeAsync` pattern.
+
+**2. Inline unnecessary local variable in `BlockUntilStoppedAsync` in `LiveClient.cs`**
+- File: `src/Databento.Client/Live/LiveClient.cs` (line ~880)
+- `var streamTask = Interlocked.CompareExchange(ref _streamTask, null, null);` assigns to a variable only used for a null check.
+- Fix: Change to `if (Interlocked.CompareExchange(ref _streamTask, null, null) == null)`.
+- Note: Same pattern exists in the `BlockUntilStoppedAsync(TimeSpan timeout, ...)` overload.
+
+### Potentially Breaking
+
+**3. Add `ConfigureAwait(false)` to `StreamAsync` in `LiveClient.cs`**
+- File: `src/Databento.Client/Live/LiveClient.cs` (line ~615)
+- `await foreach (var record in _recordChannel.Reader.ReadAllAsync(cancellationToken))` is missing `.ConfigureAwait(false)`.
+- Standard best practice for library code — not having it can cause deadlocks in environments with a `SynchronizationContext`.
+- **Why breaking:** Changes thread affinity for callers using the library in WPF, WinForms, or ASP.NET apps with a `SynchronizationContext`. Their `await foreach` would resume on a thread pool thread instead of their original context. We don't know all use cases of this library.
+
+**4. Remove `async`/`await Task.CompletedTask` from `ResubscribeAsync` in `LiveClient.cs`**
+- File: `src/Databento.Client/Live/LiveClient.cs` (lines ~568-586)
+- Method is marked `async` and ends with `await Task.CompletedTask`. The `async` keyword generates a state machine for no reason — the method is entirely synchronous (P/Invoke call).
+- Correct pattern: remove `async`, return `Task.CompletedTask` (same as `SubscribeAsync` does).
+- **Why breaking:** With `async`, exceptions from the P/Invoke are captured into the returned `Task` and thrown at the `await` site. Without `async`, exceptions throw synchronously at the call site. For callers who `await` immediately, no difference. For callers who capture the `Task` and `await` later, the exception timing changes.
+
+**5. Replace `ConcurrentBag` with `List` for `_subscriptions` in `LiveClient.cs`**
+- File: `src/Databento.Client/Live/LiveClient.cs` (line ~38)
+- `ConcurrentBag` was a defensive choice. All writes (`_subscriptions.Add`) happen during `SubscribeAsync` which is synchronous and completes before `StartAsync`. After `Start`, the collection is read-only. `List` is safe for concurrent reads with no concurrent writes.
+- databento-cpp uses a plain `std::vector` — `ConcurrentBag` is a fidelity divergence.
+- The comment "HIGH FIX: Use thread-safe collection for concurrent subscription operations" was added during a code quality pass but the concurrent write scenario doesn't materialize in the current code. `ResubscribeAsync` uses native resubscribe (`dbento_live_resubscribe`), not the managed collection.
+- `ConcurrentBag` is on the cold setup path (not the hot data path) and has zero overhead when uncontended, so it's harmless. It differs from `SemaphoreSlim` (which would serialize P/Invoke operations on the hot path).
+- **Why breaking:** If a code path exists that we haven't identified where a background thread accesses `_subscriptions`, replacing with `List` introduces a race condition. Requires thorough analysis and testing before changing.
+
+### Cosmetic (low priority)
+
+**6. Shorten `Models.Dbn.DbnMetadata` references in `LiveClient.cs`**
+- File: `src/Databento.Client/Live/LiveClient.cs`
+- Fully qualified `Models.Dbn.DbnMetadata` is used throughout. Could add a `using` directive and use `DbnMetadata`.
+- Purely cosmetic, zero runtime impact. Not worth the churn unless touching the file for other reasons.

src/Databento.Client/Databento.Client.csproj

@@ -9,7 +9,7 @@
 
     <!-- Package Information -->
     <PackageId>Databento.Client</PackageId>
-    <Version>5.3.2</Version>
+    <Version>5.3.3</Version>
     <Authors>Alparse</Authors>
     <Company>Databento</Company>
     <Product>databento-dotnet</Product>
@@ -20,7 +20,7 @@
     <RepositoryType>git</RepositoryType>
     <PackageProjectUrl>https://github.com/Alparse/databento-dotnet</PackageProjectUrl>
     <PackageReadmeFile>README.md</PackageReadmeFile>
-    <PackageReleaseNotes>v5.3.1: Fix Record.FromBytes failing when ts_out is enabled — records now deserialize correctly with the extra 8-byte gateway timestamp. Added TsOutNs and TsOut properties to expose the gateway send timestamp (Issue #23).</PackageReleaseNotes>
+    <PackageReleaseNotes>v5.3.3: Add NOMINMAX guards to native wrappers fixing min/max macro conflicts (Issue #24). Add thread safety documentation to ILiveClient, ILiveBlockingClient, README, and coding agent guide.</PackageReleaseNotes>
     <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
 
     <!-- XML Documentation -->

src/Databento.Client/Live/ILiveBlockingClient.cs

@@ -8,15 +8,27 @@ namespace Databento.Client.Live;
 /// Provides synchronous control over record retrieval via StartAsync/NextRecordAsync.
 /// </summary>
 /// <remarks>
+/// <para>
 /// This is the pull-based API counterpart to LiveClient (LiveThreaded).
 /// Use this when you want explicit control over when records are retrieved,
 /// as opposed to push-based event/callback delivery.
+/// </para>
+/// <para>
+/// <b>Thread safety:</b> All Subscribe calls must complete before calling <see cref="StartAsync"/>.
+/// Subscribe methods are not thread-safe — do not call them concurrently or after the stream has started.
+/// Using <c>await</c> on each call naturally serializes them and mitigates this risk.
+/// This mirrors the databento-cpp LiveBlocking calling convention where the Subscribe path performs
+/// unsynchronized socket writes.
+/// </para>
 /// </remarks>
 public interface ILiveBlockingClient : IAsyncDisposable
 {
     /// <summary>
     /// Subscribe to a dataset and schema
     /// </summary>
+    /// <remarks>
+    /// Not thread-safe. Await each call and complete all subscriptions before calling <see cref="StartAsync"/>.
+    /// </remarks>
     /// <param name="dataset">Dataset to subscribe to (e.g., "EQUS.MINI")</param>
     /// <param name="schema">Schema type to receive</param>
     /// <param name="symbols">List of symbols to subscribe to</param>

src/Databento.Client/Live/ILiveClient.cs

@@ -6,6 +6,13 @@ namespace Databento.Client.Live;
 /// <summary>
 /// Live streaming client for real-time market data
 /// </summary>
+/// <remarks>
+/// <b>Thread safety:</b> All Subscribe calls must complete before calling <see cref="StartAsync"/>.
+/// Subscribe methods are not thread-safe — do not call them concurrently or after the stream has started.
+/// Using <c>await</c> on each call naturally serializes them and mitigates this risk.
+/// This mirrors the databento-cpp calling convention where thread safety is by design (single-threaded setup),
+/// not by enforcement (no internal locks).
+/// </remarks>
 public interface ILiveClient : IAsyncDisposable
 {
     /// <summary>
@@ -21,6 +28,9 @@ public interface ILiveClient : IAsyncDisposable
     /// <summary>
     /// Subscribe to a data stream (matches databento-cpp Subscribe overloads)
     /// </summary>
+    /// <remarks>
+    /// Not thread-safe. Await each call and complete all subscriptions before calling <see cref="StartAsync"/>.
+    /// </remarks>
     /// <param name="dataset">Dataset name (e.g., "GLBX.MDP3")</param>
     /// <param name="schema">Schema type</param>
     /// <param name="symbols">List of symbols to subscribe to</param>

src/Databento.Native/src/live_blocking_wrapper.cpp

@@ -1,4 +1,7 @@
-#define NOMINMAX  // Prevent Windows min/max macros from interfering with std::numeric_limits
+#ifndef NOMINMAX
+# define NOMINMAX
+#endif
+
 #include "databento_native.h"
 #include "common_helpers.hpp"
 #include "handle_validation.hpp"

src/Databento.Native/src/live_client_wrapper.cpp

@@ -1,3 +1,7 @@
+#ifndef NOMINMAX
+# define NOMINMAX
+#endif
+
 #include "databento_native.h"
 #include "common_helpers.hpp"
 #include "handle_validation.hpp"