go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/cipkg/core/packages.go (about)

     1  // Copyright 2023 The LUCI Authors.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //	http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package core
    16  
    17  import (
    18  	"errors"
    19  )
    20  
    21  // PackageManager represents the management interface for packages to provide
    22  // a place for storing and retrieving packages.
    23  type PackageManager interface {
    24  	// Get(id) returns the handler for the package.
    25  	Get(id string) PackageHandler
    26  }
    27  
    28  var (
    29  	// ErrPackageNotExist returns when trying to increase the reference of a
    30  	// non-existent package.
    31  	ErrPackageNotExist = errors.New("package does not exist")
    32  )
    33  
    34  // PackageHandler is the interface for a handler in the storage. The content of
    35  // a package can be built by calling Build(func(Package) error) error, which
    36  // will make package available if successful and can be referenced by other
    37  // packages. Package shouldn't be modified after build.
    38  type PackageHandler interface {
    39  	// OutputDirectory() returns the output directory.
    40  	OutputDirectory() string
    41  
    42  	// LoggingDirectory() returns the logging directory.
    43  	LoggingDirectory() string
    44  
    45  	// Build(buildFunc) makes packages available in the storage.
    46  	// It's responsible for:
    47  	// - Hold exclusive lock to the package during the build.
    48  	// - Ensure build only happens once unless the package is removed.
    49  	// - Check the remote cache server (if possible).
    50  	// - Set up the build environment (e.g. create output directory).
    51  	// - Mark package available if build function successfully returns.
    52  	// Calling build function is expected to trigger the actual build.
    53  	Build(builder func() error) error
    54  
    55  	// TryRemove(), IncRef(), DecRef() are the interface for removable packages.
    56  	// If removing package is not supported by PackageManager, TryRemove() will
    57  	// always return false.
    58  	// IncRef() and DecRef() references/dereferences the package to prevent
    59  	// package from being removed, thus they can be no-op if the removal never
    60  	// happens.
    61  
    62  	// TryRemove() may remove the package only if there is no reference to it.
    63  	TryRemove() (ok bool, err error)
    64  
    65  	// Reference the package to prevent it from being removed while in use.
    66  	// IncRef() updates the last access time of the package as well.
    67  	// IncRef() only succeeds if the package is available.
    68  	// Otherwise ErrPackageNotExist will be returned.
    69  	IncRef() error
    70  	DecRef() error
    71  }