Skip to content

perf(lua): replay way_function and node_function from a memo; native MercatorArea and MinZoomByArea - #993

Open
dktue wants to merge 10 commits into
systemed:masterfrom
dktue:perf/planet-3min-01-lua-memo
Open

dktue wants to merge 10 commits into
systemed:masterfrom
dktue:perf/planet-3min-01-lua-memo

Conversation

@dktue

@dktue dktue commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Gain: planet (96 threads) about -21% wall for this PR alone, compounded over its rounds: native MercatorArea 9:07 -> 8:53, memo v3 8:51 -> 8:05 (user CPU -16%), memo node cap 8:05 -> 7:57, memo values 7:51 -> 7:42, then -4.5 s, -6.6 s, -3.8 s, -4.5 s in later rounds. way_function replayed for ~1.17 of 1.22 billion ways, node_function for ~211 million nodes. Memory: memo trees of at most 2^18 nodes per thread.

Series total: planet (in memory, 96 threads) about 9:50 for perf/shared-pieces + #989/#990 (Nov 8; glibc, Boost 1.74, GCC 11, Lua 5.3) -> 3:08 for the last commit (Nov 14; jemalloc with THP settings, Boost 1.83, GCC 14, Lua 5.4), -68%. Compounding the per-round A/B measurements, the code of this series accounts for about -63%; the newer toolchain (about -8%) and jemalloc (about -8%) for the rest.

