Async
This convention defines how asynchronous code is written in the toolkit and in applications built on it, so that APIs and workers behave predictably under load and during shutdown.
Recommendation, not a requirement. The packages work without following this convention. It is a rule only for code in the toolkit repository (see Contributing); applications can adopt it, adapt it or skip it. Opting out or adapting explains how.
Why it matters
The toolkit’s workers, persistence policies and message brokers stop on cancellation; code that ignores tokens holds them up on shutdown and under retries. See the Predictable at runtime value.
In a short-lived host such as AWS Lambda, each invocation is bounded by the platform, so missing cancellation support is rarely visible.
Long-lived workers (Anarchy.Toolkit.Hosting.Workers on EC2 or ECS) are different. Without cancellation:
- long-running calls block processing loops,
- shutdown is delayed until in-flight calls complete or time out,
- retries and recovery become harder to reason about.
Apply these rules consistently, even in code that currently runs only in short-lived hosts.
Naming rule
Use the Async suffix for asynchronous methods.
Examples:
GetUserByIdAsyncRunInManagedSessionAsync(toolkit)ExecuteAsync(toolkit)
Cancellation rule
Expose an explicitly optional token on async methods:
CancellationToken? cancellationToken = null
Typical signature pattern (as in IStoragePolicy<TStorage>.ExecuteAsync):
Task<TResult> ExecuteAsync(..., CancellationToken? cancellationToken = null)
Call sites that have no token stay concise, while worker, host or request cancellation still flows through when a token is available.
Propagation rule
If a method accepts CancellationToken? cancellationToken = null, pass it downstream wherever supported.
For database queries specifically:
- use command-level cancellation (for example Dapper’s
CommandDefinition) for calls that can hang or run long, - keep simple, low-risk queries straightforward when cancellation is already bounded by other controls (timeouts, retries, short-lived operations).
CommandDefinition is not mandatory for every query; use it where a query can block for an unbounded time.
Example in a repository deriving from PostgresDbReaderRepositoryBase:
public async Task<IReadOnlyCollection<UserEntity>> GetPendingActivationAsync(CancellationToken? cancellationToken = null)
{
return await dbPolicy.ExecuteAsync(async (connEnvelope, callbackToken) => {
var token = cancellationToken ?? callbackToken ?? CancellationToken.None;
// Use CommandDefinition for potentially hanging or heavy queries.
var command = new CommandDefinition(
commandText: LoadSql("User.Get.PendingActivation"),
parameters: new { Limit = 100 },
cancellationToken: token
);
var rows = await connEnvelope.DataStorageConnection.QueryAsync<UserEntity>(command);
return rows.ToArray();
}, operationName: "User.Get.PendingActivation", cancellationToken: cancellationToken);
}
The operationName is also attached to the database-policy duration metric as the operation_name tag. When omitted, the policy falls back to the calling method’s call site.
Worker-focused guidance
In workers built on WorkerBase / MonitoredWorkerBase / ResilientWorkerBase:
- pass the worker’s
stoppingTokenfromRunIterationAsyncinto use cases and repositories, - make polling and publishing loops stoppable,
- avoid uncancelable network or database calls in shutdown paths.
Following these rules results in prompt shutdowns, fewer stuck operations and more predictable recovery for continuously running workers.
Opting out or adapting
| You want to… | Do this |
|---|---|
Keep methods without the Async suffix |
Nothing in the toolkit relies on names; only the analyzers you enable do. |
| Keep tokens required instead of optional | Fine: the toolkit’s bases accept any token you pass. |
| Ignore cancellation in short-lived hosts (Lambda) | Possible, but workers on Hosting.Workers then wait for in-flight calls on shutdown. |
What you lose by opting out: fast, clean shutdowns of long-running workers and consistent API signatures between your code and the toolkit’s.