Збудувати поновлювану ефемеральну бібліотеку для виконання
В Частина 1: Огонь і ДонM SK1t Досить Забудьте, ми досліджували теорію, що лежать за efeмерним виконанням - обмежені МSK2 приватні МSK3 розладнані асинкові робочі потоки, які пам 'ятають достатньо, щоб бути корисними і потім випаровуються
Ця стаття перетворює цей візерунок у відновлювану бібліотеку, яку можна завантажити в будь-який .NET проект.
NUGET!!!
Тепер це також є у mostlylucid.ephemerals Nuget пакеті більше, ніж 20 переважно зрозумілийM SK1нефемеральні шаблони і МSK2атоми.
Źródлі
Полний код є в mostlylucid.atoms - база GitHub
До і після
Тут ми заміняємо
// ❌ Before: Fire-and-forget black hole
_ = Task.Run(() => ProcessAsync(item));
// No visibility. No debugging. No idea if it worked.
// ❌ Or: Blocking everything
await ProcessAsync(item); // Hope you like waiting...
І те, що ми будуємо
// ✅ After: Trackable, bounded, debuggable
await coordinator.EnqueueAsync(item);
// Instant visibility
Console.WriteLine($"Pending: {coordinator.PendingCount}");
Console.WriteLine($"Active: {coordinator.ActiveCount}");
Console.WriteLine($"Failed: {coordinator.TotalFailed}");
// Full operation history
var snapshot = coordinator.GetSnapshot();
var failures = coordinator.GetFailed();
Те ж саме асинкельне виконання. Полна обсерваторністьM SK1 Жодних даних користувачів не зберігається.
Швидкий старт
Найпоширеніший візерунок - записує koordinatора в DI і вводить його :
// Program.cs
services.AddEphemeralWorkCoordinator<TranslationRequest>(
async (request, ct) => await TranslateAsync(request, ct),
new EphemeralOptions { MaxConcurrency = 8 });
// Your service
public class TranslationService(EphemeralWorkCoordinator<TranslationRequest> coordinator)
{
public async Task TranslateAsync(TranslationRequest request)
{
await coordinator.EnqueueAsync(request);
// Returns immediately - work happens in background
}
public object GetStatus() => new
{
pending = coordinator.PendingCount,
active = coordinator.ActiveCount,
completed = coordinator.TotalCompleted,
failed = coordinator.TotalFailed
};
}
Які варіанти мені потрібні?
┌─────────────────────────────────────────────────────────────────┐
│ DECISION TREE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Processing a collection once? │
│ └─► EphemeralForEachAsync<T> (ParallelEphemeral.cs) │
│ │
│ Need a long-lived queue that accepts items over time? │
│ └─► EphemeralWorkCoordinator<T> │
│ │
│ Need per-entity ordering (user commands, tenant jobs)? │
│ └─► EphemeralKeyedWorkCoordinator<TKey, T> │
│ │
│ Need to capture results (fingerprints, summaries)? │
│ └─► EphemeralResultCoordinator<TInput, TResult> │
│ │
│ Need multiple coordinators with different configs? │
│ └─► IEphemeralCoordinatorFactory<T> (like IHttpClientFactory) │
│ │
│ Need dynamic concurrency adjustment at runtime? │
│ └─► Set EnableDynamicConcurrency = true, call SetMaxConcurrency│
│ │
└─────────────────────────────────────────────────────────────────┘
Об 'єкт конфігурації
Від ЕфемерніOptions.cs:
public sealed class EphemeralOptions
{
// Concurrency control
public int MaxConcurrency { get; init; } = Environment.ProcessorCount;
public int MaxConcurrencyPerKey { get; init; } = 1;
public bool EnableDynamicConcurrency { get; init; } = false;
// Window management
public int MaxTrackedOperations { get; init; } = 200;
public TimeSpan? MaxOperationLifetime { get; init; } = TimeSpan.FromMinutes(5);
// Fair scheduling (keyed coordinator)
public bool EnableFairScheduling { get; init; } = false;
public int FairSchedulingThreshold { get; init; } = 10;
// Signal-reactive processing
public IReadOnlySet<string>? CancelOnSignals { get; init; }
public IReadOnlySet<string>? DeferOnSignals { get; init; }
public int MaxDeferAttempts { get; init; } = 10;
public TimeSpan DeferCheckInterval { get; init; } = TimeSpan.FromMilliseconds(100);
// Signal infrastructure
public SignalSink? Signals { get; init; }
public SignalConstraints? SignalConstraints { get; init; }
public Action<SignalEvent>? OnSignal { get; init; }
// Async signal handling
public Func<SignalEvent, CancellationToken, Task>? OnSignalAsync { get; init; }
public int MaxConcurrentSignalHandlers { get; init; } = 4;
public int MaxQueuedSignals { get; init; } = 1000;
// Observability
public Action<IReadOnlyCollection<EphemeralOperationSnapshot>>? OnSample { get; init; }
}
Головні рішення щодо дизайну
- Максконкуренція погані показники для підрахунку частоти процесора - розумний для процесора - обов 'язкова праця МSK2 для I/OM SK4 обов' язковапраця M SK5 підвищити його .
- Увімкніть Динамічний Конкуренс дозволяє врегулювати час запуску за допомогою
SetMaxConcurrency()- використовує custom gate замістьSemaphoreSlim. - Скасуватинаписи/DeferOnSignals зробити координатори сигналом-реактивними M SK1 вони реагують на стан системи довкілля ( підтримують співпадіння шаблонів
*/?/комма-листиM SK1 - Насвідчення є синхронним; для асинкового вентилятораM SK1за винятком використання
SignalDispatcherабоAsyncSignalProcessorвсередині обладнателя. - Сигнальні обмеження запобігає нескінченним циклам сигналів з виявленням циклу та обмеженнями глибини.
Записи з кадрів
Від Snapshots.cs:
public sealed record EphemeralOperationSnapshot(
long Id,
DateTimeOffset Started,
DateTimeOffset? Completed,
string? Key,
bool IsFaulted,
Exception? Error,
TimeSpan? Duration,
IReadOnlyList<string>? Signals = null,
bool IsPinned = false)
{
public bool HasSignal(string signal) => Signals?.Contains(signal) == true;
}
// For result-capturing coordinators
public sealed record EphemeralOperationSnapshot<TResult>(
long Id,
DateTimeOffset Started,
DateTimeOffset? Completed,
string? Key,
bool IsFaulted,
Exception? Error,
TimeSpan? Duration,
TResult? Result,
bool HasResult,
IReadOnlyList<string>? Signals = null,
bool IsPinned = false);
Це лише метадані. Зауважте, що не тут:
- Немає вантажу
- Немає вхідних даних
- Немає змісту для користувача
Просто достатньо, щоб відповісти: " що сталося? , коли МSK2 і це спрацювало?
Як це порівнює з іншими підходами
.NET дає вам декілька способів робити паралельну роботу . ТутM SK2 показує, як Ефемерна бібліотека порівнює:
Паралельно.ForEachAsync M SK1NET 6+)
await Parallel.ForEachAsync(items,
new ParallelOptions { MaxDegreeOfParallelism = 4 },
async (item, ct) => await ProcessAsync(item, ct));
Найкраще для: Проста паралельна обробка колекцій, де ви не маєте
Що йому бракує:
- Ніяких операційного відстеження
- Жодного послідовного виконання ключів per-
- Ніхто не бачить того, що запускається.
Використовуйте efeмерний, коли: Ви потребуєте виправленняM SK1наблюдливості , за МSK3показ ключів МSK4 або сигналу M SK5реактивного обробки .
Передача даних TPL
var block = new ActionBlock<T>(
async item => await ProcessAsync(item),
new ExecutionDataflowBlockOptions { MaxDegreeOfParallelism = 4 });
foreach (var item in items)
block.Post(item);
block.Complete();
await block.Completion;
Найкраще для: Комплексні канали потоку даних з відрізаннями , об 'єднання МSK2 пакетування M SK3
Що він робить добре:
- Поєднання багатих труб (з' єднання блоків зв 'язку МSK1
- Сконструйовано-в批ціM SK1 трансформація, трансляція
- Обмежена пропускна спроможність з спиною-притиск
Використовуйте TPL Dataflow, коли: Потрібні складні топології трубопроводу МSK1 вентилятор МSK2 вимкнуто , вентильатор
Використовуйте efeмерний, коли: Потрібно відстежувати рухи , простіший інтерфейс(API)
Система.ThreadingM SK1Channels
var channel = Channel.CreateBounded<T>(100);
// Producer
foreach (var item in items)
await channel.Writer.WriteAsync(item);
channel.Writer.Complete();
// Consumer (multiple workers)
var workers = Enumerable.Range(0, 4).Select(async _ =>
{
await foreach (var item in channel.Reader.ReadAllAsync())
await ProcessAsync(item);
});
await Task.WhenAll(workers);
Найкраще для: Виробник - Patternи споживача, де ви контролюєте обидві сторониM SK2
Що він робить добре:
- Прекрасна продуктивність
- Далі-приштовхування через обмежені канали
- Відокремлення виробників та споживачів
Використовувати канали: Ви ' будуєте на замовлення інфраструктуру і потребуєте максимального контролю МSK2
Використовуйте efeмерний, коли: Ви хочете відстеження і спостереження за рухом без панелі котлаM SK1
Полі
var policy = Policy
.Handle<HttpRequestException>()
.WaitAndRetryAsync(3, attempt => TimeSpan.FromSeconds(Math.Pow(2, attempt)));
await policy.ExecuteAsync(() => ProcessAsync(item));
Найкраще для: Политика стійкості
Використовуйте Поллі, коли: Потрібна гнучкість під час особистих дзвінків .
Використовуйте efeмерний, коли: Потрібно координувати багато операцій, усвідомлюючи довкілля
Об 'єднати їх: Використовуйте Polly всередині вашого ефемерального робочого тіла для
MassTransit / NServiceBus
Найкраще для: Розповсюджене повідомлення по всіх службах з довготривалими чергами .
Використовувати автобуси повідомлень, коли: Prace must survive process restarts , span multiple services МSK2 or require guaranteed delivery
Використовуйте efeмерний, коли: Prace is in-processM SK2 does not 't need durability МSK4 and you want lightweight observabilityMSC5
តារាង порівняння
| Досуг МSK1 Обмежений МSK2 Переслідування | Включний мSK4 Клінь M| Сигнали МСК6 Самовідтворення МК7 Чиszczenie МБС8 Сложність МПС9
|----------|:-------:|:--------:|:-------:|:-------:|:-------------:|:----------:|
| Parallel.ForEachAsync МSK0 ✅ ♫ ♫ МSK2 ♫
| Об 'єм даних ТПЛА МSK1 МSK2 | | | ❌\ | МSK5\ |❌\ \ |\ ❌\ ♫ |\ ・ ❌\ · |\ Wysoka
| Канали
МSK0 Поллі МSK1 N/A M SK3 ❌ ♫ ♫ МSK5 N ♫ /A
МSK0 Цілові послуги | МSK2 | MSК4 MSК5 МСК6 СМСК7 SМСК8 СМСК9 SМСК10 сМСК11 Середній msк12
| MassTransitM SK1NServiceBus
| Ефемерна бібліотека МSK0 ✅ ♫ ♫ МSK2 ♫
Ефемеральний для кожного asiнка: ОдинM SK1Shot Wersія
Від ПаралельноЕфемеральний.cs:
// Simple parallel processing with tracking
await items.EphemeralForEachAsync(
async (item, ct) => await ProcessAsync(item, ct),
new EphemeralOptions { MaxConcurrency = 8 });
// With keyed execution (per-user sequential)
await commands.EphemeralForEachAsync(
cmd => cmd.UserId, // Key selector
async (cmd, ct) => await ExecuteCommandAsync(cmd, ct),
new EphemeralOptions
{
MaxConcurrency = 32,
MaxConcurrencyPerKey = 1 // Sequential per user
});
Чому ключові трубопроводи мають значення
Уявіть процес obsługi команд користувача:
- Пользователь А надсилає команду 1, 2, ♫
- Пользователь B надсилає команду 4, 5, ♫
Без вмикання, вони можуть виконуватися так:
З MaxConcurrencyPerKey = 1:
- Команди користувача A' виконуються в порядку
- Команди користувача B' виконуються в порядку
- Але A і B можуть бігати паралельно
Це на "-", エンтітність послідовна МSK1 , глобально паралельна - вирішальне для систем, де порядок має значення в межах jednostkiM SK1
Координатор роботи: Довгий списокM SK1 Жива черга
Від Ефемеральний координатор роботи.cs:
await using var coordinator = new EphemeralWorkCoordinator<TranslationRequest>(
async (request, ct) => await TranslateAsync(request, ct),
new EphemeralOptions
{
MaxConcurrency = 8,
MaxTrackedOperations = 500,
EnableDynamicConcurrency = true // Allow runtime adjustment
});
// Enqueue items over time
await coordinator.EnqueueAsync(new TranslationRequest("Hello", "es"));
// Check status anytime
Console.WriteLine($"Pending: {coordinator.PendingCount}");
Console.WriteLine($"Active: {coordinator.ActiveCount}");
// Get snapshots
var snapshot = coordinator.GetSnapshot();
var running = coordinator.GetRunning();
var failed = coordinator.GetFailed();
var completed = coordinator.GetCompleted();
// Control flow
coordinator.Pause(); // Stop pulling new work
coordinator.Resume(); // Continue
// Adjust concurrency at runtime (requires EnableDynamicConcurrency)
coordinator.SetMaxConcurrency(16);
// Pin important operations to survive eviction
coordinator.Pin(operationId);
coordinator.Unpin(operationId);
coordinator.Evict(operationId);
// When done
coordinator.Complete();
await coordinator.DrainAsync();
Неперервні потоки з IAsyncEnumerable
await using var coordinator = EphemeralWorkCoordinator<Message>.FromAsyncEnumerable(
messageStream, // IAsyncEnumerable<Message>
async (msg, ct) => await ProcessMessageAsync(msg, ct),
new EphemeralOptions { MaxConcurrency = 16 });
await coordinator.DrainAsync();
Keyed Coordinator: Per-Entity Pipelines
Від Ефемеральний Керіаційний Koординатор:
await using var coordinator = new EphemeralKeyedWorkCoordinator<string, Command>(
cmd => cmd.UserId, // Key selector
async (cmd, ct) => await ExecuteCommandAsync(cmd, ct),
new EphemeralOptions
{
MaxConcurrency = 32,
MaxConcurrencyPerKey = 1, // Per-user sequential
EnableFairScheduling = true, // Prevent hot user starvation
FairSchedulingThreshold = 10 // Reject if user has 10+ pending
});
// TryEnqueue returns false if fair scheduling rejects
if (!coordinator.TryEnqueue(hotUserCommand))
{
await DeferCommandAsync(hotUserCommand);
}
// Per-key visibility
var pendingForUser = coordinator.GetPendingCountForKey("user-123");
var opsForUser = coordinator.GetSnapshotForKey("user-123");
Результат-Координатори захоплення
Від Ефемеральний координатор результатів.cs:
await using var coordinator = new EphemeralResultCoordinator<SessionInput, SessionResult>(
async (input, ct) =>
{
var fingerprint = await ComputeFingerprintAsync(input.Events, ct);
return new SessionResult(fingerprint, input.Events.Length);
},
new EphemeralOptions { MaxConcurrency = 16 });
await coordinator.EnqueueAsync(session);
coordinator.Complete();
await coordinator.DrainAsync();
// Get just the results (no metadata)
var results = coordinator.GetResults();
// Get snapshots with results + metadata
var snapshots = coordinator.GetSnapshot();
// Get base snapshots without results (privacy-safe)
var baseSnapshots = coordinator.GetBaseSnapshot();
// Filter by success/failure
var successful = coordinator.GetSuccessful();
var failed = coordinator.GetFailed();
Керування конкуренцією
Від ConcurrencyGates.cs:
Бібліотека забезпечує два механізми управління співпадінням:
FixedConcurrencyGate (DefaultM SK1
- Підтримований
SemaphoreSlim - Оптимальна гаряча
- Не можна підлаштувати на час запуску
РегулюванийConcurrencyGate
- Налаштування з
Queue<WaiterEntry> - Підтримка
UpdateLimit()під час запуску - Створено за допомогою
EnableDynamicConcurrency = true
// Dynamic concurrency adjustment
var coordinator = new EphemeralWorkCoordinator<T>(body,
new EphemeralOptions
{
MaxConcurrency = 4,
EnableDynamicConcurrency = true
});
// Later, based on system load:
coordinator.SetMaxConcurrency(16); // Scale up
coordinator.SetMaxConcurrency(2); // Scale down
Модель заводу: Визначні координатори
Від Залежність:
Як IHttpClientFactory, можна зареєструвати названі конфігурації
// Registration
services.AddEphemeralWorkCoordinator<TranslationRequest>("fast",
async (request, ct) => await FastTranslateAsync(request, ct),
new EphemeralOptions { MaxConcurrency = 32 });
services.AddEphemeralWorkCoordinator<TranslationRequest>("accurate",
async (request, ct) => await AccurateTranslateAsync(request, ct),
new EphemeralOptions { MaxConcurrency = 4 });
// Usage
public class TranslationService(IEphemeralCoordinatorFactory<TranslationRequest> factory)
{
private readonly EphemeralWorkCoordinator<TranslationRequest> _fast =
factory.CreateCoordinator("fast");
private readonly EphemeralWorkCoordinator<TranslationRequest> _accurate =
factory.CreateCoordinator("accurate");
}
Гарантії заводу
- Те ж саме ім 'я = та ж ситуація - Зателефонування
CreateCoordinator("fast")двічі повертає один і той самий координатор - Різні назви = різні випадки -
"fast"і"accurate"отримати окремі координатори - Звільне створення - Координатори створені тільки тоді, коли їх вперше запрошують
- Веріалізація конфігурації - Попросити нереєстроване ім 'я спричиняє допомічну помилку
Програмне забезпечення для тестування сигналів
Усі координатори запропонують оптимізовані методи пошуку сигналів:
// Get all signals
var signals = coordinator.GetSignals();
// Filter by key (zero-allocation)
var userSignals = coordinator.GetSignalsByKey("user-123");
// Filter by time range
var recentSignals = coordinator.GetSignalsSince(DateTimeOffset.UtcNow.AddMinutes(-5));
var rangeSignals = coordinator.GetSignalsByTimeRange(from, to);
// Filter by signal name or pattern
var rateSignals = coordinator.GetSignalsByName("rate-limit");
var httpSignals = coordinator.GetSignalsByPattern("http.*");
// Check existence (short-circuits on first match)
if (coordinator.HasSignal("rate-limit"))
await ThrottleAsync();
if (coordinator.HasSignalMatching("error.*"))
await AlertAsync();
// Count signals efficiently (no allocation)
var totalSignals = coordinator.CountSignals();
var errorCount = coordinator.CountSignals("error");
var httpCount = coordinator.CountSignalsMatching("http.*");
Оптимізації виробництва
швидке генерування
Від Ефемеральний IdGenerator.cs:
internal static class EphemeralIdGenerator
{
private static long _counter;
private static readonly long _processStart = Environment.TickCount64;
private static readonly int _processId = Environment.ProcessId;
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static long NextId()
{
var counter = Interlocked.Increment(ref _counter);
// Combine counter with process-unique seed
Span<byte> buffer = stackalloc byte[24];
BitConverter.TryWriteBytes(buffer, _processStart);
BitConverter.TryWriteBytes(buffer.Slice(8), _processId);
BitConverter.TryWriteBytes(buffer.Slice(16), counter);
return unchecked((long)XxHash64.HashToUInt64(buffer));
}
}
- Attribution-бесплатно (застосування
stackalloc) - Thread-safe (застосування
Interlocked.Increment) - Незвичайне в усіх процесах (включно з технологічним номером
- Не - послідовність (hash розповсюджує шкалуM SK1
Пам 'ять-Безпека довгаM SK1жива операційна система
Координатори не зберігають Task відмітки - просто рахункиM SK1
private int _activeTaskCount;
private readonly TaskCompletionSource _drainTcs;
// In ExecuteItemAsync:
finally
{
// Signal drain when last task completes AND channel iteration is done
if (Interlocked.Decrement(ref _activeTaskCount) == 0 &&
Volatile.Read(ref _channelIterationComplete))
{
_drainTcs.TrySetResult();
}
}
Per-Cleanup Key Lock
Координатор з ключем автоматично очищує пусті семафори на один ключ.
private sealed class KeyLock(SemaphoreSlim gate, int maxCount)
{
public SemaphoreSlim Gate { get; } = gate;
public int MaxCount { get; } = maxCount;
public long LastUsedTicks = Environment.TickCount64;
}
// Cleanup runs periodically, removes locks idle > 60 seconds
Повний приклад
// Program.cs
var builder = WebApplication.CreateBuilder(args);
// Named coordinators
builder.Services.AddEphemeralWorkCoordinator<TranslationRequest>("fast",
async (req, ct) => await FastTranslateAsync(req, ct),
new EphemeralOptions { MaxConcurrency = 16 });
// Keyed coordinator for per-user commands
builder.Services.AddEphemeralKeyedWorkCoordinator<string, UserCommand>("commands",
cmd => cmd.UserId,
sp =>
{
var handler = sp.GetRequiredService<ICommandHandler>();
return async (cmd, ct) => await handler.HandleAsync(cmd, ct);
},
new EphemeralOptions
{
MaxConcurrency = 32,
MaxConcurrencyPerKey = 1,
EnableFairScheduling = true,
CancelOnSignals = new HashSet<string> { "system-overload" }
});
var app = builder.Build();
// Controller
[ApiController]
[Route("api")]
public class WorkController : ControllerBase
{
private readonly EphemeralWorkCoordinator<TranslationRequest> _translator;
private readonly EphemeralKeyedWorkCoordinator<string, UserCommand> _commands;
public WorkController(
IEphemeralCoordinatorFactory<TranslationRequest> translationFactory,
IEphemeralKeyedCoordinatorFactory<string, UserCommand> commandFactory)
{
_translator = translationFactory.CreateCoordinator("fast");
_commands = commandFactory.CreateCoordinator("commands");
}
[HttpPost("translate")]
public async Task<IActionResult> Translate([FromBody] TranslationRequest request)
{
await _translator.EnqueueAsync(request);
return Ok(new { pending = _translator.PendingCount });
}
[HttpPost("command")]
public IActionResult SubmitCommand([FromBody] UserCommand command)
{
if (!_commands.TryEnqueue(command))
return StatusCode(429, "Too many pending commands for this user");
return Ok();
}
[HttpGet("status")]
public IActionResult GetStatus() => Ok(new
{
translator = new
{
pending = _translator.PendingCount,
active = _translator.ActiveCount,
completed = _translator.TotalCompleted,
failed = _translator.TotalFailed,
hasRateLimit = _translator.HasSignal("rate-limit")
},
commands = new
{
pending = _commands.PendingCount,
active = _commands.ActiveCount,
errorCount = _commands.CountSignalsMatching("error.*")
}
});
}
Завершення
Ми "'" створили повну ефемеральну бібліотеку з МСК1 .
EphemeralForEachAsync- ОдинM SK1 паралельна обробка кадрів з відстеженнямEphemeralWorkCoordinator- Довгий МSK1 живі обсерваційні чергиEphemeralKeyedWorkCoordinator- PerM SK1 послідовне виконання об 'єктів з правильним розкладомEphemeralResultCoordinator- Результат- Модель заводу - Наименовані конфігурації, як
IHttpClientFactory - Динамічне співпадіння - Регулювання паралелізму впродовж робочого часу
- Сигнальна інфраструктура - СконструйованийM SK1видача сигналу та пошук
Модель сидить у гарному місці:
- Більш помітно, ніж
Parallel.ForEachAsync - Простіше, ніж TPL Dataflow
- Більше інтегрованого, ніж сирові канали
- Prywatність-безпечна по дизайну
Огонь... і ДонM SK1 Не забувайш.
Ліки
- Частина 1: Огонь і ДонM SK1t Досить Забудьте - теорія і модель
- Частина 3: Невичерпні сигнали - перетворення атомів у сенсорну мережу
- Документація SemaphoreSlim
- Система.ThreadingM SK1Channels
- Передача даних TPL
- Модель IHttpClientFactory