Trait pubgrub::solver::DependencyProvider

pub trait DependencyProvider {
    type P: Package;
    type V: Debug + Display + Clone + Ord;
    type VS: VersionSet<V = Self::V>;
    type Priority: Ord + Clone;
    type Err: Error + 'static;

    // Required methods
    fn prioritize(&self, package: &Self::P, range: &Self::VS) -> Self::Priority;
    fn choose_version(
        &self,
        package: &Self::P,
        range: &Self::VS
    ) -> Result<Option<Self::V>, Self::Err>;
    fn get_dependencies(
        &self,
        package: &Self::P,
        version: &Self::V
    ) -> Result<Dependencies<Self::P, Self::VS>, Self::Err>;

    // Provided method
    fn should_cancel(&self) -> Result<(), Self::Err> { ... }
}

Trait that allows the algorithm to retrieve available packages and their dependencies. An implementor needs to be supplied to the resolve function.

Required Associated Types

type P: Package

How this provider stores the name of the packages.

type V: Debug + Display + Clone + Ord

How this provider stores the versions of the packages.

type VS: VersionSet<V = Self::V>

How this provider stores the version requirements for the packages. The requirements must be able to process the same kind of version as this dependency provider.

type Priority: Ord + Clone

The type returned from prioritize. The resolver does not care what type this is as long as it can pick a largest one and clone it.

std::cmp::Reverse can be useful if you want to pick the package with the fewest versions that match the outstanding constraint.

type Err: Error + 'static

The kind of error returned from these methods.

Returning this signals that resolution should fail with this error.

Required Methods

fn prioritize(&self, package: &Self::P, range: &Self::VS) -> Self::Priority

Decision making is the process of choosing the next package and version that will be appended to the partial solution.

Every time such a decision must be made, the resolver looks at all the potential valid packages that have changed, and a asks the dependency provider how important each one is. For each one it calls prioritize with the name of the package and the current set of acceptable versions. The resolver will then pick the package with the highes priority from all the potential valid packages.

The strategy employed to prioritize packages cannot change the existence of a solution or not, but can drastically change the performances of the solver, or the properties of the solution. The documentation of Pub (PubGrub implementation for the dart programming language) states the following:

Pub chooses the latest matching version of the package with the fewest versions that match the outstanding constraint. This tends to find conflicts earlier if any exist, since these packages will run out of versions to try more quickly. But there’s likely room for improvement in these heuristics.

Note: the resolver may call this even when the range has not change, if it is more efficient for the resolveres internal data structures.

fn choose_version( &self, package: &Self::P, range: &Self::VS ) -> Result<Option<Self::V>, Self::Err>

Once the resolver has found the highest Priority package from all potential valid packages, it needs to know what vertion of that package to use. The most common pattern is to select the largest vertion that the range contains.

fn get_dependencies( &self, package: &Self::P, version: &Self::V ) -> Result<Dependencies<Self::P, Self::VS>, Self::Err>

Retrieves the package dependencies. Return Dependencies::Unknown if its dependencies are unknown.

Provided Methods

fn should_cancel(&self) -> Result<(), Self::Err>

This is called fairly regularly during the resolution, if it returns an Err then resolution will be terminated. This is helpful if you want to add some form of early termination like a timeout, or you want to add some form of user feedback if things are taking a while. If not provided the resolver will run as long as needed.

Implementors

impl<P: Package, VS: VersionSet> DependencyProvider for OfflineDependencyProvider<P, VS>

An implementation of DependencyProvider that contains all dependency information available in memory. Currently packages are picked with the fewest versions contained in the constraints first. But, that may change in new versions if better heuristics are found. Versions are picked with the newest versions first.

type P = P

type V = <VS as VersionSet>::V

type VS = VS

type Err = Infallible

type Priority = Reverse<usize>