UA-.NETStandard/docs/AsyncServerSupport.md

# Support of the TAP (Task Asynchronous Pattern) for server operations

The OPC UA .NET Standard stack has supported asynchronous operations for a long time. The asynchronous operations are based on the IAsyncResult pattern, which is also called the APM (Asynchronous Programming Model) or the Begin/End pattern. This pattern was introduced with .NET Framework 1.0 and is still supported in .NET 8.0.

In addition to the APM, the TAP (Task Asynchronous Pattern) is now also supported for server operations. The TAP is based on the Task and async/await keywords introduced in .NET Framework 4.0 and is the recommended way to implement asynchronous operations in modern .NET applications.

In the future APM support will be deprecated, as it was never implemented for NodeManagers.

Starting with 1.5.378 the server library allows users to also implement Task based NodeManagers.
Implementing the TAP allows to improve the scalability of the server, as the TAP is significantly more efficient in terms of resource usage and performance.

In order to support the TAP pattern, the following changes have been made to the server library:

- Introduce a Task based `RequestQueue`
- Introduce a Task based `TransportListenerCallback`
- Update the generated Code to support Task based operations
- Update of the `MasterNodeManager` to support Task based operations
- Introduce a Task based `IAsyncNodeManager` interface
- Introduce `AsyncNodeManagerAdapter` and `SyncNodeManagerAdapter` classes to support sync and async node managers side by side.

## Upgrading an existing server

- Update `INodeManager.CreateMonitoredItems` to support the new `MonitoredItemIdFactory`.
- In a future release an `CustomNodeManagerAsync` class will be provided to simplify the creation of fully async NodeManagers.
- The existing `CustomNodeManager2` class can be used as is, and async operations can be implemented as needed using the different interfaces provided by the server library:
  - `IAsyncNodeManager` for full async support
  - `ICallAsyncNodeManager` for async method calls
  - `IReadAsyncNodeManager` for async reading
  - `IWriteAsyncNodeManager` for async writing
  - `IHistoryReadAsyncNodeManager` for async history read
  - `IHistoryUpdateAsyncNodeManager` for async history update
  - `IConditionRefreshAsyncNodeManager` for async condition refresh
  - `ITranslateBrowsePathAsyncNodeManager` for async translate browse path
  - `IBrowseAsyncNodeManager` for async browsing
  - `ISetMonitoringModeAsyncNodeManager` for async monitoring mode changes
  - `ITransferMonitoredItemsAsyncNodeManager` for async monitored item transfer
  - `IDeleteMonitoredItemsAsyncNodeManager` for async monitored item deletion
  - `IModifyMonitoredItemsAsyncNodeManager` for async monitored item modification
  - `ICreateMonitoredItemsAsyncNodeManager` for async monitored item creation

--> The MasterNodeManager automatically detects if a NodeManager implements any of the async interfaces and uses the async implementation if available. If no async interface is implemented, the sync implementation is used.

- The Server already allows to register fully async NodeManagers, which implement the `IAsyncNodeManager` interface. To register a fully async Nodemanager use `StandardServer.RegisterNodeManager(IAsyncNodeManagerFactory)`.
  For compatibility reasons the IAsyncNodeManager has a property `SyncNodeManager`, this needs to be implemented by passing your IAsyncNodeManager to the `SyncNodeManagerAdapter`.

## Async Method call

Support for async method callbacks is already implemented by `CustomNodeManager2` to enable the support just add `IAsyncNodeManager` to your NodeManager implementation.
All generated code already has support for Async Methods e.g. `UpdateCertificateMethodState.OnCallAsync`. If the NodeManager implements `IAsyncNodeManager` the async callback is used automatically.
If a generic Method handler shall be used the `MethodState.OnCallMethod2Async` handler shall be used.

## AsyncCustomNodeManager

`AsyncCustomNodeManager` is the recommended base class for building fully async, TAP-native node managers.
Unlike the older `CustomNodeManager2`, it implements `IAsyncNodeManager` **directly** rather than
`INodeManager3`. This has two practical consequences:

- All virtual methods are `async ValueTask`-returning from the start, so there is no boilerplate
  wrapping of synchronous code inside `Task.Run` or similar helpers.
