Unverified Commit 3c2f9be2 authored by Sam Poder's avatar Sam Poder Committed by GitHub

[turbopack] Add `clusters` to chunking heuristics (#95157)

The goal of this PR increase the expected benefit of merging two chunks
when their overlapping chunk groups are in a "cluster" (a cluster is a
set of routes that are commonly visited together). This is because in
these cases the Z+Z case (one of six in the N=2 set of cases) is more
likely than others. To this I have increased the probability of the Z+Z
case.

At the moment, to do this I've done the following to the probabilities:

```rust
/*
MERGED CASE (N = 2):
case X + X (p = (a_rem/groups) * ((a_rem - 1)/rem_g)): size = a_size, requests = 1
case Y + Y (p = (b_rem/groups) * ((b_rem - 1)/rem_g)): size = b_size, requests = 1
case Z + Z (p = (o_groups/groups) * (o_groups - 1)/rem_g): size = (a_size + b_size), requests = 1
case X + Y (p = (a_rem/groups) * (b_rem/rem_g) + (b_rem/groups) * (a_rem/rem_g)): size = a_size + b_size, requests = 2
case X + Z (p = (a_rem/groups) * (o_groups/rem_g) + (o_groups/groups) * (a_rem/rem_g)): size = a_size + (a_size + b_size), requests = 2
case Y + Z (p = (b_rem/groups) * (o_groups/rem_g) + (o_groups/groups) * (b_rem/rem_g)): size = b_size + (a_size + b_size), requests = 2

Request count is different in this case: Z + Z (better)
Requests size is different (worse) in these cases: X + Z, Y + Z

Each cost / benefit is weighted by the probabilities above. There are cases when
we know that Z + Z is more likely due to common user behaviour. This is based on
the "cluster" chunking heuristic we provide. We increase P(Z + Z) when two or more
routes in a cluster request both chunk items together (ie. request Z). P(X + Z) and
P(Y + Z) are therefore less likely. To increase P(Z + Z) while maintaining a total
probability of 1, we do the following (when chunk items overlap in a cluster):

P'(X + Z) = (1/2) * P(X + Z)
P'(Y + Z) = (1/2) * P(Y + Z)
P'(Z + Z) = P(Z + Z) + (1/2) * P(X + Z) + (1/2) * P(Y + Z)

Otherwise:

P'(X + Z) = P(X + Z)
P'(Y + Z) = P(Y + Z)
P'(Z + Z) = P(Z + Z)
*/
```

This increases `P'(Z + Z)` while reducing `P'(X + Z)` and `P'(Y + Z)`.
It is a bit of a blunt tool for doing this, however. So if anyone has
other suggestions for how to change this probabilities while maintaining
existing behaviour - let me know!
parent 0d5d2fb1
......@@ -7,7 +7,7 @@ use either::Either;
use rustc_hash::FxHashSet;
use serde::{Deserialize, Deserializer, Serialize};
use serde_json::Value as JsonValue;
use turbo_esregex::EsRegex;
use turbo_esregex::{EsRegex, EsRegexSet};
use turbo_rcstr::{RcStr, rcstr};
use turbo_tasks::{
FxIndexMap, NonLocalValue, OperationValue, ResolvedVc, TryJoinIterExt, Vc,
......@@ -1150,6 +1150,9 @@ const DEFAULT_WEIGHT_DISTRIBUTION: f32 = 0.1;
)]
#[serde(rename_all = "camelCase")]
pub struct TurbopackChunkingConfig {
/// Groups of pages commonly visited together, each defined by a list of regular expressions
/// matched against the route pathname. The cluster ID is the index in this list.
clusters: Option<Vec<Vec<RegexComponents>>>,
/// A number between `0.0..=1.0`. Higher values weight the benefit of merging
/// chunks for a single page load more heavily. A site's bounce rate is a good
/// approximation if you don't have a better value.
......@@ -1183,10 +1186,12 @@ pub struct TurbopackChunkingConfig {
#[turbo_tasks::value]
pub struct TurbopackChunking {
/// The route-matching regexes for each user-defined cluster.
clusters: Vec<EsRegexSet>,
/// First-page-load priority as an integer percentage (`0..=100`), or `None` if unset.
pub first_page_load_priority: Option<u32>,
/// Route-matching regexes for priority routes.
priority_routes: Vec<EsRegex>,
priority_routes: EsRegexSet,
/// Priority-route boost as an integer percentage (e.g. `150` for a 1.5x boost), or
/// `None` to use the default.
pub priority_boost_percent: Option<u32>,
......@@ -1206,33 +1211,35 @@ pub struct TurbopackChunking {
impl TurbopackChunking {
/// Compute the [`EntryHeuristics`] for a route `pathname` by matching it against the configured
/// priority-route regexes.
/// cluster and priority-route regexes.
pub fn entry_heuristics_for(&self, pathname: &str) -> EntryHeuristics {
let high_priority = self
.priority_routes
let clusters = self
.clusters
.iter()
.filter(|regex| regex.as_regex_str().is_none())
.any(|regex| regex.is_match(pathname))
|| regex::RegexSet::new(
self.priority_routes
.iter()
.filter_map(|regex| regex.as_regex_str()),
)
.is_ok_and(|set| set.is_match(pathname));
EntryHeuristics { high_priority }
.enumerate()
.filter(|(_, regexes)| regexes.is_match(pathname))
.map(|(index, _)| index as u16)
.collect();
let high_priority = self.priority_routes.is_match(pathname);
EntryHeuristics {
clusters,
high_priority,
}
}
}
/// Compile a list of route-matching [`RegexComponents`] into [`EsRegex`]es.
fn parse_route_regexes(patterns: &[RegexComponents]) -> Result<Vec<EsRegex>> {
patterns
/// Compile a list of route-matching [`RegexComponents`] into an [`EsRegexSet`], which builds the
/// combined [`regex::RegexSet`] up front so that matching a route doesn't have to.
fn parse_route_regexes(patterns: &[RegexComponents]) -> Result<EsRegexSet> {
let regexes = patterns
.iter()
.cloned()
.map(|pattern| {
EsRegex::try_from(pattern)
.context("Invalid route pattern in `experimental.turbopackChunking`")
})
.collect()
.collect::<Result<Vec<_>>>()?;
Ok(EsRegexSet::new(regexes))
}
/// Resolve `experimental.cssChunking` to the [`StyleGroupsAlgorithm`] Turbopack should use.
......@@ -2165,12 +2172,19 @@ impl NextConfig {
#[turbo_tasks::function]
pub fn turbopack_chunking(&self) -> Result<Vc<TurbopackChunking>> {
let config = self.experimental.turbopack_chunking.as_ref();
let clusters = config
.and_then(|c| c.clusters.as_deref())
.unwrap_or_default()
.iter()
.map(|patterns| parse_route_regexes(patterns))
.collect::<Result<Vec<_>>>()?;
let priority_routes = parse_route_regexes(
config
.and_then(|c| c.priority_routes.as_deref())
.unwrap_or_default(),
)?;
Ok(TurbopackChunking {
clusters,
first_page_load_priority: config
.and_then(|c| c.first_page_load_priority)
.map(|priority| (priority.clamp(0.0, 1.0) * 100.0).round() as u32),
......
......@@ -1050,6 +1050,9 @@ function bindingToApi(
...nextConfigSerializable.experimental,
turbopackChunking: {
...chunkingConfig,
clusters: chunkingConfig.clusters?.map((cluster: RegExp[]) =>
cluster.map(regexComponents)
),
priorityRoutes: chunkingConfig.priorityRoutes?.map(regexComponents),
},
}
......
......@@ -396,6 +396,7 @@ export const experimentalSchema = {
turbopackSharedRuntime: z.boolean().optional(),
turbopackChunking: z
.object({
clusters: z.array(z.array(z.instanceof(RegExp))).optional(),
firstPageLoadPriority: z.number().min(0).max(1).optional(),
priorityRoutes: z.array(z.instanceof(RegExp)).optional(),
priorityBoost: z.number().min(1).optional(),
......
......@@ -805,6 +805,19 @@ export interface ExperimentalConfig {
* making chunk merging decisions and the raw size thresholds it uses.
*/
turbopackChunking?: {
/**
* Groups of pages commonly visited together, each defined by a list of regular
* expressions matched against the route pathname.
*
* @example
* ```js
* clusters: [
* [/^\/dashboard/, /^\/dashboard\/settings/],
* [/^\/blog/, /^\/blog\/[^/]+$/],
* ]
* ```
*/
clusters?: RegExp[][]
/**
* This is a number between `0..1`, when higher, we weight the benefits of
* merging chunks for a signal page load higher. If you don't know a good
......
......@@ -161,6 +161,89 @@ impl EsRegex {
}
}
/// A group of [`EsRegex`]es matched against a haystack as a unit.
///
/// The members backed by the `regex` crate are compiled into a single [`regex::RegexSet`] once,
/// when the group is built, rather than on every match. The remainder (those that fall back to
/// `regress`, e.g. for lookahead) are matched one at a time.
#[derive(Debug, Clone)]
#[turbo_tasks::value(eq = "manual", shared, serialization = "custom")]
pub struct EsRegexSet {
/// The members, in the order they were given. Also the source of truth for equality and
/// serialization, since [`regex::RegexSet`] supports neither.
regexes: Vec<EsRegex>,
/// The combined members, or `None` if the combined program couldn't be built.
#[turbo_tasks(trace_ignore)]
set: Option<regex::RegexSet>,
/// Indices into `regexes` of the members `set` doesn't cover. Usually empty.
individual: Vec<u32>,
}
impl PartialEq for EsRegexSet {
fn eq(&self, other: &Self) -> bool {
self.regexes == other.regexes
}
}
impl Eq for EsRegexSet {}
impl Encode for EsRegexSet {
fn encode<E: Encoder>(&self, encoder: &mut E) -> Result<(), EncodeError> {
self.regexes.encode(encoder)
}
}
impl<Context> Decode<Context> for EsRegexSet {
fn decode<D: Decoder<Context = Context>>(decoder: &mut D) -> Result<Self, DecodeError> {
let regexes: Vec<EsRegex> = Decode::decode(decoder)?;
Ok(EsRegexSet::new(regexes))
}
}
impl_borrow_decode!(EsRegexSet);
impl Default for EsRegexSet {
fn default() -> Self {
Self::new(Vec::new())
}
}
impl EsRegexSet {
/// Builds the combined matcher. Members backed by `regress` can't join a
/// [`regex::RegexSet`], and the combined program has its own size limit; either way the
/// leftovers are recorded up front and matched one at a time.
pub fn new(regexes: Vec<EsRegex>) -> Self {
let set = regex::RegexSet::new(regexes.iter().filter_map(EsRegex::as_regex_str)).ok();
let individual = regexes
.iter()
.enumerate()
.filter(|(_, regex)| set.is_none() || regex.as_regex_str().is_none())
.map(|(index, _)| index as u32)
.collect();
Self {
regexes,
set,
individual,
}
}
/// Returns true if any member matches somewhere in the `haystack`.
pub fn is_match(&self, haystack: &str) -> bool {
if let Some(set) = &self.set
&& set.is_match(haystack)
{
return true;
}
self.individual
.iter()
.any(|&index| self.regexes[index as usize].is_match(haystack))
}
/// Returns true if the group has no members.
pub fn is_empty(&self) -> bool {
self.regexes.is_empty()
}
}
pub struct Captures<'h> {
delegate: CapturesImpl<'h>,
}
......@@ -216,7 +299,75 @@ impl<'h> Iterator for Captures<'h> {
#[cfg(test)]
mod tests {
use super::{EsRegex, EsRegexImpl};
use super::{EsRegex, EsRegexImpl, EsRegexSet};
#[test]
fn es_regex_set_matches_either_delegate() {
// `a(?!b)` needs regress; `^/docs` is handled by the shared `RegexSet`.
let set = EsRegexSet::new(vec![
EsRegex::new("^/docs", "").unwrap(),
EsRegex::new("a(?!b)", "").unwrap(),
]);
assert_eq!(set.individual, vec![1]);
assert!(set.is_match("/docs/getting-started"));
assert!(set.is_match("ac"));
assert!(!set.is_match("/blog"));
assert!(!set.is_match("ab"));
}
#[test]
fn es_regex_set_combines_every_member_when_it_can() {
let set = EsRegexSet::new(vec![
EsRegex::new("^/docs", "").unwrap(),
EsRegex::new("^/blog", "").unwrap(),
]);
// A miss only queries the combined set, not every member again.
assert!(set.individual.is_empty());
assert!(set.is_match("/docs"));
assert!(set.is_match("/blog"));
assert!(!set.is_match("/about"));
}
#[test]
fn empty_es_regex_set_never_matches() {
let set = EsRegexSet::default();
assert!(set.is_empty());
assert!(!set.is_match(""));
assert!(!set.is_match("/docs"));
}
#[test]
fn oversized_es_regex_set_falls_back_to_matching_individually() {
// Each of these compiles on its own but together they blow the combined size limit.
const N: usize = 60_000;
let regexes = vec![
EsRegex::new(&format!("^/docs/[0-9a-zA-Z]{{{N}}}"), "").unwrap(),
EsRegex::new(&format!("^/blog/[0-9a-zA-Z]{{{N}}}"), "").unwrap(),
];
assert!(regexes.iter().all(|regex| regex.as_regex_str().is_some()));
let set = EsRegexSet::new(regexes);
assert!(set.set.is_none());
assert_eq!(set.individual, vec![0, 1]);
assert!(set.is_match(&format!("/docs/{}", "a".repeat(N))));
assert!(set.is_match(&format!("/blog/{}", "a".repeat(N))));
assert!(!set.is_match("/about"));
}
#[test]
fn es_regex_set_round_trip_bincode() {
let set = EsRegexSet::new(vec![
EsRegex::new("^/docs", "").unwrap(),
EsRegex::new("a(?!b)", "").unwrap(),
]);
let config = bincode::config::standard();
let encoded = bincode::encode_to_vec(&set, config).unwrap();
let (decoded, len) = bincode::decode_from_slice::<EsRegexSet, _>(&encoded, config).unwrap();
assert_eq!(set, decoded);
assert_eq!(len, encoded.len());
// The `RegexSet` is rebuilt on decode, not carried in the encoding.
assert!(decoded.is_match("/docs"));
assert!(decoded.is_match("ac"));
}
#[test]
fn round_trip_bincode() {
......
......@@ -97,8 +97,9 @@ pub struct ChunkGroupInfo {
pub chunking_heuristics: ChunkingHeuristicsInfo,
}
/// Chunking heuristics computed by [`compute_chunk_group_info`]. `priority_routes` is a set of
/// chunk-group indices (same indexing as [`ChunkGroupInfo::chunk_groups`]).
/// Chunking heuristics computed by [`compute_chunk_group_info`]. `clusters` is indexed by
/// chunk-group index (same length and order as [`ChunkGroupInfo::chunk_groups`]); `priority_routes`
/// is a set of those indices.
#[derive(
Debug,
Default,
......@@ -112,6 +113,12 @@ pub struct ChunkGroupInfo {
Decode,
)]
pub struct ChunkingHeuristicsInfo {
/// For each chunk group (by index), the set of cluster IDs it belongs to. A cluster ID is the
/// index of a configured cluster. A route's chunk group carries that route's clusters; chunk
/// groups it pulls in inherit them.
///
/// Example: `clusters[5] = [0, 2]` — chunk group 5 is part of clusters 0 and 2.
pub clusters: Vec<Vec<u16>>,
/// The set of chunk-group indices that belong to a priority route: the priority
/// routes themselves, plus every chunk group they pull in.
///
......@@ -155,13 +162,17 @@ impl ChunkGroupInfo {
#[turbo_tasks::task_input]
#[derive(Debug, Default, Clone, Hash, PartialEq, Eq, TraceRawVcs, Encode, Decode)]
pub struct EntryHeuristics {
/// Cluster indices this route belongs to.
pub clusters: Vec<u16>,
pub high_priority: bool,
}
impl EntryHeuristics {
/// Heuristics for an entry that is a high-priority route.
/// Heuristics for an entry that is a high-priority route: belongs to no clusters and is marked
/// as high priority.
pub fn high_priority() -> Self {
Self {
clusters: Vec::new(),
high_priority: true,
}
}
......@@ -813,9 +824,10 @@ pub async fn compute_chunk_group_info(graph: &ModuleGraph) -> Result<Vc<ChunkGro
}
}
// Resolve per-chunk-group chunking heuristics. Entry chunk groups carry their route's
// priority-route flag; other chunk groups inherit it (OR) from their referencing chunk
// groups.
// Resolve per-chunk-group chunking heuristics. Entry
// chunk groups carry their route's clusters / priority-route flag; other chunk groups
// inherit the union of clusters (and OR of the flag) from their referencing chunk groups.
let mut clusters: Vec<RoaringBitmap> = vec![RoaringBitmap::new(); chunk_groups_map.len()];
let mut priority_routes = RoaringBitmap::new();
let mut worklist: Vec<usize> = Vec::new();
......@@ -828,18 +840,24 @@ pub async fn compute_chunk_group_info(graph: &ModuleGraph) -> Result<Vc<ChunkGro
else {
continue;
};
if !heuristics.high_priority {
if heuristics.clusters.is_empty() && !heuristics.high_priority {
continue;
}
if let Some(index) =
chunk_groups_map.get_index_of(&ChunkGroupKey::Entry(modules.clone()))
&& priority_routes.insert(index as u32)
{
worklist.push(index);
if clusters[index].is_empty() && !priority_routes.contains(index as u32) {
worklist.push(index);
}
clusters[index].extend(heuristics.clusters.iter().map(|&c| c as u32));
if heuristics.high_priority {
priority_routes.insert(index as u32);
}
}
}
while let Some(source) = worklist.pop() {
let source_priority_route = priority_routes.contains(source as u32);
let Some(targets) = inherits_from.get(&(source as u32)) else {
continue;
};
......@@ -848,18 +866,29 @@ pub async fn compute_chunk_group_info(graph: &ModuleGraph) -> Result<Vc<ChunkGro
if target == source {
continue;
}
if priority_routes.insert(target as u32) {
let [source_clusters, target_clusters] =
clusters.get_disjoint_mut([source, target]).unwrap();
let previous_target_clusters_len = target_clusters.len();
*target_clusters |= &*source_clusters;
let changed = (source_priority_route && priority_routes.insert(target as u32))
|| previous_target_clusters_len != target_clusters.len();
if changed {
worklist.push(target);
}
}
}
let chunk_group_clusters: Vec<Vec<u16>> = clusters
.into_iter()
.map(|bm| bm.iter().map(|id| id as u16).collect())
.collect();
let chunk_group_priority_routes = RoaringBitmapWrapper(priority_routes);
Ok(ChunkGroupInfo {
module_chunk_groups: ResolvedVc::cell(module_chunk_groups),
chunk_group_keys: chunk_groups_map.keys().cloned().collect(),
chunking_heuristics: ChunkingHeuristicsInfo {
clusters: chunk_group_clusters,
priority_routes: chunk_group_priority_routes,
},
chunk_groups: chunk_groups_map
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment