# IRunCancellationRegistry

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.iruncancellationregistry/
> Summary: IRunCancellationRegistry: The in-memory registry of runs in progress on this instance; binds an incoming cancellation request to the running run's Threading.CancellationTokenSource.

<div class="api-provenance">Namespace Tracon · Assembly <code>Tracon.Abstractions.dll</code></div>

The in-memory registry of runs in progress on this instance; binds an
incoming cancellation request to the running run's
[CancellationTokenSource](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtokensource).

```csharp
public interface IRunCancellationRegistry
```

## Remarks

The registry is **in-process**. In a multi-instance
deployment, a request may land on the wrong instance; in that case the
cancellation endpoint returns `409 Conflict`. A setup that needs a
distributed registry can replace this interface with its own
implementation (`TryAddSingleton`).

Cancelling the root run (`RunId == RootRunId`) also cancels every
record under the same `RootRunId`. Cancelling a single child run
affects neither sibling branches nor the root.

**Tenant behavior.**
[IRunCancellationRegistry.Register](/api/tracon.iruncancellationregistry/#Tracon_IRunCancellationRegistry_Register_System_Guid_System_Guid_System_String_System_Threading_CancellationTokenSource_) and [IRunCancellationRegistry.TryCancel](/api/tracon.iruncancellationregistry/#Tracon_IRunCancellationRegistry_TryCancel_System_Guid_System_String_) take an EXPECTED
tenant as an explicit parameter — never the ambient tenant, since the
caller's own thread may not belong to the run's tenant.
[IRunCancellationRegistry.ActiveCount](/api/tracon.iruncancellationregistry/#Tracon_IRunCancellationRegistry_ActiveCount) and [IRunCancellationRegistry.ActiveRunIds](/api/tracon.iruncancellationregistry/#Tracon_IRunCancellationRegistry_ActiveRunIds) are
TENANT-INDEPENDENT: this is in-process diagnostic state covering every
tenant's runs on this instance at once, by design (`RunHeartbeatWriter`
needs the whole set, not one tenant's slice).

## Properties

### <a id="Tracon_IRunCancellationRegistry_ActiveCount"></a> ActiveCount

The number of runs in progress on this instance. For diagnostics and tests.

```csharp
int ActiveCount { get; }
```

#### Property Value

 [int](https://learn.microsoft.com/dotnet/api/system.int32)

### <a id="Tracon_IRunCancellationRegistry_ActiveRunIds"></a> ActiveRunIds

The identifiers of the runs currently in progress on this instance.

```csharp
IReadOnlyCollection<Guid> ActiveRunIds { get; }
```

#### Property Value

 [IReadOnlyCollection](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlycollection\-1)<[Guid](https://learn.microsoft.com/dotnet/api/system.guid)\>

#### Remarks

`RunHeartbeatWriter` uses this list to write heartbeats only for runs
THIS process is actually executing. Another instance marking a Running row as
"alive" by mistake would defeat the entire purpose of reconciliation.

## Methods

### <a id="Tracon_IRunCancellationRegistry_Register_System_Guid_System_Guid_System_String_System_Threading_CancellationTokenSource_"></a> Register\(Guid, Guid, string?, CancellationTokenSource\)

Writes a running run into the registry.

```csharp
IDisposable Register(Guid runId, Guid rootRunId, string? tenantId, CancellationTokenSource source)
```

#### Parameters

`runId` [Guid](https://learn.microsoft.com/dotnet/api/system.guid)

The run's identifier.

`rootRunId` [Guid](https://learn.microsoft.com/dotnet/api/system.guid)

The identifier of the run at the root of the tree. Equals
`runId`
for the root.

`tenantId` [string](https://learn.microsoft.com/dotnet/api/system.string)?

The run's tenant.

`source` [CancellationTokenSource](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtokensource)

The source that triggers the run's cancellation. Ownership stays with the
caller; this method does not dispose it.

#### Returns

 [IDisposable](https://learn.microsoft.com/dotnet/api/system.idisposable)

The object to dispose to remove the record from the registry.

### <a id="Tracon_IRunCancellationRegistry_TryCancel_System_Guid_System_String_"></a> TryCancel\(Guid, string?\)

Requests a run's cancellation. If it is the tree root, child runs are also cancelled.

```csharp
bool TryCancel(Guid runId, string? tenantId)
```

#### Parameters

`runId` [Guid](https://learn.microsoft.com/dotnet/api/system.guid)

The identifier of the run whose cancellation is requested.

`tenantId` [string](https://learn.microsoft.com/dotnet/api/system.string)?

The requesting tenant. If it does not match the record's tenant, the request is ignored.

#### Returns

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

[true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) if the cancellation request reached a record.

#### Remarks

**Guarantee limit: cancellation is cooperative, not forced.** This
method only calls [CancellationTokenSource.Cancel](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtokensource)
on the token registered with the matching [IRunCancellationRegistry.Register](/api/tracon.iruncancellationregistry/#Tracon_IRunCancellationRegistry_Register_System_Guid_System_Guid_System_String_System_Threading_CancellationTokenSource_) call; it does
not force the run's body to stop. A [true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) return means the
signal reached a registered record, not that the run has actually stopped — a
run body that reads its token late, catches
[OperationCanceledException](https://learn.microsoft.com/dotnet/api/system.operationcanceledexception), or ignores the token altogether keeps
running (and, if it calls a billed model provider, keeps accruing cost) until it
chooses to observe the cancellation.