- The `SyncNodeManager` property (required by `IAsyncNodeManager`) is satisfied automatically: the
  constructor calls `this.ToSyncNodeManager()` and stores the resulting `INodeManager3` adapter.
  Callers that still require an `INodeManager3` reference (e.g. legacy subscription code) use that
  adapter; the node manager itself never needs to implement the synchronous interface.

### Registering an AsyncCustomNodeManager

Use the `IAsyncNodeManagerFactory` overload of `StandardServer.RegisterNodeManager`:

```csharp
server.RegisterNodeManager(context =>
    new MyAsyncNodeManager(server, configuration));
```

### Async browse iteration

Every hook a custom node manager overrides is awaitable, and that includes browsing.
`AsyncCustomNodeManager.BrowseAsync` and `TranslateBrowsePathAsync` iterate an
`INodeBrowser` through `NextAsync(CancellationToken)` rather than `Next()`, so a browser that
has to reach an underlying system — the aggregation case, where the references come from
another server — awaits that fetch on the first `NextAsync` instead of holding a request
worker on a blocking call. The default `NextAsync` wraps `Next()`, so the browsers the stack
ships and every existing custom browser keep working untouched. See
[NodeManagers.md](NodeManagers.md#threading-contract-for-nodes-and-browsers) for the browser contract.

### Locking strategy vs CustomNodeManager2

`CustomNodeManager2` protects its entire address space with a **single coarse-grained monitor
lock** stored in the `Lock` property:

```csharp
lock (Lock)
{
    // all reads and writes go through this single lock
}
```

While simple, this serialises all concurrent requests for the whole node manager and blocks the
calling thread, which prevents the use of `await` inside the critical section.

`AsyncCustomNodeManager` replaces this with a **two-tier, await-compatible locking model**:

#### 1. Global write semaphore — `m_writeSemaphore`

A `SemaphoreSlim(1, 1)` that serialises all **write** operations across the node manager.
Because it is a `SemaphoreSlim` it can be acquired with `await`:

```csharp
await m_writeSemaphore.WaitAsync(cancellationToken).ConfigureAwait(false);
try
{
    // safe to write any node
}
finally
{
    m_writeSemaphore.Release();
}
```

Only one write request runs at a time, preventing concurrent modifications of the address space.
Read operations do **not** acquire this semaphore.

#### 2. Monitored-item semaphore — `m_monitoredItemSemaphore`

A second `SemaphoreSlim(1, 1)` that serialises all **monitored-item management** operations
(create, modify, delete, set-monitoring-mode, subscribe-to-events, condition-refresh, transfer).
This keeps subscription state consistent without blocking reads or writes:

```csharp
await m_monitoredItemSemaphore.WaitAsync(cancellationToken).ConfigureAwait(false);
try
{
    // create / delete / modify monitored items
}
finally
{
    m_monitoredItemSemaphore.Release();
}
```

#### 3. Per-node locking for read and attribute access

Reads do not acquire any manager-wide lock. Instead they lock **only the individual `NodeState`
object** being accessed. This allows many reads to run truly in parallel across different nodes:

```csharp
lock (handle.Node)
{
    errors[ii] = handle.Node.ReadAttribute(
        systemContext,
        nodeToRead.AttributeId,
        nodeToRead.ParsedIndexRange,
        nodeToRead.DataEncoding,
        value);
}
```

The same per-node lock is used for the old-value read inside `WriteAsync` and for
`FindChildBySymbolicName` lookups in the component cache.

| Concern                          | `CustomNodeManager2`       | `AsyncCustomNodeManager`           |
|----------------------------------|----------------------------|------------------------------------|
| Address-space reads              | Global `lock (Lock)`       | Per-node `lock (node)` (parallel)  |
| Address-space writes             | Global `lock (Lock)`       | `await m_writeSemaphore` (serial)  |
| Monitored-item management        | Global `lock (Lock)`       | `await m_monitoredItemSemaphore`   |
| `await` inside critical section  | Not possible               | Supported everywhere               |
| Implemented interface            | `INodeManager3`            | `IAsyncNodeManager`                |

### Monitored-item manager selection

The constructor accepts an optional `useSamplingGroups` flag:

```csharp
// Default: change-triggered (MonitoredNodeMonitoredItemManager)
public MyNodeManager(IServerInternal server, ApplicationConfiguration config)
    : base(server, config) { }

// Opt-in: timer-based sampling (SamplingGroupMonitoredItemManager)
public MyNodeManager(IServerInternal server, ApplicationConfiguration config)
    : base(server, config, useSamplingGroups: true) { }
```

- **`MonitoredNodeMonitoredItemManager`** (default): node value changes are propagated to
  subscribers immediately by awaiting `NodeState.ClearChangeMasksAsync` after every successful
  write (see [Fully asynchronous change notifications](#fully-asynchronous-change-notifications)).
  No background threads are created per subscription.
- **`SamplingGroupMonitoredItemManager`**: a background timer thread samples the current node
  value at the negotiated `SamplingInterval`. Write changes are *not* pushed immediately; instead
  the next scheduled sample detects and delivers them.  Choose this mode when the data source
  produces values independently of OPC UA write requests (e.g. hardware polling).

### Fully asynchronous change notifications

`AsyncCustomNodeManager` propagates value changes and events to monitored items over a fully asynchronous push path, so no thread is blocked when a node exposes an asynchronous value read handler or when the per-node notification channel applies back-pressure.

`NodeState` exposes asynchronous counterparts of its change-notification API alongside the existing synchronous members:

| Synchronous | Asynchronous |
|-------------|--------------|
| `ClearChangeMasks(context, includeChildren)` | `ClearChangeMasksAsync(context, includeChildren, ct)` |
| `OnStateChanged` / `StateChanged` | `OnStateChangedAsync` / `StateChangedAsync` |
| `ReportEvent(context, e)` | `ReportEventAsync(context, e, ct)` |
| `OnReportEvent` | `OnReportEventAsync` |

The additions are non-breaking: existing synchronous callers and sinks continue to work unchanged. `MonitoredNodeMonitoredItemManager` wires the asynchronous sinks, so after a successful write `AsyncCustomNodeManager.WriteAsync` flushes changes with `await handle.Node.ClearChangeMasksAsync(...)`. The value for each monitored attribute is read at that moment through `NodeState.ReadAttributeAsync` — honoring an asynchronous `OnReadValueAsync` / `OnSimpleReadValueAsync` handler when one is registered — and the resulting snapshot is enqueued by awaiting the bounded per-node channel. Because the read is materialized before the change is enqueued, every notification carries the node value at the instant of the change (an enqueue-time snapshot); because both the read and the enqueue are awaited, the producing thread is never blocked.

The synchronous `ClearChangeMasks` / `ReportEvent` still drive the asynchronous sinks: they complete inline when the node is synchronously readable and the channel has capacity, and block the calling thread only when a genuinely asynchronous read is in flight or the channel is full. A synchronous node manager therefore keeps working without any change, paying a blocking cost only in those two cases.

Overflow and discard — the FIFO/LIFO `DiscardOldest` behavior and the `Overflow` status bit — remain a property of each monitored item's own queue. The shared per-node channel is a lossless conduit and does not drop notifications, so a monitored item's configured queue policy is always applied to the full stream of changes.

### Creating a custom node manager

Derive from `AsyncCustomNodeManager` and override only the virtual methods you need:

```csharp
public class MyNodeManager : AsyncCustomNodeManager
{
    public MyNodeManager(IServerInternal server, ApplicationConfiguration config)
        : base(server, config, "http://my.org/UA/Data/")
    {
    }

    public override async ValueTask CreateAddressSpaceAsync(
        IDictionary<NodeId, IList<IReference>> externalReferences,
        CancellationToken cancellationToken = default)
    {
        await base.CreateAddressSpaceAsync(externalReferences, cancellationToken)
                  .ConfigureAwait(false);

        // build your nodes here
        var myVar = new BaseDataVariableState(null);
        myVar.NodeId  = new NodeId("MyVar", NamespaceIndex);
        myVar.Value   = 42;
        await AddNodeAsync(SystemContext, default, myVar, cancellationToken)
              .ConfigureAwait(false);
    }
}
```