Skip to main content

SetupTask

zng_ext_setup::task

Trait SetupTask 

Source 
pub trait SetupTask: Sized {
    type InstallConfig: Any + Send;
    type PrepareInstall: ConfigValue;
    type Install: ConfigValue;

    // Required methods
    fn task_type_id() -> TaskTypeId;
    fn prepare_install(
        args: PrepareInstallArgs<Self>,
    ) -> impl Future<Output = Result<Self::PrepareInstall, SetupTaskError>> + Send + 'static;
    fn install(
        args: InstallArgs<Self>,
    ) -> impl Future<Output = Result<Self::Install, InstallTaskError<Self::Install>>> + Send + 'static;
    fn cancel_install(
        args: CancelInstallArgs<Self>,
    ) -> impl Future<Output = Result<(), SetupTaskError>> + Send + 'static;
    fn validate_uninstall(
        args: ValidateUninstallArgs<Self>,
    ) -> impl Future<Output = Result<Self::Install, SetupTaskError>> + Send + 'static;
    fn uninstall(
        args: UninstallArgs<Self>,
    ) -> impl Future<Output = Result<(), SetupTaskError>> + Send + 'static;
}
Expand description

Represents an install and uninstall task implementation.

Setup tasks runs in steps, steps do not necessarily run on the same process, communication between steps is done using serialized data. The steps are implemented as associated functions, not methods, the task type is not instantiated.

Each step runs for all tasks on the setup list, before moving to the next step.

§Install Steps

1 - If the user did not cancel, SetupTask::prepare_install is called. 2.a - If did not cancel, SetupTask::install is called, the user cannot cancel once this starts. 2.b - If did cancel, SetupTask::cancel_install is called.

Note that steps 1 and 2 might not run on the same process. A case where this happens is a self-updater that starts preparing to install the update while it is still running.

§Uninstall Steps

1 - SetupTask::Install data is deserialized from the install log. 2 - SetupTask::validate_uninstall is called. 3 - If did not cancel, SetupTask::uninstall is called.

§Register

Custom setup task types must be registered with SETUP.register_task_type otherwise install and uninstall will fail with SetupTaskError::UnknownType.

§Async

The async functions must not block on IO, offload all blocking IO to zng_task::wait. CPU heavy operations are ok, the tasks run in worker threads.

Required Associated Types§

Source

type InstallConfig: Any + Send

Install config type.

Source

type PrepareInstall: ConfigValue

Prepared install data type.

Source

type Install: ConfigValue

Installed data type.

Required Methods§

Source

fn task_type_id() -> TaskTypeId

Unique ID for the task type.

Source

fn prepare_install( args: PrepareInstallArgs<Self>, ) -> impl Future<Output = Result<Self::PrepareInstall, SetupTaskError>> + Send + 'static

Run all expensive install operations that can run without affecting the system or previous installs.

This step must not cause any change that affects existing install, even if reversible, it must only run all potentially expensive tasks in such a way that the final commit can happen quickly.

The user may cancel the install at any time, if possible monitor the cancel var and return early on cancel. Implement cancellation cleanup on cancel_install.

Source

fn install( args: InstallArgs<Self>, ) -> impl Future<Output = Result<Self::Install, InstallTaskError<Self::Install>>> + Send + 'static

Commit prepared install changes.

The user cannot cancel installation when this step is running. Progress indicators will only show indeterminate with the expectation this step will finish quickly.

Install must not fail at the first error encountered, a best attempt to apply all install steps must be made, errors can be aggregated on the InstallTaskError::error. The InstallTaskError::clean_data must include uninstall instructions for all successful steps, best attempt of partial steps and any data from the previous version that was not replaced in case it is installing an update.

Source

fn cancel_install( args: CancelInstallArgs<Self>, ) -> impl Future<Output = Result<(), SetupTaskError>> + Send + 'static

Cancel prepared install changes.

This is called if the user requested cancel during or after prepare_install and before install.

This step must find and cleanup all prepared changes, such as temporary files. The cancel logic must be resilient to partial changes as prepare_install might return early due to user cancel or an error.

Source

fn validate_uninstall( args: ValidateUninstallArgs<Self>, ) -> impl Future<Output = Result<Self::Install, SetupTaskError>> + Send + 'static

Validate the install state for uninstall.

This step must not make any changes to the file system, not even creating temp files. This step allows tasks to validate the install state before uninstall makes irreversible changes.

This step is not expected to take long, but if it does check the cancel flag to avoid unnecessary work. If the uninstall is canceled when another task is preparing after this one the returned data is just dropped.

This step returns a validation error or the corrected install data.

Source

fn uninstall( args: UninstallArgs<Self>, ) -> impl Future<Output = Result<(), SetupTaskError>> + Send + 'static

Uninstall.

The user cannot cancel uninstallation when this step is running.

Uninstall is idempotent, it must not fail in case a step is already completed, for example, if the task must remove a file and it is not found, that is not an error. Task runners can retry partially run uninstall with an install data clone.

Uninstall must not fail at the first error encountered, a best attempt to apply all uninstall steps must be made, errors can be aggregated on the SetupTaskError.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§