Stacked on perf/shared-pieces (#1001) and commit 00 of this series (perf/planet-3min-00-store-finalize-pmtiles-close: #989 and #990 adapted to that base, no PR of its own), so the diff of this PR on GitHub also shows the commits below it; review the last commit. The whole series is on perf/planet-3min.

What

Most ways run exactly the same Lua as many ways before them: the same tag reads give the same results and the same calls. With way_memo = true in the profile, tilemaker records, per thread, a tree of what way_function read (Find, Holds, IsClosed, NextRelation, ...) and which tilemaker functions it then called (Layer, Attribute..., MinZoom), and replays the calls for a way whose reads give the same results, without entering Lua. Ways with anything else (geometry queries, Id, relation tags, globals) run through Lua as before.

  • Opt-in declarations, documented in CONFIGURATION.md: way_memo_values (tags only tested for being empty and copied, e.g. name; replayed with the way's own value, optionally its length), way_memo_area (MercatorArea only compared with given numbers), way_memo_relations (NextRelation only tested, relation tags only via FindInRelation), and node_memo* for node_function. Multipolygon relations get a record of their own.
  • The walk reads the way's tags once into small key slots (memo_keys.h); TagMap builds its hash only when Lua asks for a tag.
  • Bounded: 2^18 nodes per thread, at most 256 children per node, full trees are compacted; a value-heavy branch (a name, a house number) falls back to Lua.
  • New Lua functions MercatorArea() (planar Web Mercator area) and MinZoomByArea(limit, thresholds): the minimum-zoom-by-area rule worked out in C++, so that way_function stays replayable.
  • The bundled OpenMapTiles profile uses all of this, and keeps tilemaker's functions in locals.
  • The Makefile compiles as C++17, like CMake since build(cmake): use C++17 unless MLT is enabled; document C++ standards #953 (memo_keys.h uses std::string_view). Works with Lua 5.1/LuaJIT too (lua_objlen where luaL_len is missing).

Output

This is the only commit of the series that changes the output, through the bundled profile's area: the old profile computed MercatorArea() in Lua as Area() / cos^2(latitude of the centroid), the native function is the planar area on the Web Mercator plane. Areas close to a minimum-zoom threshold can fall on the other side of it, so some landuse, water, building and bridge polygons appear one zoom earlier or later. The memo itself replays exactly what Lua would do (it records only deterministic reads; anything it cannot record runs through Lua), so with a profile that doesn't use the new functions the output is unchanged. Every later commit keeps the output of this one.

Verification

  • Builds (CMake and Makefile, GCC 13, Boost 1.83, Lua 5.4) and passes the unit tests (make test, 18 suites, 0 failures). CI passes on Linux (Makefile with LuaJIT, CMake), macOS and Windows; locally also checked with LuaJIT 2.1 and Boost 1.87 headers.
  • Output on four extracts (Lake Huron, Canberra, Patagonia, Canary Islands; 4 threads, bundled profile, no shapefiles): different from the previous commit, as expected; byte-identical to the final commit of the series (sha256 Huron 40bba7e1, Canberra d916213b, Patagonia 6a1b4ca3, Canary 69fc28eb).
  • Finland (16 threads): byte-identical to the final commit (sha256 870216f1). Wall 45.7 s -> 34.8 s against the previous commit (WSL, 16 threads).
  • What changes (pmdiff, previous commit vs this one): Finland 2,770 of 596,882 tiles differ (0.46%): z5-z10 16-47% of the few low-zoom tiles, z11 6.3%, z12 1.6%, z13 1.1%, z14 30 tiles (0.01%). Patagonia 104 of 322,441, Canary Islands 78 of 5,428, Canberra 19 of 3,654, Lake Huron none. Feature counts per layer change only by polygons near a minimum-zoom threshold (landcover, landuse, water, building); no polygon that was valid became invalid (in the decoded sample of differing tiles). The 30 z14 tiles in Finland come from tilemaker's clip cache, not from wrong geometry: a polygon whose minimum zoom moved from 14 to 13 now has a cached z13 clip, and its z14 tile is cut from that instead of from the whole polygon. At the last zoom the clip box is widened to the ends of every segment that crosses the tile border, which depends on the input, so the parts outside the tile differ (in the traced polygon by 71 tile units = 8.9 px, all beyond the tile edge); inside the tile both are the same. With the clip cache switched off for the test, this commit changes no z14 tile at all; and the memo with the old Lua area function gives a file byte-identical to the previous commit.
  • LuaJIT 2.1 (Makefile build): with the memo on and off, byte-identical output on the four extracts.

🤖 Generated with Claude Code

dktue and others added 6 commits November 7, 2026 14:48
systemed#983 (combined snapshot)

For testing only, not for merging. One commit with the combined tree that
built the planet in 14 min 03 s (in memory, 96 threads) for systemed#977:

master 2789651 + systemed#933, systemed#959, systemed#966, systemed#968, systemed#970, systemed#971, systemed#972, systemed#973, systemed#974, systemed#975,
systemed#976, systemed#978, systemed#979 (open performance PRs), systemed#981 (deterministic tile content),
systemed#942 (deterministic POI order) and systemed#983 (ordered .pmtiles/.mbtiles writer,
64 MB per thread). Each change is reviewed in its own PR.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Same change as systemed#986. With it, the sort before the tile phase takes ~13 s
instead of 2-5 minutes at 96 threads, so planet times no longer vary by
minutes between runs (14:12 / 14:08 in memory at 96 threads).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
end() woke every thread waiting in waitForRoom() after each batch it wrote,
although most of the time the held tiles were still over the limit. At 96
threads that meant dozens of threads waking, finding no room and sleeping
again for every batch: 125M context switches and 7,700 s of system time on
the planet. Now they are only woken once the held tiles are back under the
limit. Planet in memory, 96 threads, all open performance PRs:
14:05 -> 12:45 (-9.5%), system time 7,708 -> 2,868 s, context switches
125M -> 35M. Output unchanged (same batches, same order).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Every tile batch that needs a large polygon copied it from the store and
clipped it from scratch, at every zoom. Now polygons with at least 10,000
points are clipped once per z8 tile, before the tiles are written (all
threads, largest polygon first), and tiles below clip from that piece.
After that the pieces are only read, so there is no lock while tiles are
written; a z6 tile's pieces are freed once no tile in it is still to come.

A piece only depends on the polygon and the z8 tile, so the output stays
the same for any thread count. A piece whose clip needed the repair path is
not used: once one came out empty and a lake vanished from all tiles below.

Planet in memory, 96 threads, all open performance PRs + systemed#983's wake-up
fix: 12:45 -> 10:55 (-14.4%), user CPU -27%, peak RSS +7.5 GB.
Germany byte-identical at 32 and 8 threads; planet sample: same feature
counts, area within 0.003%.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
At 96 threads the one thread that writes batches in order became the
bottleneck of the tile phase: busy 260 s of a 323 s tile phase, with the
others waiting for room for 5,100 thread-seconds. Writing the bytes was
more than half of its work (ofstream::write, and a tellp() per tile).

- The writer keeps its own tile data offset instead of calling tellp() for
  every tile, and the stream gets a 4 MB buffer.
- OrderedBatches can take a second step, flushItem: also in batch order and
  one thread at a time, but run by whichever thread is free, so it doesn't
  hold up the first step. PMTiles places tiles (offset, repeated tiny tiles,
  index) in the first step and writes their bytes in the second.

The file is byte-identical. Planet in memory, 96 threads, all open
performance PRs: 10:41 -> 9:54 (-7.3%); tile phase 323 -> 245 s, threads
busy 76 -> 94 of 96 on average. New test: the second step runs in order,
never twice at once, and always after the first (also clean under TSan).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The pieces used to be computed in a pass of their own before the tile phase,
which ended with one thread on the largest piece (~6 s on the planet) while
all others waited. Now the tile threads compute them before their first
tile, largest polygon first, and go on to tiles once no piece is left to
start; a tile that needs a piece still being computed waits for just that
one (shared_future). A piece is known before the tiles start, so the map
doesn't change and tiles look pieces up without a lock as before.

Output byte-identical (Germany at 32 and 8 threads).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- polylabel.h: rename edgeDistBound's parameter `near` to `nearCell`.
  tile_data.h includes boost/asio since systemed#972, which pulls in windows.h on
  Windows, and windows.h defines `near` as an empty macro.
- test/shp_mem_tiles.test.cpp (systemed#979): include shp_mem_tiles.h before
  minunit.h. minunit.h sets _POSIX_C_SOURCE, which on macOS hides ip_mreq,
  and boost/asio (through tile_data.h) needs it.

Renames and include order only; output unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@dktue
dktue force-pushed the perf/planet-3min-01-lua-memo branch from f2f670e to 160e4f9 Compare November 15, 2026 13:38
…uctors have run (macOS)

On macOS the main thread's thread-local destructors run after the static
destructors. Two of them touched objects that were already gone, and the
unit tests aborted at exit with "mutex lock failed: Invalid argument":

- mmap_allocator.cpp: thread_regions_t's destructor locks
  mmap_allocator_mutex and appends to free_mmap_files /
  free_mmap_shm_regions. These three are now allocated once and never
  destroyed. ~mmap_dir_t clears free_mmap_files first, so --store files
  are still released and deleted as before (that list used to be destroyed
  just before mmap_dir).
- LeasedStore (tile_data.cpp): a thread gives its store leases back to
  the TileDataSource when it ends; the main thread does that at exit, after
  the sources (locals of main(), or of a unit test such as
  test_shp_mem_tiles) are destroyed, locking a destroyed storeMutex. The
  sources are now registered while alive (an immortal registry), and a
  lease goes back only to a live source. Sources are also numbered: a new
  source at the address of a destroyed one no longer gets that one's
  lease.

No change in output.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@dktue
dktue force-pushed the perf/planet-3min-01-lua-memo branch from 160e4f9 to b56bf1c Compare November 15, 2026 15:21
cldellow added a commit to cldellow/tilemaker that referenced this pull request Nov 15, 2026
…s-b36pcl

dktue's 3-minute planet series (systemed#993–systemed#1000) on relslow-patched; Lua 5.4 and jemalloc in the image
@cldellow

Copy link
Copy Markdown
Contributor

I love (what I understand to be) the direction of this work: let someone author flexible profiles in user-friendly Lua while also avoiding the runtime cost where possible.

I'm wrapping my head around the work here, so apologies if some of these questions are dumb! Some of these are more just to understand the space vs a suggestion for a change in the current PR.

  1. Could _G.Find, _G.Holds, etc be initialized earlier by tilemaker?

I think this would avoid the user having to author an init_function in order to do the local declaration speedup trick.

I think if

luaState.dofile(luaFile.c_str());
was moved after the function registrations, that might suffice.

  1. Could the local Find, Holds, Layer, ... = _G.Find, _G.Holds, _G.Layer trick be applied automatically by tilemaker?

Especially if (1) is possible, this seems like a mechanical transformation that would benefit anyone who uses tilemaker.

Could tilemaker just decree that it will preprocess your profile to add this line at the top of every file? Any runtime errors that quote lua file line numbers would need to have their line numbers decreased by 1 to still point to the right line in the user's profile, but I think that'd be manageable.

  1. Would it be possible to also support Intersects?

If I understand correctly, Intersects could fit the proposed memo system well because its range is low cardinality (just 2 options: true or false).

Could it be added? I think https://github.com/hikeratlas/basemap/blob/main/slices/buildings.lua would trivially be ready to use memo if Intersects was supported.

For completeness, I think maybe it'd make sense to include: Intersects(layer), CoveredBy(layer), IsMultiPolygon(), HasTags() and OsmType().

  1. Would it be possible to opt-in other state to the memo system?

My ways profile isn't currently a candidate for the memo system.

One of the issues is its use of Wikidata IDs (high cardinality) and the qrank module: https://github.com/hikeratlas/basemap/blob/5210191627cbe185c0477298117c04f0746a7fe4/slices/ways.lua#L163

That module is a SQLite database that maps a Wikidata ID to a popularity score. We then branch based on whether the popularity score is above or below a threshold of 1000.

Conceptually, this feels very similar to the problem solved by way_memo_area = { 1000, 5000 }.

I wonder if there's some way to unlock this? For example, if tilemaker offered a MakeMemoizable function:

local get_route_and_highway = MakeMemoizable(function()
  local on_route = false
  local highway = ''
  while true do
    local rel = NextRelation()
    if not rel then break end
    local route = FindInRelation('route')
    local network = FindInRelation('network')

    local wikidata = FindInRelation('wikidata')
    local rank = qrank.get(wikidata)

    if route == 'road' and rank > 1000 then
      highway = 'motorway'
    end
    if route == 'hiking' or route == 'foot' then on_route = true end
  end
return on_route, highway
end)

function way_function():
  local on_route, highway = get_route_and_highway()
  ...
end

tilemaker would still have to invoke the Lua interpreter, but now its scope is just for get_route_and_highway, and only when a branch needs it.

Maybe this wouldn't provide enough savings? I don't know if the benefit of memoizing is avoiding the Lua interpreter entirely, or if you still get a savings if you just reduce the amount of Lua code being interpeted, and the number of Lua -> tilemaker transitions for the tilemaker functions.

Aside: MakeMemoizable is a poor name, since we're not actually making that function itself memoizable, we're making everything around it memoizable. Still, maybe good enough for the discussion.

  1. Could certain patterns be detected/supported automatically?

This is sort of a thought experiment. Could the config knobs for way_memo, way_memo_values, way_memo_area and way_memo_relations (and node_memo*) be removed entirely?

They're quite powerful, but using them correctly seems a bit fraught. (I pause here to note that I'm a hypocrite: I added way_keys and node_keys, which have similar footguns.)

tilemaker controls the environment and sees all the lua profiles. In theory, I think a tilemaker could do static analysis of any given profile to decide whether its usage is safe for memoization or not.

Such analysis would allow more things to be automatically supported, e.g. in:

Attribute("osm_id", Id())

it could understand that Id() is a pure function and is just being forwarded.

In some cases, the analysis would be uncertain, and tilemaker would have to err on the side of caution and decline to memoize, e.g. if a user's profile imports a native library whose code isn't visible to tilemaker. That could be communicated to the user, who might then be able to apply a workaround to hint to tilemaker that the thing is truly safe to memoize.

On the one hand, the static analysis approach feels quite ambitious. On the other hand, if it could deliver speedups with no effort from the user, while also avoiding the risk of the user introducing errors through misconfiguration, I wouldn't mind throwing Claude tokens at building and testing it.

@dktue

dktue commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

Thanks, these are good questions, not dumb ones. Short answers, in your order:

1. Registering the functions before the profile is loaded. Yes. Today dofile runs first and the functions are registered after it (osm_lua_processing.cpp, luaState.dofile and then luaState["Find"] = &rawFind …), which is why the bundled profile takes its locals in init_function. Registering first would let a profile write local Find, Holds, Layer = Find, Holds, Layer at the top. It is a small change of its own; I'd keep it out of this PR and send it separately. It is independent of the memo: locals only make Lua's own lookups cheaper.

2. Adding the locals automatically. Possible, but I'd rather not rewrite the user's source: besides the line numbers, a profile may already define a local or global with one of those names. With (1), it is one line a profile can opt into, and the bundled profile would show it.

3. Intersects and friends. Today Intersects, CoveredBy and the other geometry queries send the way through Lua (the memo marks it "Lua only"). They could become reads like IsClosed: the result is true or false, so the memo can tell ways apart by it. The cost is that tilemaker then has to run the query for every way that reaches that branch, before it knows which record applies, but that is no more than the Lua run does now. IsMultiPolygon() and OsmType() are cheap and would fit the same way. Not in this PR, but a natural next step, and your buildings slice would be a good test for it.

4. Opting other state in. As I read it, your MakeMemoizable function is something the memo treats like MercatorArea with way_memo_area: an opaque value that it can't look into but whose result it can branch on. tilemaker would still run that function in Lua for every way, but if its results are few (on_route, highway), the rest of way_function could be replayed. How much that saves depends on how much of the cost is in that function: the memo pays off mostly because it skips the Lua call entirely, and with qrank's SQLite lookups in the function, those would stay. Worth a try with a real profile; I'd want to measure it on yours before designing the API.

5. No knobs. Agreed that the knobs are easy to get wrong. Part of the checking is already there at run time: calls the memo can't replay (geometry queries, Id(), relation tags without way_memo_relations …) send the way through Lua, and if a replayed way reads differently from what was recorded, the memo switches itself off for that thread with a message. What it can't see is state outside the reads, like a global counter or a module such as qrank. A static check of the profile could catch most of that, and an automatic fallback when it's unsure sounds right. I haven't started on it; if you want to try, the record/replay code is in osm_lua_processing.cpp (memo*), and I'm happy to help.

dktue and others added 2 commits November 16, 2026 13:27
…+ systemed#990)

systemed#989 and systemed#990 adapted to perf/shared-pieces, as the base of this series.

- SortedNodeStore/SortedWayStore::finalize publish the leftover groups
  (groups split between worker batches) from all threads instead of one
  after the other. On the planet that was ~10 s after the ways pass with
  every other thread idle. Same store content. (systemed#989, unchanged)
- PMTiles::close collects the directory entries and cuts them into leaves
  exactly as before, then serializes and compresses the leaves on all
  cores and writes them in order: ~9 s -> 3 s on the planet, byte-identical
  file. (systemed#990; on perf/shared-pieces the two-step writer already holds the
  file, so the leaf writes need no lock and fileMutex goes.)

Planet (in memory, 96 threads): -9 s and -6 s. Output byte-identical to
perf/shared-pieces.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…atorArea

Most ways run exactly the same Lua as many ways before them: the same tag
reads give the same results and the same calls. With `way_memo = true` in
the profile, tilemaker records, per thread, a tree of what way_function
read (Find, Holds, IsClosed, NextRelation, ...) and which tilemaker
functions it then called (Layer, Attribute..., MinZoom), and replays the
calls for a way whose reads give the same results, without entering Lua.
Ways with anything else (geometry queries, Id, relation tags, globals)
run through Lua as before.

- Opt-in declarations, documented in CONFIGURATION.md: way_memo_values
  (tags only tested for being empty and copied, e.g. name; replayed with
  the way's own value, optionally its length), way_memo_area (MercatorArea
  only compared with given numbers), way_memo_relations (NextRelation only
  tested, relation tags only via FindInRelation), and node_memo* for
  node_function. Multipolygon relations get a record of their own.
- The walk reads the way's tags once into small key slots (memo_keys.h);
  TagMap builds its hash only when Lua asks for a tag.
- Bounded: 2^18 nodes per thread, at most 256 children per node, full trees
  are compacted; a value-heavy branch (a name, a house number) falls back
  to Lua.
- New Lua functions MercatorArea() (planar Web Mercator area) and
  MinZoomByArea(limit, thresholds): the minimum-zoom-by-area rule worked
  out in C++, so that way_function stays replayable.
- The bundled OpenMapTiles profile uses all of this, and keeps tilemaker's
  functions in locals.
- The Makefile compiles as C++17, like CMake since systemed#953 (memo_keys.h
  uses std::string_view). Works with Lua 5.1/LuaJIT too (lua_objlen where
  luaL_len is missing).

Output: the only change in this series. The old profile computed
MercatorArea in Lua as Area() / cos^2(latitude of the centroid); the
native function is the planar area on the Web Mercator plane. Areas close
to a minimum-zoom threshold can land on the other side of it, so some
landuse, water and building polygons start one zoom earlier or later.
Everything else is identical; the memo itself does not change the output.

Planet (96 threads): way_function replayed for ~1.17 billion of 1.22
billion ways, node_function for ~211 million nodes; together with the
native area about -21% wall.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants