Skip to content

feat: introduce a unified background task center #21

Description

@AshGreyG

inspired by #20 (comment)

Problem

Long-running desktop work is currently owned by individual components. The RCSB download Form now uses a dedicated worker thread as a safe short-term fix, but task lifecycle, progress, cancellation, errors, and completion notifications are still local to the Form.

As more background work is added—project-tree loading, file scanning, structure parsing, downloads, and future bioinformatics workflows—this can lead to duplicated task management, inconsistent cancellation behavior, and no global way to inspect or notify users about running work.

Proposal

Introduce a desktop-level BackgroundTaskCenter owned by ChitinApp.

The task center should provide:

  • A shared asynchronous execution boundary, preferably a reusable Tokio runtime.
  • Stable task identifiers and a registry of active/completed tasks.
  • Task states such as queued, running, completed, failed, and cancelled.
  • Progress events with task-specific metadata.
  • Cancellation handles.
  • Duplicate-work protection where tasks target the same file or resource.
  • Completion and failure events that can later feed Toast notifications and a global task execution center.
  • Task lifetime independent of modal Form visibility.

The RCSB Form, CLI integration points, and future desktop workflows should submit domain tasks rather than creating their own runtime or worker lifecycle.

A possible high-level model is:

ChitinApp
└── BackgroundTaskCenter
    ├── async runtime
    ├── task registry
    ├── cancellation handles
    ├── progress events
    └── completion events

RCSB Form / other UI
└── submit task
    └── BackgroundTaskCenter

Product Area

Developer tooling

Acceptance Criteria

  • A desktop-owned task center can start a long-running async task without blocking GPUI's background executor.
  • Tasks have stable IDs and observable lifecycle state.
  • A task can continue after its originating Form or panel is closed.
  • Callers can subscribe to progress, completion, failure, and cancellation events.
  • Callers can request cancellation and receive a deterministic terminal state.
  • RCSB batch downloads use the task center instead of creating an ad-hoc runtime/thread per submission.
  • Existing Form behavior remains available: per-file progress animation, batch position, validation errors, and input locking while active.
  • Duplicate downloads to the same destination are rejected or coalesced according to an explicit policy.
  • Toast notifications and a global task list can be added without coupling those features to individual task implementations.
  • Tests cover task lifecycle transitions, cancellation, completion, failure propagation, and concurrent submissions.

Alternatives Considered

  • Keep one dedicated OS thread and Tokio runtime per download. This is the current safety fix, but it does not provide shared lifecycle management or a foundation for a task center.
  • Run downloads directly on the GPUI background executor with block_on. This can occupy an executor worker for the entire batch and delay unrelated work.
  • Implement separate task managers in each component. This duplicates cancellation, progress, and error handling and makes global notifications difficult.

Phased Delivery

  1. Define TaskId, task state, event, and cancellation interfaces.
  2. Add an application-owned execution boundary and task registry.
  3. Migrate RCSB downloads from the dedicated-thread workaround.
  4. Add task-center integration for project-tree loading and file scanning.
  5. Connect Toast notifications and the global task execution center.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions