Garbage collection

Garbage Collection (GC) is the process for removing "unnecessary" blobs from a device. It is usually performed to free up disk space so that new ephemeral packages can be resolved or to OTA (which internally makes use of package resolution).

How to trigger

GC is implemented by pkg-cache, which exposes the functionality via fuchsia.space/Manager.GC.

It can be triggered manually by running fx shell pkgctl gc.

It is automatically triggered (if necessary) at various points during OTA by the system-updater.

It is automatically triggered (if necessary) by the system-update-checker, which is the update checker used by engineering builds.

The algorithm

The current algorithm is based on the design proposed by the Open Package Tracking RFC.

Definitions

  • Base packages
    • The "base" or "system_image" package (identified by hash in the boot arguments) and the packages listed (by hash) in its data/static_packages file.
    • Generally intended to be the minimal set of packages required to run a particular configuration.
  • Cache packages
    • The packages listed (by hash) in the "base" package's data/cache_packages.json file.
    • Conceptually packages that we would like to use without networking but still want the option to ephemerally update.
  • Open packages
  • Writing index
    • Packages whose blobs are currently being written as part of a resolve
  • Retained index
    • Packages that were/will be downloaded during OTA and are used during the OTA process or are necessary for the next system version.
    • Manipulated by the system-updater during the OTA process to meet the OTA storage requirements.
  • Package blobs
    • All the blobs required by a package.
    • The meta.far and content blobs, plus the package blobs of all subpackages, recursively.
    • As a result of this definition, protecting a package from GC protects all of its subpackages. The subpackages, as packages themselves, may or may not be protected independently of protection provided by a superpackage.

Implementation

  1. Fail if the current boot partition has not been marked healthy, to avoid deleting blobs needed by the previous system in case of fallback
  2. Determine the set of all resident blobs, Br
  3. Lock the Writing and Retained indices
  4. Determine the set of all protected blobs, Bp, which is the package blobs of all of the following packages:
    • Base packages
    • Cache packages
    • Open packages
    • Writing index packages
    • Retained index packages
  5. Delete the blobs of the set difference Br - Bp
  6. Unlock the Writing and Retained indices