Skip to content

Proposal: Progress Events #92

@chuckries

Description

@chuckries

We propose that adapters can send progress events to a fronted, in order to display progress related UI to a user in the case of long running tasks on the adapter side. Specific examples of long running tasks that an adapter may want to report progress for include symbol loading and expression evaluation.

Progress events may be generic (unrelated to a specific request) or specific (related directly to a request). This allows frontends to organize incoming progress events and directly show progress UI or defer progress information to API related to an original request.

  • An example of a generic progress event is automatic symbol loading progress, as this can happen any time a target process is running
  • An example of a specific progress event is loading symbols due to a LoadSymbols request, as this action is taken as a direct cause of a request.

Progress events are grouped using a unique id. This allows adapters to report progress for a long running task and frontends to group progress events together.

Progress events can be cancellable and are cancelled by extending the existing CancelRequest.

/** Event message for 'progress' event type
 *      The event indicates that a long running task has progress to report that can be displayed to the user.
 *      Multiple progress events with the same id represent a single logical progrses operation that can be updated.
 *      Sequence of events is as follows (for a given id):
 *      - adapter sends 1 progress event of category 'new'
 *      - adapter sends 0 or more progress events of category 'update'
 *      - adapter sends 1 progress event of category complete
 *      After this the adapter cannot send any more progress events with the same id
 * 
 *      Progress events may be generic (not related to a specific request) or be specific to a request id 
 * 
 *      Progress events may be cancellable. To cancel an operation that is reporting progress, a Cancel request is sent specifying the progressId to cancel.
 */
export interface ProgressEvent extends Event {
    body: {
        /**
         * The unique id for this progress operation. 
         */
        progressId: number;

        /** The request id that this progress event is related to, if any */
        requestId?: number;

        /** The progress category.
         *      Values: 'new', 'update', 'complete'
         */
        category: string;

        /** If cancellable is true, the task reporting progress may be canceled with a CancelRequest. If not present, assumed false */
        cancellable?: boolean;

        /** If 'category' is 'complete', this field may be present to report whether the completed progress task was cancelled. If not present, assumed false */
        cancelled?: boolean;

        /** A description of the progress event to display to the user; used to explain the long running task.  
         *      This field should be present when category is 'new' or 'update'
        */
        description?: string;

        /** The current step of the progress task, 0 indexed. This field combined with 'totalSteps' can be used to report a percentage progress for the long running task.
         *      If both 'currentStep' and 'totalSteps' are present and totalSteps is not 0, these fields represent a percentage progress where percent is 'currentStep' / 'totalSteps'
         *      If both 'currentStep' and 'totalSteps' are present and are 0, the progress is 'indeterminate', i.e. an indeterminate progress bar may be shown
         *      If either or both 'currentStep and 'totalSteps' are not present, their is no numeric progress to report and only the 'description' should be used.
         */
        currentStep?: number;

        /** The total number of steps this long running task will require. This field combined with 'currentStep' can be used to report a percentage progress for the long running task. 
         * 
        */
        totalSteps?: number;
    }
}

export interface CancelRequest extends Request {
    ...

    /** The progressId of a cancellable ProgressEvent */
    progressId?: number;
}

CC: @andrewcrawley @gregg-miskelly

Metadata

Metadata

Assignees

Labels

feature-requestRequest for new features or functionality

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions