Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: Background tasks #4352

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Commits on Sep 18, 2024

  1. feat(server): Asynchronous server-side background task execution

    This patch implements the whole support ecosystem for server-side
    background tasks, in order to help lessen the load (and blocking) of API
    handlers in the web-server for long-running operations.
    
    A **Task** is represented by two things in strict co-existence: a
    lightweight, `pickle`-able implementation in the server's code (a
    subclass of `AbstractTask`) and a corresponding `BackgroundTask`
    database entity, which resides in the "configuration" database (shared
    across all products).
    A Task is created by API request handlers and then the user is
    instructed to retain the `TaskToken`: the task's unique identifier.
    Following, the server will dispatch execution of the object into a
    background worker process, and keep status synchronisation via the
    database.
    Even in a service cluster deployment, load balancing will not interfere
    with users' ability to query a task's status.
    
    While normal users can only query the status of a single task (which is
    usually automatically done by client code, and not the user manually
    executing something); product administrators, and especially server
    administrators have the ability to query an arbitrary set of tasks using
    the potential filters, with a dedicated API function (`getTasks()`) for
    this purpose.
    
    Tasks can be cancelled only by `SUPERUSER`s, at which point a special
    binary flag is set in the status record.
    However, to prevent complicating inter-process communication,
    cancellation is supposed to be implemented by `AbstractTask` subclasses
    in a co-operative way.
    The execution of tasks in a process and a `Task`'s ability to
    "communicate" with its execution environment is achieved through the new
    `TaskManager` instance, which is created for every process of a server's
    deployment.
    
    Unfortunately, tasks can die gracelessly if the server is terminated
    (either internally, or even externally).
    For this reason, the `DROPPED` status will indicate that the server has
    terminated prior to, or during a task's execution, and it was unable to
    produce results.
    The server was refactored significantly around the handling of subprocesses
    in order to support various server shutdown scenarios.
    
    Servers will start `background_worker_processes` number of task handling
    subprocesses, which are distinct from the already existing "API
    handling" subprocesses.
    By default, if unconfigured, `background_worker_processes` is equal to
    `worker_processes` (the number of API processes to spawn), which is
    equal to `$(nproc)` (CPU count in the system).
    
    This patch includes a `TestingDummyTask` demonstrative subclass of
    `AbstractTask` which counts up to an input number of seconds, and each
    second it gracefully checks whether it is being killed.
    The corresponding testing API endpoint, `createDummyTask()` can specify
    whether the task should simulate a failing status.
    This endpoint can only be used from, but is used extensively, the unit
    testing of the project.
    
    This patch does not include "nice" or "ergonomic" facilities for admins
    to manage the tasks, and so far, only the server-side of the
    corresponding API calls are supported.
    whisperity committed Sep 18, 2024
    Configuration menu
    Copy the full SHA
    a75244f View commit details
    Browse the repository at this point in the history

Commits on Sep 20, 2024

  1. doc: Background tasks

    whisperity committed Sep 20, 2024
    Configuration menu
    Copy the full SHA
    715121b View commit details
    Browse the repository at this point in the history