Forkless operations · Valkey

Forkless operations

Description

Valkey uses the fork() system call for several background operations, including saving the dataset to disk and fully synchronizing replicas. Fork-based operations have been part of Valkey since its earliest days and are a simple, proven approach. They also come with tradeoffs that can matter for some workloads. One of them is memory usage: the forked child process shares memory with Valkey through copy-on-write, so memory usage can grow while the child is running. In extreme cases, where writes are spread across much of the dataset during that time, memory usage can grow by up to 2x.

Valkey 9.2 introduces forkless save and forkless full sync, which perform these two operations without calling fork(). Valkey takes the snapshot inside the running process, which keeps memory usage steadier and more predictable while the operation runs. In this case, the tradeoff is that writes can briefly wait and latency can be slightly higher during the operation, as discussed later in Impact on clients.

It is important to note that forkless is not yet a full replacement for fork(). In some situations, Valkey falls back to a fork-based save or full sync even when it is configured to prefer forkless operations. When using forkless, it is highly encouraged to plan the configuration in a way that avoids these fallbacks, and to take into account that other operations, such as AOF rewrite and atomic slot migration, still use fork(). This page describes how to plan for forkless operations.

Enabling forkless operations

Forkless operations are disabled by default. Two configuration parameters control them:

When Valkey uses fork instead

As the name suggests, prefer-forkless does not guarantee that every save and full sync is forkless. Before each operation, Valkey checks whether a forkless operation is possible, and uses fork() when it is not. Each fallback is logged to the server log, and counted in the debug section of INFO.

Valkey uses fork() for saves when:

For full syncs, the conditions above apply, and Valkey additionally uses fork() when:

Events that cancel forkless operations

Some events that do not affect a fork-based save or full sync cancel a forkless one:

When a full sync is cancelled, the replica reconnects and starts a new full sync. When a save is cancelled, automatic saves configured with save are retried later, and a save started with BGSAVE must be started again.

Monitoring forkless operations

The persistence section of INFO shows which method Valkey uses:

The server log records the method of each full sync, and the reason for each fallback. For debugging, the debug section of INFO also includes the forkless_fallbacks_* counters described in When Valkey uses fork instead.

Impact on clients

A forkless operation runs while Valkey keeps serving clients, so it can affect commands that write to the dataset:

Workloads with very large keys that receive frequent writes are the most affected. Splitting very large collections into smaller keys reduces both the chance that a write waits and how long it waits.

For module developers

A module declares that it supports forkless operations by setting the VALKEYMODULE_OPTIONS_HANDLE_FORKLESS option with ValkeyModule_SetModuleOptions. Forkless operations are used only when every loaded module sets this option. A module that does not set it keeps working as before, and Valkey uses fork() for saves and full syncs while that module is loaded, even when forkless-policy is set to prefer-forkless.

By setting the option, a module agrees to the following:

A module cannot be loaded while a forkless save or full sync is running. MODULE LOAD returns an error, and the module can be loaded after the operation finishes.