PaperMC / PaperMC/Paper

Flush memory caches to disk when server is paused (empty-server pause)

Open
#13,864 2 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

scope: configuration status: accepted
Dominant language
Java
Stars
12.7k
Forks
3.5k
Avg merge
3d 13h
Merged PRs (30d)
11

Description

Is your feature request related to a problem?

When pause-empty-server triggers and the server enters a paused state, the JVM heap still holds large in-memory caches; I'm assuming loaded chunks, block entity data, lighting engine state, etc; even though no players are online and no ticking is occurring. On memory constrained hosts (home servers, low-RAM VPS, shared machines running multiple services, or even a server provider), the paused server still occupies its full working-set RAM for hours at a time.

Example:
[17:26:56 INFO]: Server empty for 60 seconds, pausing

At this point the server is doing nothing, but its heap remains fully populated.

Describe the solution you'd like.

When the server goes into a paused state, Paper should aggressively flush and unload its in-memory caches to reduce RAM usage while idle.

  1. Flush all unloaded dirty chunks/region files to disk (which save-all already does)
  2. Unload the chunk cache and drop references, freeing heap
  3. Flush and release block entity caches
  4. Hint the GC to reclaim freed memory

On resume, chunks and entities would lazy-load back through the existing load-on-demand path.

This should probably be opt-in via a new config key.

This is not a request to serialize the JVM heap to disk. The ask is purely to invoke existing save-and-unload codepaths at pause time rather than lazily.

Describe alternatives you've considered.

CRIU process checkpointing can checkpoint and restore a Linux process including heap, but it requires elevated privileges, is linux only, and is very fragile with JVM threads.

Other

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the pause-empty-server path and compare its behavior with the existing save-all, chunk-unload, and load-on-demand paths. Done should be an opt-in pause-time mechanism that flushes and releases the requested in-memory state, then allows it to load again on resume; the issue names no files or tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
performance
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.