d-installer_phases.md

Phases and Progress

A service has an installation phase, and the installation phase has an status:

• Installation phases: probe, install

• Phase status: doing, done, error

• Progress: represents the progress of a phase in doing state

Installer Process

• The installer process is probing if any service is in probe phase with doing status.
• The installer process is probed if all services are in probe phase with done status.
• The installer process is installing if any service is in install phase with doing status.
• The installer process is installed if all services are in install phase with done status.
• The installer process is wrong in any phase is in error status.

D-Bus iface: org.opensuse.DInstaller.InstallationPhase1

Properties

• Phase -> unsigned 32-bit integer (r)

  Current installation phase (1 for probe and 2 for install).

• Status -> struct(string, array(struct(string, variant))) (r)

  Status of the phase (0 for error, 1 for doing and 2 for done). The second value is hash of data associated to the status. For example:

  • Messages -> array(string): a list of messages, typically used when when the status is 0.
  • Progress -> struct(unsigned 32-bit integer, unsigned 32-bit integer, string): progress information, containing total steps, current step and description. The progress information is usually used when the status is 1. A signal is emitted every time the progress is updated.

Backend Classes

phase_manager = InstallationPhase::Manager.new

phase_manager.on_phase_change {}
phase_manager.on_status_change {}
phase_manager.on_progress_change {}
phase_manager.on_progress_finish {}

phase_manager.phase = InstallationPhase::Startup.new # calls on_phase_change callbacks and adds
                                                     # on_status_change callbacks to the phase.
phase_manager.progress = Progress.new(3)             # adds on_progress_change and on_progress_finish
                                                     # callbacks to the progress. It also adds another
                                                     # on_finish_callback to change the phase status
                                                     # to done.
phase_manager.phase.status                           #=> InstallationPhase::Status::Doing

progress = phase_manager.progress
progress.step("Doing step 1") { step1 }              # calls on_progress_change
progress.step("Doing step 2") { step2 }              # calls on_progress_change
progress.step("Doing step 3") { step3 }              # calls on_progress_change and on_progress_finish

phase_manager.phase.status                           # InstallationPhase::Status::Done
phase_manager.progress.finish?                       #=> true

phase_manager.phase = InstallationPhase::Install.new
phase_manager.phase.status                           #=> InstallationPhase::Status::Doing
phase_manager.progress                               #=> nil

No matter what the underlying implementation is, if you feel the need here already for those fine-grained definitions, how about providing some predicate methods for them? Like

• doing?
• done?
• error?
• success? (implies done? && !error? )
• scheduled?

Be prepared for more complexity here: It might not always be so simplistic. It might become necessary to make a difference between different phases of execution / probing, and in some cases, you might want to report them on a more granular level.

Well, few notes:

1. should be phase string or unsigned int with enum and 1 for probe and 2 for install?
2. for status I do not like that additional parameter is array of string. Why not generic hash?
3. and this is related to 2. I would not have separated progress method and instead have that progress info in that generic hash from 2 when status is doing.

Since this is using or introducing integer enumerations, here's an Issue to address their D-Bus representation: openSUSE/agama#212