KVHeavyTaskBaseDataProvider

open class KVHeavyTaskBaseDataProvider<K, Element, CustomEvent> where K : Hashable

Base class for heavy task data providers that defines the foundation for task execution.

This abstract base class provides the essential components that every heavy task data provider needs: a unique key identifier, event publishing capabilities, and result delivery mechanisms. It serves as the foundation for implementing concrete data providers that perform specific heavy operations.

Key Responsibilities

  • Task Identification: Maintains unique key for task tracking and cache coordination
  • Event Broadcasting: Provides mechanism for real-time progress and status updates
  • Result Delivery: Handles final result publishing with success/failure states
  • Type Safety: Enforces generic type constraints for keys, elements, and events

Generic Parameters

  • K: Key type (must be Hashable) used for task identification and caching
  • Element: Result type returned upon successful task completion
  • CustomEvent: Event type for progress updates and status notifications

Usage Pattern

Concrete implementations should inherit from this class and implement the KVHeavyTaskDataProviderInterface protocol to provide actual task execution logic.

  • Callback type for publishing custom events during task execution.

    This closure is invoked to broadcast real-time updates such as:

    • Progress percentages and completion estimates
    • Status changes (starting, processing, pausing)
    • Custom metrics (throughput, error counts, quality metrics)
    • User-defined events specific to the task domain

    Events are published asynchronously to avoid blocking task execution.

    Declaration

    Swift

    public typealias CustomEventPublisher = @Sendable (CustomEvent) -> Void

  • Callback type for publishing the final task result.

    This closure is called exactly once per task execution to deliver:

    • Success case: Contains the computed result or nil for valid null results
    • Failure case: Contains detailed error information for debugging and recovery

    The callback is thread-safe and handles proper cleanup after result delivery.

    Declaration

    Swift

    public typealias ResultPublisher = @Sendable (Result<Element?, Error>) -> Void
  • key

    The unique identifier for this task instance.

    This key serves multiple purposes:

    • Task identification: Uniquely identifies this task across the system
    • Cache coordination: Used as cache key for result storage and retrieval
    • Deduplication: Prevents duplicate tasks from running simultaneously
    • Progress tracking: Associates events and callbacks with specific tasks

    Declaration

    Swift

    public internal(set) var key: K { get }

  • Publisher for broadcasting custom events during task execution.

    Use this callback to send real-time updates to observers. Events are delivered asynchronously on a global queue to prevent blocking the main task execution. Multiple observers can be registered for the same task key.

    Declaration

    Swift

    public internal(set) var customEventPublisher: CustomEventPublisher { get }

  • Publisher for delivering the final task result.

    Critical: This callback must be called exactly once per task execution. Calling it multiple times or not calling it will result in undefined behavior, memory leaks, or hanging operations. The manager relies on this callback for proper task lifecycle management and resource cleanup.

    Declaration

    Swift

    public internal(set) var resultPublisher: ResultPublisher { get }

  • Initializes a new heavy task data provider instance.

    This initializer sets up the essential communication channels between the data provider and the task manager. The provided callbacks are used for the entire lifecycle of the task.

    Note

    Both publishers are thread-safe and can be called from any queue.

    Warning

    The resultPublisher must be called exactly once per task execution.

    Declaration

    Swift

    public required init(
    key: K,
    customEventPublisher: @escaping CustomEventPublisher,
    resultPublisher: @escaping ResultPublisher
)

    Parameters

    key

    Unique identifier for this task (used for caching and deduplication)
    customEventPublisher

    Callback for sending progress updates and custom events
    resultPublisher

    Callback for delivering the final result (success or failure)