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; ...@@ -7,7 +7,7 @@ use either::Either;
use rustc_hash::FxHashSet; use rustc_hash::FxHashSet;
use serde::{Deserialize, Deserializer, Serialize}; use serde::{Deserialize, Deserializer, Serialize};
use serde_json::Value as JsonValue; use serde_json::Value as JsonValue;
use turbo_esregex::EsRegex; use turbo_esregex::{EsRegex, EsRegexSet};
use turbo_rcstr::{RcStr, rcstr}; use turbo_rcstr::{RcStr, rcstr};
use turbo_tasks::{ use turbo_tasks::{
FxIndexMap, NonLocalValue, OperationValue, ResolvedVc, TryJoinIterExt, Vc, FxIndexMap, NonLocalValue, OperationValue, ResolvedVc, TryJoinIterExt, Vc,
...@@ -1150,6 +1150,9 @@ const DEFAULT_WEIGHT_DISTRIBUTION: f32 = 0.1; ...@@ -1150,6 +1150,9 @@ const DEFAULT_WEIGHT_DISTRIBUTION: f32 = 0.1;
)] )]
#[serde(rename_all = "camelCase")] #[serde(rename_all = "camelCase")]
pub struct TurbopackChunkingConfig { 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 /// 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 /// 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. /// approximation if you don't have a better value.
...@@ -1183,10 +1186,12 @@ pub struct TurbopackChunkingConfig { ...@@ -1183,10 +1186,12 @@ pub struct TurbopackChunkingConfig {
#[turbo_tasks::value] #[turbo_tasks::value]
pub struct TurbopackChunking { 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. /// First-page-load priority as an integer percentage (`0..=100`), or `None` if unset.
pub first_page_load_priority: Option<u32>, pub first_page_load_priority: Option<u32>,
/// Route-matching regexes for priority routes. /// 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 /// Priority-route boost as an integer percentage (e.g. `150` for a 1.5x boost), or
/// `None` to use the default. /// `None` to use the default.
pub priority_boost_percent: Option<u32>, pub priority_boost_percent: Option<u32>,
...@@ -1206,33 +1211,35 @@ pub struct TurbopackChunking { ...@@ -1206,33 +1211,35 @@ pub struct TurbopackChunking {
impl TurbopackChunking { impl TurbopackChunking {
/// Compute the [`EntryHeuristics`] for a route `pathname` by matching it against the configured /// 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 { pub fn entry_heuristics_for(&self, pathname: &str) -> EntryHeuristics {
let high_priority = self let clusters = self
.priority_routes .clusters
.iter() .iter()
.filter(|regex| regex.as_regex_str().is_none()) .enumerate()
.any(|regex| regex.is_match(pathname)) .filter(|(_, regexes)| regexes.is_match(pathname))
|| regex::RegexSet::new( .map(|(index, _)| index as u16)
self.priority_routes .collect();
.iter() let high_priority = self.priority_routes.is_match(pathname);
.filter_map(|regex| regex.as_regex_str()), EntryHeuristics {
) clusters,
.is_ok_and(|set| set.is_match(pathname)); high_priority,
EntryHeuristics { high_priority } }
} }
} }
/// Compile a list of route-matching [`RegexComponents`] into [`EsRegex`]es. /// Compile a list of route-matching [`RegexComponents`] into an [`EsRegexSet`], which builds the
fn parse_route_regexes(patterns: &[RegexComponents]) -> Result<Vec<EsRegex>> { /// combined [`regex::RegexSet`] up front so that matching a route doesn't have to.
patterns fn parse_route_regexes(patterns: &[RegexComponents]) -> Result<EsRegexSet> {
let regexes = patterns
.iter() .iter()
.cloned() .cloned()
.map(|pattern| { .map(|pattern| {
EsRegex::try_from(pattern) EsRegex::try_from(pattern)
.context("Invalid route pattern in `experimental.turbopackChunking`") .context("Invalid route pattern in `experimental.turbopackChunking`")
}) })
.collect() .collect::<Result<Vec<_>>>()?;
Ok(EsRegexSet::new(regexes))
} }
/// Resolve `experimental.cssChunking` to the [`StyleGroupsAlgorithm`] Turbopack should use. /// Resolve `experimental.cssChunking` to the [`StyleGroupsAlgorithm`] Turbopack should use.
...@@ -2165,12 +2172,19 @@ impl NextConfig { ...@@ -2165,12 +2172,19 @@ impl NextConfig {
#[turbo_tasks::function] #[turbo_tasks::function]
pub fn turbopack_chunking(&self) -> Result<Vc<TurbopackChunking>> { pub fn turbopack_chunking(&self) -> Result<Vc<TurbopackChunking>> {
let config = self.experimental.turbopack_chunking.as_ref(); 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( let priority_routes = parse_route_regexes(
config config
.and_then(|c| c.priority_routes.as_deref()) .and_then(|c| c.priority_routes.as_deref())
.unwrap_or_default(), .unwrap_or_default(),
)?; )?;
Ok(TurbopackChunking { Ok(TurbopackChunking {
clusters,
first_page_load_priority: config first_page_load_priority: config
.and_then(|c| c.first_page_load_priority) .and_then(|c| c.first_page_load_priority)
.map(|priority| (priority.clamp(0.0, 1.0) * 100.0).round() as u32), .map(|priority| (priority.clamp(0.0, 1.0) * 100.0).round() as u32),
......
...@@ -1050,6 +1050,9 @@ function bindingToApi( ...@@ -1050,6 +1050,9 @@ function bindingToApi(
...nextConfigSerializable.experimental, ...nextConfigSerializable.experimental,
turbopackChunking: { turbopackChunking: {
...chunkingConfig, ...chunkingConfig,
clusters: chunkingConfig.clusters?.map((cluster: RegExp[]) =>
cluster.map(regexComponents)
),
priorityRoutes: chunkingConfig.priorityRoutes?.map(regexComponents), priorityRoutes: chunkingConfig.priorityRoutes?.map(regexComponents),
}, },
} }
......
...@@ -396,6 +396,7 @@ export const experimentalSchema = { ...@@ -396,6 +396,7 @@ export const experimentalSchema = {
turbopackSharedRuntime: z.boolean().optional(), turbopackSharedRuntime: z.boolean().optional(),
turbopackChunking: z turbopackChunking: z
.object({ .object({
clusters: z.array(z.array(z.instanceof(RegExp))).optional(),
firstPageLoadPriority: z.number().min(0).max(1).optional(), firstPageLoadPriority: z.number().min(0).max(1).optional(),
priorityRoutes: z.array(z.instanceof(RegExp)).optional(), priorityRoutes: z.array(z.instanceof(RegExp)).optional(),
priorityBoost: z.number().min(1).optional(), priorityBoost: z.number().min(1).optional(),
......
...@@ -805,6 +805,19 @@ export interface ExperimentalConfig { ...@@ -805,6 +805,19 @@ export interface ExperimentalConfig {
* making chunk merging decisions and the raw size thresholds it uses. * making chunk merging decisions and the raw size thresholds it uses.
*/ */
turbopackChunking?: { 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 * 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 * merging chunks for a signal page load higher. If you don't know a good
......
...@@ -161,6 +161,89 @@ impl EsRegex { ...@@ -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> { pub struct Captures<'h> {
delegate: CapturesImpl<'h>, delegate: CapturesImpl<'h>,
} }
...@@ -216,7 +299,75 @@ impl<'h> Iterator for Captures<'h> { ...@@ -216,7 +299,75 @@ impl<'h> Iterator for Captures<'h> {
#[cfg(test)] #[cfg(test)]
mod tests { 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] #[test]
fn round_trip_bincode() { fn round_trip_bincode() {
......
...@@ -97,8 +97,9 @@ pub struct ChunkGroupInfo { ...@@ -97,8 +97,9 @@ pub struct ChunkGroupInfo {
pub chunking_heuristics: ChunkingHeuristicsInfo, pub chunking_heuristics: ChunkingHeuristicsInfo,
} }
/// Chunking heuristics computed by [`compute_chunk_group_info`]. `priority_routes` is a set of /// Chunking heuristics computed by [`compute_chunk_group_info`]. `clusters` is indexed by
/// chunk-group indices (same indexing as [`ChunkGroupInfo::chunk_groups`]). /// chunk-group index (same length and order as [`ChunkGroupInfo::chunk_groups`]); `priority_routes`
/// is a set of those indices.
#[derive( #[derive(
Debug, Debug,
Default, Default,
...@@ -112,6 +113,12 @@ pub struct ChunkGroupInfo { ...@@ -112,6 +113,12 @@ pub struct ChunkGroupInfo {
Decode, Decode,
)] )]
pub struct ChunkingHeuristicsInfo { 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 /// The set of chunk-group indices that belong to a priority route: the priority
/// routes themselves, plus every chunk group they pull in. /// routes themselves, plus every chunk group they pull in.
/// ///
...@@ -155,13 +162,17 @@ impl ChunkGroupInfo { ...@@ -155,13 +162,17 @@ impl ChunkGroupInfo {
#[turbo_tasks::task_input] #[turbo_tasks::task_input]
#[derive(Debug, Default, Clone, Hash, PartialEq, Eq, TraceRawVcs, Encode, Decode)] #[derive(Debug, Default, Clone, Hash, PartialEq, Eq, TraceRawVcs, Encode, Decode)]
pub struct EntryHeuristics { pub struct EntryHeuristics {
/// Cluster indices this route belongs to.
pub clusters: Vec<u16>,
pub high_priority: bool, pub high_priority: bool,
} }
impl EntryHeuristics { 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 { pub fn high_priority() -> Self {
Self { Self {
clusters: Vec::new(),
high_priority: true, high_priority: true,
} }
} }
...@@ -813,9 +824,10 @@ pub async fn compute_chunk_group_info(graph: &ModuleGraph) -> Result<Vc<ChunkGro ...@@ -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 // Resolve per-chunk-group chunking heuristics. Entry
// priority-route flag; other chunk groups inherit it (OR) from their referencing chunk // chunk groups carry their route's clusters / priority-route flag; other chunk groups
// 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 priority_routes = RoaringBitmap::new();
let mut worklist: Vec<usize> = Vec::new(); let mut worklist: Vec<usize> = Vec::new();
...@@ -828,18 +840,24 @@ pub async fn compute_chunk_group_info(graph: &ModuleGraph) -> Result<Vc<ChunkGro ...@@ -828,18 +840,24 @@ pub async fn compute_chunk_group_info(graph: &ModuleGraph) -> Result<Vc<ChunkGro
else { else {
continue; continue;
}; };
if !heuristics.high_priority { if heuristics.clusters.is_empty() && !heuristics.high_priority {
continue; continue;
} }
if let Some(index) = if let Some(index) =
chunk_groups_map.get_index_of(&ChunkGroupKey::Entry(modules.clone())) 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() { 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 { let Some(targets) = inherits_from.get(&(source as u32)) else {
continue; continue;
}; };
...@@ -848,18 +866,29 @@ pub async fn compute_chunk_group_info(graph: &ModuleGraph) -> Result<Vc<ChunkGro ...@@ -848,18 +866,29 @@ pub async fn compute_chunk_group_info(graph: &ModuleGraph) -> Result<Vc<ChunkGro
if target == source { if target == source {
continue; 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); 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); let chunk_group_priority_routes = RoaringBitmapWrapper(priority_routes);
Ok(ChunkGroupInfo { Ok(ChunkGroupInfo {
module_chunk_groups: ResolvedVc::cell(module_chunk_groups), module_chunk_groups: ResolvedVc::cell(module_chunk_groups),
chunk_group_keys: chunk_groups_map.keys().cloned().collect(), chunk_group_keys: chunk_groups_map.keys().cloned().collect(),
chunking_heuristics: ChunkingHeuristicsInfo { chunking_heuristics: ChunkingHeuristicsInfo {
clusters: chunk_group_clusters,
priority_routes: chunk_group_priority_routes, priority_routes: chunk_group_priority_routes,
}, },
chunk_groups: chunk_groups_map 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