Введение

• А что на картинке?
• Внешние ссылки

Работа с библиотекой ActiveSession

• Получение доступа к активному сеансу из обработчика запроса
• Работа с активным сеансом.
  
  • Создание нового исполнителя.
  • Получение существующего исполнителя
  • Прекращение активного сеанса.
  • Связывание данных с активным сеансом и отслеживание завершения и очистки активного сеанса.
  • Идентификация активного сеанса.
  • Внешний идентификатор исполнителя для клиентской части веб-приложения
  • Другие методы и свойства интерфейса активного сеанса
  • Примеры работы с активным сеансом
• Библиотека ActiveSession и внедрение зависимостей
  
  • Получение сервисов с временем жизни Scoped для использования исполнителями
  • Использование сервисов с временем жизни Scoped, полученных из контейнера активного сеанса, которые не поддерживают параллельный доступ к ним.
• Работа с исполнителем
  
  • Состояние исполнителя. (в скрытом тексте)
  • Исполнители последовательностей. (в скрытом тексте)
  • Методы получения результатов.
  • Получение информации о процессе фонового выполнения.
  • Прерывание выполнения исполнителя.
  • Отслеживание завершения работы и очистки исполнителя
  • Примеры работы с исполнителями.

Классы стандартных исполнителей библиотеки ActiveSession

• Классы-адаптеры для внешних последовательностей.
• Класс исполнителя, создающего временные ряды.
• Класс исполнителя сеансового процесса.

Заключение

Так же как и в основной статье, картинка в этой статье изображает диаграмму одного из вариантов жизненного цикла исполнителя.
Обозначения на этой диаграмме — следующие:

• толстые линии со стрелками обозначают основной поток управления веб-приложения: взаимодействия браузера с веб-сервером, приводящие к загрузке веб-страниц и отображение загруженных веб-страниц вместе с исполнением размещенных на них сценариев; в данном примере есть две веб страницы: с одной из них (она отображена частично и подробно не рассматривается) посылается запрос POST на сервер, другая же отображает результат выполнения этого запроса, время от времени подгружая дополнительные данные, полученные исполнителем в фоновом режиме.
• линии средней толщины (тоже со стрелками) обозначают запросы сценария на веб-странице к серверу;
• тонкие линии отображают взаимодействие обработчиков запросов с библиотекой ActiveSession и, в частности, с исполнителем.
• прерывистые и пунктирные линии отображают работу исполнителя: прерывистая линия показывает исполнитель, в работающий в фоновом режиме, а пунктирная — тот же исполнитель, до начала и после завершения фоновой операции.

А вот жизненный цикл исполнителя для данного примера — другой.

1. Обработчик запроса POST на сервере создает исполнитель (вызовом IActiveSession.CreateRunner), запускает его фоновый процесс и возвращает начальный результат (всё это — вызовом метода IRunner.GetRequiredAsync). Обработчик запроса формирует страницу, отображающую этот результат, и возвращает ее браузеру. Фоновый процесс исполнителя при этом продолжает выполняться на сервере, а инфраструктура библиотеки ActiveSession удерживает в своем хранилище ссылку на этот исполнитель.
2. Браузер отображает полученную страницу и выполняет размещенный на ней сценарий, подгружающий дополнительные данные.
3. Сценарий с определенным интервалом делает запросы к точке вызова API на сервере с использованием fetch().
4. Обработчик точки вызова API находит исполнитель, запрашивает у него текущий результат вместе с состоянием и отправляет их сценарию в браузере в качестве ответа.
5. Сценарий, получив ответ, изменяет содержимое страницы, чтобы отобразить полученный результат.
6. После первых двух полученных ответов сценарий обнаруживает, что исполнитель ещё выполняется, и планирует следующий запрос к точке вызова API сервера.
7. После получения второго ответа пользователь увидел, что ему нужно, и послал команду на прекращение выполнения исполнителя (например, нажал на кнопку на странице). Эта команда была преобразована сценарием на странице в обращение к соответствующей точке вызова API.
8. Обработчик точки вызова API нашел исполнитель и вызвал метод прерывания его работы. Исполнитель в результате вызова этого метода перешел в завершающую стадию. Инфраструктура библиотеки ActiveSession, обнаружив завершение исполнителя, удаляет ссылку на него из хранилища. Теперь объект исполнителя может быть утилизирован сборщиком мусора.
9. После отправки команды прекращения работы исполнителя сценарий отменил периодические запросы к точке вызова API сервера.

То есть, пользователь в этом примере не стал дожидаться окончания фонового выполнения исполнителя, а послал команду прервать его выполнение. И обработчик точки вызова API прервал выполнение.

В интерфейсе IActivesession определена также асинхронная версия метода для нахождения существующего исполнителя, GetRunnerAsync:

ValueTask<IRunner<TResult>?> GetRunnerAsync<TResult>(     int RunnerNumber,     HttpContext Context,      CancellationToken CancellationToken = default ); 

В отличие от синхронной версии метод GetRunnerAsync принимает дополнительный параметр CancellationToken, дающий возможность отмены операции поиска, а возвращает этот метод значение ValueTask<IRunner<TResult>?> — задачу, результатом которой является найденный исполнитель (или null). В нынешнюю версию библиотеки этот метод добавлен «на вырост»: он предназначен для нахождения исполнителей на удаленных узлах, а в нынешней версии реализация этой функции — пока что только в планах. Ну, а для локальных исполнителей он всегда выполняется синхронно и возвращает завершенную задачу.

В текущей версии библиотеки это не важно, но другое отличие сохраняемых в Properties объектов от значений сохраняемых в сеансе ASP.NET Core — в том, что эти объекты локальны для каждого узла, на котором выполняется приложение, использующее библиотеку ActiveSession. При использовании последующих версий библиотеки, которые смогут поддерживать активные сеансы, распространяющиеся на несколько узлов, это отличие может стать существенным.

Свойство Id (идентификатор) активного сеанса — строка, состоящая из основной части и, возможно, суффикса. Основная часть идентификатора — одинаковая для всех активных сеансов в сеансе ASP.NET Core, представляемом интерфейсом ISession. Ее значение хранится в переменных этого сеанса (когда-то она просто совпадала с ISession.Id, но потом по соображениям безопасности получила отдельное значение. Суффикс предназначен для различения разных активных сеансов, связанных с одним сеансом ASP.NET Core. В текущей версии библиотеки суффикс не используется, так что с одним сеансом ASP.NET Core в данной версии может быть связан только один существующий на текущий момент активный сеанс.

Сам по себе идентификатор — свойство Id — однозначно определяет активный сеанс среди других существующих на текущий момент сеансов. Но среди всех вообще активных сеансов — и доступных в текущий момент, и уже завершенных, и тех, которые могут быть созданы — этот идентификатор однозначно активный сеанс не определяет: для некоторых из таких сеансов значения свойства Id могут совпадать. Полностью активный сеанс однозначно определяется только комбинацией идентификатора (Id) и номера поколения (Generation).

Свойство Generation содержит номер поколения активного сеанса: которым по счету был создан этот активный сеанс среди сеансов c тем же Id. Значение этого свойство, наряду со значением свойства Id, составляет идентификатор активного сеанса, входящий во внешний идентификатор исполнителя (о нем см. далее в этой главе).

Свойство SessionServices содержит ссылку на контейнер сервисов для ограниченной области, связанной с данным активным сеансом. Эта область существует, пока существует активный сеанс. Контейнер, на который ссылается это свойство, предназначен для получения сервисов с временем жизни ограниченной области (Scoped), которые можно использовать в исполнителях, работающих в этом активном сеансе — либо используя свойство SessionServices в качестве Service Locator, либо путем внедрения зависимостей через предназначенные для этого сервисы-адаптеры (они будут рассмотрены в следующей главе). А так как внедрение зависимостей является предпочтительным способом работы с контейнером сервисов, то прямая ссылка на контейнер сервисов активного сеанса не предназначена для широкого использования, а потому информация о ней убрана в скрытый текст.

Свойство IsFresh устанавливается в true при создании активного сеанса и сбрасывается в false при создании в нем первого исполнителя. Его можно использовать в обработчике текущего запроса для того, чтобы узнать, исполняются ли сейчас и исполнялись ли вообще в текущем активном сеансе какие-либо исполнители.

Метод TrackRunnerCleanup возвращает задачу, которая завершится по завершении выполнения и очистки (если таковая требуется) исполнителя с указанным номером. Если исполнитель с указанным номером в сеансе не зарегистрирован, то этот метод вернет null. Этот метод используется, в частности, самой библиотекой совместно с функцией эксклюзивного доступа к сервисам из контейнера активного сеанса для своевременного освобождения блокировки по завершении исполнителя, для которого эта блокировка предназначена (такое использование описано в следующей главе, см. описание метода CreateRunnerWithExclusiveService).

Pages\SequenceAdapterParams.cshtml.cs

        //Come here after the data are entered to the form on the page          //(the page template is beyond the scope of the example)         public ActionResult OnPost()          {             if(ModelState.IsValid) {                  //Make some input processing                 // IEnumerable<SimSeqData> sync_source;                 //...                  //Obtain a reference on the active session object for this request                 IActiveSession session= HttpContext.GetActiveSession();                  //Check that the active session is available                 if(session.IsAvailable) {                      //Create a new runner                     (var runner, int runner_number)= session.CreateSequenceRunner(sync_source, HttpContext);                      //This part will be explained later                       //in an external runner identifier usage example                     ExtRunnerKey key = (session, runner_number); //Make an external identifier                     //Pass the external identifier by a part of the redirection URL path                     return RedirectToPage("SequenceShowResults", new { key });                  }                 else //An active session is unavailable                      return StatusCode(StatusCodes.Status500InternalServerError);             }             //Repeat input due to invalid data entered             return Page();         }

APIControllers\SampleController.cs

    [HttpPost("[action]")]     public IActionResult TerminateSession()     {         IActiveSession session = HttpContext.GetActiveSession();         if(session.IsAvailable) {             session.Terminate(HttpContext);             return StatusCode(StatusCodes.Status204NoContent);         }         else return StatusCode(StatusCodes.Status500InternalServerError);     } 

В примере производится прекращение выполнения исполнителя связанного со страницей HTML, сформированной с помощью фреймворка Razor Pages.

1.Внешний идентификатор исполнителя сохраняется в поле _key класса модели страницы, доступном для соответствующего шаблона Razor Page (код сохранения не показан).

Pages\TimeSeriesResults.cshtml.cs

    public class TimeSeriesResultsModel : PageModel     {         internal ExtRunnerKey _key;         }         //...     }

2.С помощью шаблона Razor Page на основе значения вышеупомянутого поля класса модели страницы устанавливается значение глобальной переменной JavaScript в результирующей HTML-странице, чтобы она содержала внешний идентификатор связанного с ней исполнителя. Затем внешний идентификатор исполнителя передается из обработчика выгрузки HTML-страницы конечной точке API Abort для завершения связанного исполнителя.

Pages\TimeSeriesResults.cshtml

@page "{key}" @model SampleApplication.Pages.TimeSeriesResultsModel <!-- ... -->  <script>     var pollInterval = @Model._timeoutMsecs;     var runner_key = {          RunnerNumber: @Model._key.RunnerNumber,         Generation: @Model._key.Generation,         _ActiveSessionId: "@(WebUtility.UrlEncode( Model._key.ActiveSessionId))",         get ActiveSessionId() { return decodeURI(this._ActiveSessionId); }     },       window.onunload = function () {         let request = {             RunnerKey: runner_key,         }         fetch("@Model._AbortEndpoint", {             method: "POST",             headers: {                "Content-type": "application/json;charset=utf-8"             },             keepalive: true,             body: JSON.stringify(request)         });     } </script>

3.Обработчик (метод действия контроллера API MVC) проверяет, работает ли он в том же активном сеансе, в котором был создан исполнитель. Если это так, то обработчик получает типонезависимый интерфейс этого исполнителя и прекращает его выполнение вызовом метода Abort полученного интерфейса. Использование типонезависимого интерфейса позволяет применять один и тот же обработчик API при закрытии разных страниц, с которыми могут быть связаны исполнители с разными типами результата.

APIControllers\SampleController.cs

    [HttpPost("[action]")]     public ActionResult<AbortResponse> Abort(AbortRequest Request)     {         IActiveSession session = HttpContext.GetActiveSession();         if(session.IsAvailable && Request.RunnerKey.IsForSession(session)) {             var runner = session.GetNonTypedRunner(Request.RunnerKey.RunnerNumber, HttpContext);             if(runner!=null) {                 AbortResponse response = new AbortResponse();                 response.runnerStatus=runner.Abort(HttpContext.TraceIdentifier).ToString();                 return response;             }         }         return StatusCode(StatusCodes.Status410Gone);     }

В примере производится формирование передача следующей странице Razor Pages внешнего идентификатора исполнителя, с которым эта страница должна работать дальше. Идентификатор передается в виде части пути в URL для следующей страницы — сегмента для переменной с именем key, описанного в директиве page страницы.

1.Внешний идентификатор исполнителя преобразуется в строковое значение с целью передачи его в URL следующей страницы(это делается методом PageModel.RedirectToPage()).

Pages\SequenceAdapterParams.cshtml.cs

        //This is part of the previous example from "Creating a new runner" section         public ActionResult OnPost()          {             //...                     //Create a new runner                     (var runner, int runner_number)= session.CreateSequenceRunner(sync_source, HttpContext);                     //Make an external identifier                     ExtRunnerKey key = (session, runner_number);                      //Pass the external identifier by a part of the redirection URL path.                     //A value of an external identifier will be serialized by the Razor Pages framework using the key.ToString() method call                     return RedirectToPage("SequenceShowResults", new { key });              //...         }

2.Значение внешнего идентификатора исполнителя из сегмента URL привязывается к входному параметру обработчика страницы с тем же именем. Привязка осуществляется с помощью класса привязки указанного в атрибуте [ModelBinder]. После получения внешнего идентификатора исполнителя обработчик проверяет, что исполнитель был создан в том же активном сеансе, в котором выполняется обработчик, и если это так — извлекает ссылку на исполнитель для дальнейшей работы с ним.

Pages\SequenceShowResults.cshtml

@page "{key}"  @model SapmleApplication.Pages.SequenceShowResultsModel <!-- ... -->

Pages\SequenceShowResults.cshtml.cs

    public class SequenceShowResultsModel : PageModel     {         //...         public async Task OnGetAsync([ModelBinder<ExtRunnerKeyMvcModelBinder>]ExtRunnerKey Key)         {             //...             IActiveSession active_session = HttpContext.GetActiveSession();             if(!active_session.IsAvailable) {                 //... Write a message about the situation             }             else {                 if(!Key.IsForSession(active_session)) {                     //... Write a message about the situation                 }                 else {                     //Obtain the runner                     var runner = active_session.GetSequenceRunner<SimSeqData>(Key.RunnerNumber, HttpContext);                     //...                 }             }         }         //...     }

3.Метод BindModelAsync класса привязки (он в нынешний состав библиотеки ActiveSession не входит, а реализован в самом примере) преобразует строку со значением параметра маршрутизации в экземпляр класса ExtRunnerKey — внешнего идентификатора исполнителя, используя метод ExtRunnerKey.TryParse.

ExtRunnerKeyMvcModelBinder.cs

    public class ExtRunnerKeyMvcModelBinder : IModelBinder     {         public Task BindModelAsync(ModelBindingContext Context)         {             String name = Context.ModelName;             String? key_string = Context.ValueProvider.GetValue(name).FirstOrDefault();             if(key_string != null) {                 ExtRunnerKey key;                 if(ExtRunnerKey.TryParse(key_string, out key)) {                     Context.ModelState.SetModelValue(name, key, key_string);                     Context.Result=ModelBindingResult.Success(key);                 }             }             return Task.CompletedTask;         }     }

Следующий пример показывает, как можно связать объект с активным сеансом и отслеживать завершение сеанса, чтобы выполнить очистку. Пример связывает объект RunnerRegistry (функциональность которого выходит за рамки примера) с активным сеансом, извлекает связанный объект и очищает его после того, как активный сеанс завершает очистку:

RunnerRegistry.cs

    public class RunnerRegistry: IDisposable     {         //...         public void Dispose()         {             //...         }      }

Sources\RunnerRegistryActiveSessionsExtensions.cs

    public static class RunnerRegistryActiveSessionsExtensions     {         public const string REGISTRY_NAME = "RunnerRegistry";          public static RunnerRegistry GetRegistry(this IActiveSession ActiveSession)         {             Object? cached_result;             RunnerRegistry? result = null;             //First just try to get the existing registry (fast path)             if(!ActiveSession.Properties.TryGetValue(REGISTRY_NAME, out cached_result)) { //Fast path isn't available                 lock(ActiveSession.Properties) { //Lock shareable resource - Properties dictionary                     result = new RunnerRegistry(); //Create new registry to add it to Properties                     if(ActiveSession.Properties.TryAdd(REGISTRY_NAME, result)) //Use "double check pattern" with second check within lock block                         //Addition was successful                         ActiveSession.CleanupCompletionTask.ContinueWith((_) => result.Dispose()); //Plan disposing the registry added after end of ActiveSession                     else {                         //Somebody added a registry already between checks                         cached_result = ActiveSession.Properties[REGISTRY_NAME]; //Get previously added registry                         result.Dispose();                         result=null; //Dispose and clear result                     }                 }             }             return result??(RunnerRegistry)cached_result!; //cached_result is not null here;         }         //...     }

Проблема возникает с теми сервисами, для которых при регистрации указано время существования, ограниченное областью действия (Scoped). В их число входит немалое количество часто используемых сервисов — например, представляющих подключения к базам данных или контексты баз данных Entity Framework. Стандартно в ASP.NET Core такой областью действия сервиса, ограничивающей его время жизни, является обработка одного запроса к веб-серверу. Такие сервисы исполнители использовать, очевидно, не должны, потому что, по самой их сути, часть кода исполнителей выполняется вне контекста обработки какого-либо запроса. Поэтому для активного сеанса создается своя область действия сервисов, существующая, пока существует активный сеанс.

Технически, для создания областей действия сервисов в .NET используются дочерние контейнеры сервисов: сервис с временем жизни области действия, полученный из дочернего контейнера для определенной области, имеет время жизни этой области. Для обычного обработчика запроса ASP.NET Core для области действия, связанной с запросом, ссылка на ее контейнер помещается в контекст запроса (свойство HttpContext.RequestServices). В библиотеке ActiveSession ссылка на контейнер сервисов области для активного сеанса хранится в свойстве SessionServices активного сеанса (IActiveSession.Service). Именно этот дочерний контейнер передается в метод Create фабрики исполнителя, создающий исполнитель.

Остается ещё одна проблема: внедрение зависимостей от сервисов с временем жизни ограниченной области, используемых в исполнителях, в обработчики запроса, реализуемые в рамках фреймворков высокого уровня (например — контроллеры и действия ASP.NET Core MVC или страницы Razor pages). Дело в том, что такие фреймворки получают объекты сервисов для области действия связанной с запросом, а про активный сеанс и ее область действия для сервисов им ничего неизвестно. В результате исполнитель может получить в качестве аргумента ссылку на сервис с неподходящей областью действия.

В библиотеке ActiveSession предусмотрены, в принципе, два варианта решения этой проблемы.

Первый вариант — подмена ссылки на дочерний контейнер сервисов в свойстве HttpContext.RequestServices контекста запроса на дочерний контейнер для области действия активного сеанса. Такая подмена настраивается через параметр UseSessionServicesAsRequestServices при конфигурировании библиотеки (в этой статье конфигурирование библиотеки ActiveSession не рассматривается). В этом случае все зависимости от сервисов с временем жизни ограниченной области разрешаются для области действия активного сеанса, что автоматически позволяет передавать любые из них исполнителям.
Достоинством этого варианта является отсутствие необходимости дополнительных модификаций уже написанного кода. Недостатками является, во-первых, чувствительность к порядку установки компонентов-обработчиков (middleware) в конвейер: может получиться нехорошо, если другой компонент-обработчик до подмены контейнера получит объект сервиса из контейнера, связанного с запросом, а обработчик конечной точки будет работать с совсем другим объектом, полученным из контейнера сервисов активного сеанса. Другой недостаток этого варианта — он, в общем случае, не тестировался для фреймворков во всем разнообразии их применений, а потому нет никакой гарантии, что подмена контейнера сервисов не вызовет ошибок во фреймворке. Потому что, например, для разных запросов будет возвращаться один и тот же экземпляр реализующего сервиса, тогда как логика работы фреймворка может быть рассчитана на то, что экземпляры для каждого запроса будут разными. А потому этот вариант не рекомендуется использовать без подробного тестирования приложения. В том числе — и нагрузочного, поскольку сервисы с областью действия активного сеанса могут жить дольше, а потому — требовать большего расхода памяти приложением. В общем, такой вариант в библиотеке ActiveSession реализуем, но не рекомендован.

Второй, более безопасный вариант — это внедрение зависимостей от сервисов, предназначенных для передачи исполнителям, через специальный сервис-адаптер IActiveSessionService<TService>. Этот сервис зарегистрирован, как имеющий время жизни ограниченной области (Scoped), и при внедрении зависимостей его реализация запрашивается, естественно из контейнера сервисов для обработки запроса. То есть, сам объект, реализующий IActiveSessionService, привязан к области обработки одного запроса к веб-серверу: он будет одним и тем же в этой области, и он будет очищен по завершении обработки этого веб-запроса. Но вот сервис, для которого IActiveSessionService служит адаптером, и ссылку на который содержит свойство IActiveSessionService.Service, запрашивается из контейнера сервисов активного сеанса (если она доступна), а потому по завершении обработки веб-запроса реализующий его экземпляр объекта очищен не будет, и получение этого же сервиса в другом запросе, входящем в тот же активный сеанс, вернет этот же экземпляр.
Достоинством этого варианта является его лучшая совместимость: изменение времени жизни сервисов касается только тех из них, для которых оно указано явно, никакие другие сервисы (в том числе, и вызываемые в других компонентах-обработчиках конвейера(middleware) это изменение не затронет. Потому рекомендуется именно этот вариант решения проблемы внедрения зависимостей для ограниченной области. Недостатки у этого варианта тоже есть. Во-первых, это — необходимость модификации существующего исходного кода (если таковой уже есть, конечно). А, во-вторых — несколько большие накладные расходы на поиск сервиса: для доступа к активного сеанса, в которой содержится ссылка на ее контейнер, требуется получить текущий контекст запроса (HttpContext), а в рамках работы контейнера сервисов это возможно только через сервис IHttpContextAccessor. Сервис же IHttpContextAccessor работает через доступ к контексту выполнения (переменной типа AsyncLocal), а это само по себе ведет к увеличению накладных расходов — не знаю, насколько больших во всех случаях, но, по крайней мере, достаточному, чтобы о нем, упоминалось в документации по .NET. Впрочем, полученный от IHttpAccessor контекст запроса кэшируется в экземпляре внутреннего сервиса библиотеки ActiveSession, имеющего время жизни области обработки запроса, а потому в течение обработки одного запроса обращаться к сервису IHttpContextAccessor приходится не более одного раза.

Pages\ExclusiveParams.cshtml.cs

    public class ExclusiveParamsModel : PageModel     {         // ...Other fields and properties         //A reference to the service used to obtain an exclusive service accessor         readonly ISessionServiceLock<IExclusiveService> _sessionServiceLock;         // ...         //Inject ISessionServiceLock service reference into the page model class constructor         public ExclusiveParamsModel(ISessionServiceLock<IExclusiveService> SessionServiceLock)         {             // ...Initialize other fields and properties             _sessionServiceLock=SessionServiceLock;         }          public async Task<ActionResult> OnPostAsync()          {             IActiveSession session = HttpContext.GetActiveSession();             // ...Perform some initialization and check if the session exists              //An exclusive service accessor. The service represented by it will not be really used by this example however.             ILockedSessionService<IExclusiveService>? accessor;              try {                 // Obtain an exclusive service accessor to lock access to the instance implementing IExclusiveService                 accessor =  await _sessionServiceLock.AcquireAsync(Timeout.InfiniteTimeSpan, HttpContext.RequestAborted);             }             catch(ObjectDisposedException) {                 //The active session was terminated, and it and all its associated objects are disposed.                 return RedirectToPage("SessionGone"); //Redirect to a page informing a user about that             }             if(accessor == null) return StatusCode(StatusCodes.Status500InternalServerError); //Infinite wait ended? It's impossible!              IAsyncEnumerable<SimSeqData> async_source; //Its initialized is skipped for brevity.             //Create a runner and pass the exclusive service accessor obtained earlier to be disposed after the runner completion and cleanup             (IRunner runner, int runner_number) = session.CreateSequenceRunner(async_source, HttpContext, accessor);              //... return RedirectResult to the result page containing an URL with the runner external identifier             //... see "Passing in URL an external runner identifier serialized into a string" example.                   }      }

Прежде чем перейти к описанию свойств и методов интерфейса исполнителя IRunner<TResult> (и его не зависящей от типа результата части IRunner) стоит рассмотреть несколько понятий, на которые опирается это описание.

Состояние исполнителя.

Состояние исполнителя состоит из статуса исполнителя, позиции исполнителя и, возможно, исключения, возникшего во время фонового выполнения исполнителя. Состояние исполнителя возвращается вместе с результатом методами получения результата исполнителя (см. соответствующий раздел ниже). Состояние исполнителя, возвращаемое вместе с результатом, берется в момент возврата результата. Текущее состояние исполнителя также доступно через свойства Status, Position и Exception интерфейса исполнителя.

Статус исполнителя, значение перечислимого типа RunnerStatus, описывает стадию жизненного цикла исполнителя. Существование исполнителя начинается с его начальной стадии, на которой фоновая операция еще не запущена. Значение статуса для этой стадии всегда NotStarted.

Когда начинается фоновое выполнение, исполнитель переходит на стадию выполнения. Существует два значения статуса, которые соответствуют стадии выполнения. Значение Stalled указывает, что результат для последней точки выполнения, достигнутой фоновой операцией, уже возвращен, но фоновая операция все еще выполняется. Значение Progressed указывает, что результат для последней точки выполнения, достигнутой фоновой операцией, еще не возвращен, при этом фоновая операция может быть как уже завершена, так и ещё выполняться. Чтобы проверить, соответствует ли значение статуса стадии выполнения, можно использовать метод расширения IsRunning() для класса RunnerStatus.

Исполнитель переходит в свою конечное состояние — на стадию завершения — после того, как его фоновая операция была завершена по любой причине и все результаты, полученные при фоновом выполнении, но ещё не возвращенные методами получения результата были возвращены. Значения статуса, соответствующие стадии завершения, указывают причину завершения исполнителя. Значение статуса Completed указывает, что фоновая операция была завершена естественным образом и ее окончательный результат был возвращен. Значение статуса Failed указывает, что фоновая операция была завершена из-за исключения, возникшего во время ее выполнения и последний полученный до возникновения исключения результат также был возвращен, при этом исключение становится частью состояния исполнителя. Значение статуса Aborted указывает, что выполнение исполнителя было прервано вызовом из приложения или самой библиотекой — из-за таймаута обращения к исполнителю или из-за завершения активного сеанса, к которому принадлежит исполнитель. В отличие от двух предыдущих случаев, прерывание выполнения исполнителя не только завершает фоновую операцию, но и отбрасывает все ее результаты, которые еще не были возвращены или уже приготовлены к немедленному возврату. Таким образом, прерывание заставляет исполнитель перейти на стадию завершения со статусом Aborted немедленно, а не после того, как будут возвращены все уже полученные фоновым процессом результаты, как в двух предыдущих случаях.

Состояние исполнителя, дошедшего до стадии завершения, больше измениться не может, а сам исполнитель по достижении этой стадии удаляется из хранилища. При этом исполнитель становится недоступным через интерфейс активного сеанса IActiveSession и подвергается очистке, если его класс подразумевает таковую (реализует интерфейс IDisposable и/или IAsyncDisposable). Чтобы проверить, соответствует ли значение статуса исполнителя стадии завершения, можно использовать метод расширения IsFinal() для класса RunnerStatus.

Позиция исполнителя — это номер точки выполнения, для которой были возвращены результаты фонового выполнения. Когда позиция передается вместе с возвращаемым результатом, она указывает точку выполнения, для которой возвращается результат. Свойство Position исполнителя содержит номер последней точки выполнения, для которой был возвращен результат. Обычно (а для любого стандартного исполнителя библиотеки ActiveSession — всегда) свойство Position — это еще и максимальный номер точки выполнения, для которой когда-либо возвращался результат. Позиция исполнителя изменяется только на стадии его выполнения. Для стандартных исполнителей библиотеки ActiveSession позиция исполнителя на начальной стадии всегда равна нулю. На стадии завершения у стандартных исполнителей позиция зависит от причины завершения. Если завершение исполнителя произошло из-за завершения фонового процесса — нормального (статус — Completed) или по ошибке (статус — Failed) — позиция завершенного исполнителя будет равна номеру последней достигнутой фоновым исполнителем точки выполнения: пока данные для этой точки выполнения не возвращены методами получения результата, работа исполнителя не завершается (но его выполнение можно прервать, и тогда он завершится сразу). Если же исполнитель был прерван (статус — Aborted) позиция его может быть любой: прерывание исполнителя прерывает выполнение и его фонового процесса, и относящихся к его интерфейсной части методов получения данных.

Исключение как часть состояния исполнителя устанавливается только тогда, когда исполнитель переходит в стадию завершения со статусом Failed. В этом случае эта часть состояния содержит исключение, которое произошло во время фонового выполнения. Во всех других случаях исключение равно null. Исключение как часть состояния исполнителя доступна через свойство Exception его интерфейса.

Если вам кажется, что понятия «результат» и «точка выполнения» выглядят несколько абстрактно, то вам не кажется: так оно и есть. Результат выполнения — это действительно абстрактное понятие, точный смысл которого зависит от конкретного исполнителя. То же самое относится и к понятию «точка выполнения»: она и, в частности, номер, он же «позиция» — это тоже абстракция, смысл которой тоже определяется конкретным исполнителем. Но в процессе работы над конкретными стандартными исполнителями выяснились полезные на практике варианты реализации этих абстракций. Соглашения, описывающие эти варианты, изложены ниже, в описании исполнителей последовательностей и других стандартных исполнителей библиотеки ActiveSession, как наиболее полезные на практике. А рассуждения об абстрактных понятиях убраны сюда, в скрытый текст, чтобы не смущать читателей при первом (и, возможно, единственном) прочтении этого текста.

Но если вы придумали какую-то другую полезную вам реализацию этих абстракций — используйте смело: библиотека ActiveSession будет работать и с этой реализацией, потому что инфраструктура библиотеки от конкретного наполнения этих абстракций не зависит. В такой независимости как раз и состоит польза абстракций. Но усложнять жизнь читателя, которому нужны конкретные решения его задачи, разговорами про абстрактыне абстракции я считаю неправильным. А потому рассказ про абстракции находится здесь, в скрытом тексте.

Исполнители последовательностей.

Важным частным случаем исполнителей являются те, которые получают или производят в фоновом режиме последовательность объектов одного и того же типа (далее эти объекты будут называться записями) и возвращают в качестве результата эту последовательность записей по частям, в порядке их получения и без пропусков или повторений. В дальнейшем такие исполнители будут называться исполнителями последовательностей. У исполнителей последовательностей есть ряд общих черт, которые отличают их от других исполнителей.

Во-первых, методы получения результата одного исполнителя последовательности должны выполняться последовательно, по одному за раз. Нарушение этого правила приводит к возникновению исключения InvalidOperationException. Это правило применимо и к асинхронным методам получения результатов: пока один такой метод ожидает своего завершения, никакие другие методы получения результатов исполнителя последовательности, как синхронные, так и асинхронные, не могут быть вызваны. Ограничение, налагаемое этим правилом, гарантирует, что фоновая последовательность будет возвращена в том же порядке, без пропусков и дублей.

Во-вторых, результат исполнителя последовательности имеет обобщенный тип IEnumerable<TItem>, где TItem — тип записи. Результат, возвращаемый методами получения результатов последовательного исполнителя, является частью исходной фоновой последовательности, содержащей записи, которые еще не были возвращены — от последней точки выполнения, для которой был возвращен результат, и до точки выполнения, указанной параметрами метода (см. обсуждение параметров методов получения результатов ниже).

В-третьих, номер точки выполнения для исполнителя последовательности — это количество записей в исходной фоновой последовательности, полученных или возвращенных на данный момент, в зависимости от контекста. То есть, при получении информации о фоновом процессе исполнителя последовательности этот номер равен количеству записей, созданных или полученных из другого источника фоновым процессом, а в качестве позиции исполнителя последовательности — возвращаемой вместе с результатом или доступной через свойство Position исполнителя — общее количество записей, возвращенных в качестве результата на момент возврата или вообще.

В-четвертых, каждый метод получения результатов должен начинать получение своего результата с текущей позиции исполнителя (см. описание параметров методов получения результатов ниже).

… параметры Advance и StartPosition определяют диапазон номеров точек выполнения, для которого должен быть возвращен результат. А именно, параметр StartPosition указывает начало этого диапазона, а Advance — его размер, то есть, на какую величину номер конечной точки выполнения может превосходить номер начальной точки.
Но это — именно формальное определение.

Какой именно смысл эти параметры имеют для конкретных исполнителей, и какие на них наложены ограничения, определяется самим исполнителем, его типом.

Значение по умолчанию параметра Advance для методов получения результата отличается. Для GetAvailable оно равно Int32.MaxValue, то есть по умолчанию этот метод возвращает результат для последней достигнутой фоновым процессом точки выполнения (номер которой, очевидно, меньше Int32.MaxValue). То есть, для исполнителей последовательностей записей, результатом будут все уже выбранные в фоне, но ещё не возвращенные ранее записи.

Для GetRequiredAsync значение по умолчанию параметра Advance равно константе IRunner.DEFAULT_ADVANCE (=0). Для исполнителей последовательностей вместо него подставляется величина значения по умолчанию, указанная при создании исполнителя (поле DefaultAdvance объекта параметров исполнителя). Если при создании исполнителя значение этого поля не было задано, то подставляется значение, заданное в конфигурации библиотеки ActiveSession (которое, в свою очередь, по умолчанию равно 20).

Параметр StartPosition по умолчанию имеет значение IRunner.CURRENT_POSITION (-1), что означает, что в качестве начальной используется текущая позиция исполнителя на момент вызова метода (значение его свойства Position).

1. Идентификатор исполнителя Id. Тип свойства — это структура RunnerId. Она содержит два поля: String? ID — идентификатор активного сеанса, в которой работает исполнитель и Int32 RunnerNumber — номер исполнителя. Это свойство служит, в основном, для целей трассировки: его значение, если оно указано, добавляется кодом исполнителя и инфраструктуры как параметр каждой отправляемой в журнал (log) записи, связанной с этим исполнителем.
2. Дополнительные данные: Object? ExtraData — произвольные дополнительные данные, сопоставленные с исполнителем. Ответственность за очистку этих дополнительных данных, если она необходима, лежит целиком на приложении. Для выполнения своевременной очистки приложение может связать функцию обратного вызова с маркером завершения либо дождаться завершения задачи очистки исполнителя, ссылку на которую можно получить методом CleanupCompletionTask интерфейса активного сеанса IActiveSession.

Из примера работы с исполнителями-адаптерами последовательностей: получение начальной порции данных.

Pages\SequenceShowResults.cshtml.cs

    public class SequenceShowResultsModel : PageModel     {         //...skip irrelevant code         internal List<SimSeqData> _results=new List<SimSeqData>();         internal RunnerStatus _status;         internal Int32 _position;         internal Exception? _exception;         internal String RUNNER_COMPLETED = "The runner is completed.";         //...skip irrelevant code         internal Int32 _bkgProgress;         internal Boolean _bkgIsCompleted;         //...skip irrelevant code         public String StartupStatusMessage { get; private set; } = "";          public async Task OnGetAsync([ModelBinder<ExtRunnerKeyMvcModelBinder>]ExtRunnerKey Key)         {             //...skip irrelevant code and adjust indentation             var runner = active_session.GetSequenceRunner<SimSeqData>(Key.RunnerNumber, HttpContext);             //...skip irrelevant code and adjust indentation             IEnumerable<SimSeqData> res_enum;             (res_enum,_status,_position,_exception) =                  await runner.GetRequiredAsync(_params?.StartCount??IRunner.DEFAULT_ADVANCE, TraceIdentifier: HttpContext.TraceIdentifier);             _results = res_enum.ToList();             if(_status.IsFinal()) StartupStatusMessage=RUNNER_COMPLETED;             else {                 StartupStatusMessage="The runner is running in background.";             }             _bkgIsCompleted = runner.IsBackgroundExecutionCompleted;             _bkgProgress = runner.GetProgress().Progress;             //...skip irrelevant code and adjust indentation         }

Pages\SequenceShowResults.cshtml

@page "{key}"  @model SapmleApplication.Pages.SequenceShowResultsModel <!-- ... ---> <div style="display:inline-block; min-width:30%">     <h3 style="text-align:center">Example results.</h3>     <div>         <span style="margin-left: 10px; font-weight:600">Status:</span> <span id="runner_status">@Model._status</span>         <span style="margin-left: 10px; font-weight:600">#Records:</span> <span id="position">@Model._position</span>     </div>     <div>         <span style="margin-left: 10px; font-weight:600">Bkg. progress:</span> <span id="bkg_progress">@Model._bkgProgress</span>         <span style="margin-left: 10px; font-weight:600">Bkg. is completed:</span> <span id="bkg_completed">@Model._bkgIsCompleted</span>     </div>     <div class="records number">Number</div><div class="records name">Name</div><div class="records name">Data</div>     <table style="display:block;border-style:solid;border-width:thin;height:15em;overflow:auto">         <tbody id="results_table">             @for(int row = 0; row<Model._position; row++) {                 <tr>                     <td class="records number">@(Model._results[row].Number+1)</td>                     <td class="records name">@Model._results[row].Name</td>                     <td class="records data">@Model._results[row].Data</td>                 </tr>             }         </tbody>     </table>     <!-- ... ---> </div> <!-- ... --->

Из примера работы с исполнителями-адаптерами последовательностей: получение дополнительных данных.
APIControllers\SampleController.cs

    //public class GetAvailableRequest     //{     //    public ExtRunnerKey RunnerKey { get; set; }     //    public Int32? Advance { get; set; }     //}      //public class SampleSequenceResponse     //{     //    public Int32 status { get; init; } = StatusCodes.Status200OK;     //    public String? runnerStatus { get; set; }     //    public Int32 position { get; set; }     //    public Exception? exception { get; set; }     //    public IEnumerable<SimSeqData>? result { get; set; }     //    public Boolean isBackgroundExecutionCompleted { get; set; }     //    public Int32 backgroundProgress { get; set; }     //}      [Route("api")]     [ApiController]     public class SampleController : ControllerBase     {         [HttpPost("[action]")]         public ActionResult<SampleSequenceResponse> GetAvailable(GetAvailableRequest Request)         {             //...skip irrelevant code and adjust indentation             // IEnumerable<SimSeqData> runner; Initialized elsewhere             SampleSequenceResponse response = new SampleSequenceResponse();             response.backgroundProgress=runner.GetProgress().Progress;             response.isBackgroundExecutionCompleted=runner.IsBackgroundExecutionCompleted;             RunnerStatus runner_status;             (response.result, runner_status, response.position, response.exception) =                 runner.GetAvailable(Request.Advance??Int32.MaxValue, TraceIdentifier: HttpContext.TraceIdentifier);             response.runnerStatus=runner_status.ToString();             return response;             //...skip irrelevant code and adjust indentation         }         //...skip irrelevant code and adjust indentation     }

Из примеров работы с разными исполнителями: реакция на закрытие страницы в браузере.

APIControllers\SampleController.cs

    //public class AbortRequest     //{     //        public ExtRunnerKey RunnerKey { get; set; }     //}     //     //public class AbortResponse     //{     //    public Int32 status { get; init; } = StatusCodes.Status200OK;     //    public String? runnerStatus { get; set; }     //}      public ActionResult<AbortResponse> Abort(AbortRequest Request)     {         IActiveSession session = HttpContext.GetActiveSession();         if(session.IsAvailable && Request.RunnerKey.IsForSession(session)) {             IRunner runner = session.GetNonTypedRunner(Request.RunnerKey.RunnerNumber, HttpContext);             if(runner!=null) {                 AbortResponse response = new AbortResponse();                 response.runnerStatus=runner.Abort(HttpContext.TraceIdentifier).ToString();                 return response;             }         }         return StatusCode(StatusCodes.Status410Gone);     }

Из примера работы с исполнителями-адаптерами последовательностей: переход на страницу отображения результатов.

Pages\SequenceAdapterParams.cshtml.cs

        public ActionResult OnPost()          {             //...skip irrelevant code and adjust indentation             SequenceParams seq_params=MakeSequenceParams();             //...skip irrelevant code and adjust indentation             IEnumerable<SimSeqData> sync_source = new SyncDelayedEnumerble<SimSeqData>(seq_params.Stages, new SimSeqDataProducer().Sample);             (IRunner runner, int runner_number)= session.CreateSequenceRunner(sync_source, HttpContext);             //...skip irrelevant code and adjust indentation             ExtRunnerKey key = (session, runner_number);             runner.ExtraData=seq_params;             return RedirectToPage("SequenceShowResults", new { key });             //...skip irrelevant code and adjust indentation         }

Pages\SequenceShowResults.cshtml.cs

    public class SequenceShowResultsModel : PageModel     {         internal SequenceParams? _params;         //...skip irrelevant code         public async Task OnGetAsync([ModelBinder<ExtRunnerKeyMvcModelBinder>]ExtRunnerKey Key)         {             //...skip irrelevant code and adjust indentation             var runner = active_session.GetSequenceRunner<SimSeqData>(Key.RunnerNumber, HttpContext);             //...skip irrelevant code and adjust indentation             _params = runner.ExtraData as SequenceParams;             //...skip irrelevant code and adjust indentation         }

Pages\SequenceShowResults.cshtml

@page "{key}"  @model SapmleApplication.Pages.SequenceShowResultsModel <!-- ... ---> <div style="display:inline-block; min-width:30%">     <h3>Example parameters.</h3>     <div style ="background-color: lightgray;">         <div style="margin-bottom:0.2em"><b>Mode</b>:@(Model._params.Mode)</div>         <div style="margin-bottom:0.2em"><b>Max #records at start</b>:@(Model._params.StartCount)</div>         <div style="margin-bottom:0.2em"><b>Poll interval</b>:@(Model._params.PollInterval.TotalSeconds)s</div>         <div style="margin-bottom:0.2em"><b>Max #records per poll</b>:             @(Model._params.PollMaxCount.HasValue ? Model._params.PollMaxCount.Value.ToString():"not set")</div>         <div>             <div><b>Stages</b>:</div>             <table style="margin-left:5px">                 <tr><th>#</th><th>Iterations:</th><th>Delay:</th><th>Ends at:</th></tr>                 @if (Model._params.Stages != null) {                     int num = 0;                     int end_pos = 0;                     @foreach (SimStage stage in Model._params.Stages) {                         <tr><td style="min-width:2em">@(num++)</td><td>@stage.Count</td><td>@(Model.SmartInterval(stage.Delay))</td><td>@(end_pos+=stage.Count)</td></tr>                     }                 }             </table>         </div>     </div> </div> <!-- ... --->

Из примера исполнителя сеансового процесса. Отмена маркера завершения исполнителя, полученного фоновой задачей при ее запуске, вызывает отмену этой фоновой задачи.

Sources\RunnerRegistryObserver.cs

        public async Task Observe(Action<Int32, Int32?> Callback, CancellationToken CompletionToken)         {             TaskCompletionSource<Int32> wait_source;             TaskCompletionSource<Int32> completion_source =new TaskCompletionSource<Int32>();             Callback.Invoke(_registry.Count, null);             using(                 CancellationTokenRegistration completion_registration= CompletionToken.Register(                     ()=>completion_source.SetCanceled(CompletionToken))             ) {                 while(true) {                     wait_source = Volatile.Read(in _currentWaitSource);                     Int32 count = (await Task.WhenAny(wait_source.Task,completion_source.Task)).Result;                     //One can come here only if wait_source.Task is ran to completion,                     // because completion_source.Task never runs to completion, it can be completed via an OperationCanceledException only.                     Callback(count, null);                 }             }             //One never come here to run this task to completion, as a loop above can be be terminated by a OperationCanceledException             //This exception will be intercepted by calling code as an expected one.         }      }

Реализация метод расширения CreateRunnerWithExclusiveService для интерфейса IActiveSession (из исходного кода библиотеки ActiveSession).

        public static KeyedRunner<TResult> CreateRunnerWithExclusiveService<TRequest,TResult> (             this IActiveSession Session,             TRequest Request,             HttpContext Context,             IDisposable ExclusiveServiceAccessor)         {             return InternalCreateRunnerExcl<TRequest,TResult>(Session, Request, Context, ExclusiveServiceAccessor);         }          internal static KeyedRunner<TResult> InternalCreateRunnerExcl<TRequest, TResult>(             IActiveSession Session,             TRequest Request,             HttpContext Context,             IDisposable? ExclusiveServiceAccessor)         {             KeyedRunner<TResult> result = Session.CreateRunner<TRequest, TResult>(Request, Context);             if(ExclusiveServiceAccessor!=null) {                 (Session.TrackRunnerCleanup(result.RunnerNumber)??Task.CompletedTask)                     .ContinueWith((_) => ExclusiveServiceAccessor.Dispose(),TaskContinuationOptions.ExecuteSynchronously);             }             return result;         }

Упомянутые структуры с дополнительными параметрами имеют обобщенные типы EnumAdapterParams<TItem> и AsyncEnumAdapterParams<TItem> соответственно. Эти структуры для обоих классов адаптеров очень похожи: они содержат, кроме поля Source с перечисляемой последовательностью, тип которой отличается, набор одинаковых полей. Некоторые из этих полей перечислены ниже:

• Поле int? DefaultAdvance — содержит значение по умолчанию для параметра Advance метода GetRequiredAsync (см. описание этого параметра в главе про исполнители).
• Поле int? EnumAheadLimit — содержит предельное число выбранных в фоне но ещё не возвращенных записей, по достижении этого предела дальнейшая выборка блокируется, пока имеющиеся записи не будут переданы как часть результата метода, возвращающего результаты, по умолчанию это значение задается через конфигурирование библиотеки (в статье это не рассматривается).
• Поле bool StartInCоnstructor — указывает, начнется ли перечисление сразу или при первом вызове метода GetRequiredAsync (последнее — вариант по умолчанию).
• Поле bool PassSourceOnership — указывает, отвечает ли объект исполнителя при своей очистке (вызове его методов Dispose или DisposeAsync) за очистку объекта, реализующего входную последовательность, если тот реализует интерфейсы для очистки: IAsyncDisposable или IDisposable.

Для этого первым параметром в этот метод должен быть одним из входных параметров, описанных выше, первый параметр тип должен совпадать с типом этого параметра, а второй параметр тип (тип результата) должен быть IEnumerable<TItem>

Структура с параметрами имеет тип TimeSeriesparams<TResult>. Эта структура содержит упомянутые выше аргументы в полях, соответственно, Gauge, Interval и Count (если третий аргумент отсутствует, это поле устанавливается в null), а также — ряд дополнительных полей, аналогичных одноименным полям рассмотренных ранее структур (Async)EnumAdapterParams. Некоторые из этих полей перечислены ниже:

• Поле int? DefaultAdvance содержит значение по умолчанию для параметра Advance метода GetRequiredAsync (см. описание этого параметра в главе про исполнители).
• Поле int? EnumAheadLimit содержит предельное число выбранных в фоне но ещё не возвращенных записей, по достижении этого предела дальнейшая выборка блокируется, пока имеющиеся записи не будут переданы как часть результата метода, возвращающего результаты, по умолчанию это значение задается через конфигурирование.
• Поле bool StartInCоnstructor указывает, начнется ли перечисление сразу или при первом вызове метода GetRequiredAsync (последнее — вариант по умолчанию).

Для этого первым параметром метода CreateRunner должна быть либо описанная выше структура с параметрами, либо двойка или тройка из описанных выше аргументов.
Тип первый параметра-тип при этом должен совпадать с типом переданного параметра, а второй параметр-тип должен быть IEnumerable<(DateTime, TResult)>

Выполняющиеся на момент завершения исполнителя вызовы GetRequiredAsync возвращают окончательный результат и состояние, соответствующее наступившей стадии завершения исполнителя: с соответствующим причине завершения статусом, позицией, равной номеру последней достигнутой точке выполнения, и исключением, если завершение вызвано исключением. Кроме того, оценка номера завершающей точки выполнения, возвращаемая методом GetProgress, становится при завершении фонового процесса равной номеру последней фактически достигнутой точки выполнения.