`Ranges::from_iter`, `Ranges:from_unsorted` and document ranges invariants #273

konstin · 2024-11-04T23:56:14Z

Motivation

https://github.com/astral-sh/uv/pull/8797/files#diff-17170cd58cc6474d6c6ee0413af4b3b28610aca267bbe7863411627219c26549R232 needs to modify an existing Ranges. We don't want to allow direct access to ranges since this allows breaking the version-ranges invariants. This led me to two questions: How do we best construct ranges from a number of versions (#249), does the user need to hold up the invariants or do we sort and merge the given ranges? And: What are our invariants?

Given my previous profiling, construction ranges isn't nearly noticeable in benchmarks (but i'm gladly proven otherwise), the input ranges are too small and we do orders of magnitude more ranges constructions in the pubgrub algorithm itself, so the primary problem of https://github.com/astral-sh/uv/pull/8797/files#diff-17170cd58cc6474d6c6ee0413af4b3b28610aca267bbe7863411627219c26549R232 and #249 is ergonomics and zero-to-low overhead construction is a secondary problem, one that i'm tackling only because it would be inconsistent to have a slow API in pubgrub. Currently, we don't have a method for constructing ranges from multiple segments and this makes for an unergonomic API.

Invariants

For the invariants, we need 1), but i'm not clear if we also need 2) and 3) as strong as they are. They are currently invariants in the version ranges, but we could weaken them. What i like about them is that they imply that any instance of ranges is "fully reduced", it can't be simplified further (without knowning the actual versions available).

The segments are sorted, from lowest to highest (through Ord).
Each segment contains at least one version (start < end).
There is at least one version between two segments.

API

I added two functions: A from_iter where the user has to pass valid segments. This wants to be a try_collect, but that's still unstable. It is targeted at https://github.com/astral-sh/uv/pull/8797/files#diff-17170cd58cc6474d6c6ee0413af4b3b28610aca267bbe7863411627219c26549R232, which currently does this in a less secure fashion. There, you'd replace iter_mut().for_each(...) with an .into_iter().map(...).collect() (With the IntoIter i've also added this shouldn't even be an allocation; i'm optimizing this too for consistency's sake but i'd be surprised if it mattered to users). The other is from_unsorted which is ergonomics and could be used for https://github.com/astral-sh/uv/blob/0335efd0a901ee2351e663d0488b1ce87fd4cc80/crates/pep508-rs/src/marker/algebra.rs#L638-L645 and https://github.com/astral-sh/uv/blob/e1a8beb64b9f6eb573b3af616ffff680c282a316/crates/uv-resolver/src/pubgrub/report.rs#L1098-L1102 from #249. The user passes arbitrary segments and we're merging them into valid ranges.

Please discuss :)

## Motivation https://github.com/astral-sh/uv/pull/8797/files#diff-17170cd58cc6474d6c6ee0413af4b3b28610aca267bbe7863411627219c26549R232 needs to modify an existing `Ranges`. We don't want to allow direct access to ranges since this allows breaking the version-ranges invariants. This led me to two questions: How do we best construct ranges from a number of versions (#249), does the user need to hold up the invariants or do we sort and merge the given ranges? And: What are our invariants? Given my previous profiling, construction ranges isn't nearly noticeable in benchmarks (but i'm gladly proven otherwise), the input ranges are too small and we do orders of magnitude more ranges constructions in the pubgrub algorithm itself, so the primary problem of https://github.com/astral-sh/uv/pull/8797/files#diff-17170cd58cc6474d6c6ee0413af4b3b28610aca267bbe7863411627219c26549R232 and #249 is ergonomics and zero-to-low overhead construction is a secondary problem, one that i'm tackling only because it would be inconsistent to have a slow API in pubgrub. Currently, we don't have a method for constructing ranges from multiple segments and this makes for an unergonomic API. ## Invariants For the invariants, we need 1), but i'm not clear if we also need 2) and 3) as strong as they are. They are currently invariants in the version ranges, but we could weaken them. What i like about them is that they imply that any instance of ranges is "fully reduced", it can't be simplified further (without knowning the actual versions available). 1. The segments are sorted, from lowest to highest (through `Ord`). 2. Each segment contains at least one version (start < end). 3. There is at least one version between two segments. ## API I added two functions: A `from_iter` where the user has to pass valid segments. This wants to be a `try_collect`, but that's still unstable. It is targeted at https://github.com/astral-sh/uv/pull/8797/files#diff-17170cd58cc6474d6c6ee0413af4b3b28610aca267bbe7863411627219c26549R232, which currently does this in a less secure fashion. There, you'd replace `iter_mut().for_each(...)` with an `.into_iter().map(...).collect()` (With the `IntoIter` i've also added this shouldn't even be an allocation; i'm optimizing this too for consistency's sake but i'd be surprised if it mattered to users). The other is `from_unsorted` which is ergonomics and could be used for https://github.com/astral-sh/uv/blob/0335efd0a901ee2351e663d0488b1ce87fd4cc80/crates/pep508-rs/src/marker/algebra.rs#L638-L645 and https://github.com/astral-sh/uv/blob/e1a8beb64b9f6eb573b3af616ffff680c282a316/crates/uv-resolver/src/pubgrub/report.rs#L1098-L1102 from #249. The user passes arbitrary segments and we're merging them into valid ranges. Please discuss :)

See pubgrub-rs#273, it's split out from that PR, for https://github.com/astral-sh/uv/pull/8797/files. Closes #33

Use astral-sh/pubgrub#34 (pubgrub-rs/pubgrub#273) for safer ranges modification that can't break pubgrub invariants. In the process, I removed the `&mut` references in favor of a direct immutable-to-immutable mapping.

Eh2406

These all look like useful changes!

Eh2406 · 2024-11-05T16:23:41Z

version-ranges/src/lib.rs

+    /// We want to use `iterator_try_collect`, but since it's unstable at the time of writing,
+    /// we expose a public `FromIterator<(Bound<V>, Bound<V>)>` method and use this for internal
+    /// testing.
+    fn try_from(


when I see try_from I think of the TryFrom trait. Perhaps try_from_iterator?

Eh2406 · 2024-11-05T16:25:57Z

version-ranges/src/lib.rs

+            return Err(FromIterError::InvalidSegment);
+        }
+        segments.push(previous);
+        Ok(Self { segments })


let's put a call to .check_invariants() to make it easier to spot if we break things.

Eh2406 · 2024-11-05T16:27:54Z

version-ranges/src/lib.rs

@@ -283,6 +290,37 @@ impl<V: Ord> Ranges<V> {
        }
    }

+    /// We want to use `iterator_try_collect`, but since it's unstable at the time of writing,


This user facing documentation also needs to describe what this function does, and what the requirements are on the arguments, and when it returns an error.

Yeah this comment seems more like an internal note?

This isn't user facing, the function only exists internally for testing; if it weren't for the proptests this function wouldn't exist at all, from_iter is the real thing. I'll update the docs to redirect to from_iter.

Eh2406 · 2024-11-05T16:35:07Z

version-ranges/src/lib.rs

+        });
+        // TODO(konsti): Handroll this. We're relying on the union implementation treating each
+        // segment as potentially coming from the other ranges and merging overlapping bounds.
+        Self { segments }.union(&Self {


Agree with your comment here, it's cute that union with empty happens normalize our invariants, but it seems grungy to rely on it. I rather unroll it here. If there's too much duplicated code then we can have a private reestablish_invariants_by_unionizing that both methods can call.

Eh2406 · 2024-11-05T16:37:29Z

version-ranges/src/lib.rs

+            .filter(|segment| valid_segment(&segment.start_bound(), &segment.end_bound()))
+            .collect();
+        segments.sort_by(|a: &Interval<V>, b: &Interval<V>| {
+            if a.start_bound() == b.start_bound() {


I think we can reuse the existing cmp_bounds_start for this sort.

Eh2406 · 2024-11-05T16:38:56Z

version-ranges/src/lib.rs

+impl<V> IntoIterator for Ranges<V> {
+    type Item = (Bound<V>, Bound<V>);
+    // TODO(konsti): We must not leak the type here!
+    type IntoIter = smallvec::IntoIter<[Interval<V>; 1]>;


Specifically, this has to be opaque because we want to change the the representation to no longer have Interval<V>

konstin · 2024-11-05T17:41:24Z

@Eh2406 what do you think about the invariants and about the functions in general? I've also been thinking that if we handroll the from unsorted variant, we could fast-path already matching inputs so we may not need the panicking function?

Eh2406 · 2024-11-05T21:21:32Z

what do you think about the invariants and about the functions in general?

I think those are the invariants we currently maintain. The reason we need a "fully reduced" form or at least a canonicalised form is so that Eq works. But as long as these invariants are internal details, we can always change them later. Better internal documentation is always welcome.

The new functionality seems extremely useful.

konstin added 2 commits November 5, 2024 00:55

Filter to valid segments

0e1502b

konstin added a commit to astral-sh/pubgrub that referenced this pull request Nov 5, 2024

Add Ranges::from_iter

30502ce

See pubgrub-rs#273, it's split out from that PR, for https://github.com/astral-sh/uv/pull/8797/files. Closes #33

konstin mentioned this pull request Nov 5, 2024

Add Ranges::from_iter astral-sh/pubgrub#34

Open

konstin mentioned this pull request Nov 5, 2024

Use Ranges::from_iter over Ranges::iter_mut astral-sh/uv#8825

Closed

Eh2406 approved these changes Nov 5, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

`Ranges::from_iter`, `Ranges:from_unsorted` and document ranges invariants #273

`Ranges::from_iter`, `Ranges:from_unsorted` and document ranges invariants #273

konstin commented Nov 4, 2024

Eh2406 left a comment

Eh2406 Nov 5, 2024

Eh2406 Nov 5, 2024

Eh2406 Nov 5, 2024

zanieb Nov 5, 2024

konstin Nov 5, 2024

Eh2406 Nov 5, 2024

Eh2406 Nov 5, 2024

Eh2406 Nov 5, 2024

konstin commented Nov 5, 2024

Eh2406 commented Nov 5, 2024

Ranges::from_iter, Ranges:from_unsorted and document ranges invariants #273

Are you sure you want to change the base?

Ranges::from_iter, Ranges:from_unsorted and document ranges invariants #273

Conversation

konstin commented Nov 4, 2024

Motivation

Invariants

API

Eh2406 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

konstin commented Nov 5, 2024

Eh2406 commented Nov 5, 2024

`Ranges::from_iter`, `Ranges:from_unsorted` and document ranges invariants #273

`Ranges::from_iter`, `Ranges:from_unsorted` and document ranges invariants #273