From e9c301bcbe42bd5c34d781b79b4c233eaf811587 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Thu, 13 Apr 2023 19:29:18 +0200
Subject: [PATCH] document the worker/memory tradeoff

---
 README.md            | 29 +++++++++++++++++++++++++++++
 src/nix-eval-jobs.cc | 12 +++++++-----
 2 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index bf65700..17e521f 100644
--- a/README.md
+++ b/README.md
@@ -91,3 +91,32 @@ latest release branch.
 
 - [colmena](https://github.com/zhaofengli/colmena) -  A simple, stateless NixOS deployment tool
 - [robotnix](https://github.com/danielfullmer/robotnix) -  Build Android (AOSP) using Nix, used in their [CI](https://github.com/danielfullmer/robotnix/blob/38b80700ee4265c306dcfdcce45056e32ab2973f/.github/workflows/instantiate.yml#L18)
+
+## FAQ
+
+### nix-eval-jobs consumes too much memory / is too slow
+
+By default, nix-eval-jobs spawns as many worker processes as there are
+hardware threads in the system and limits the memory usage for each worker to
+4GB.
+
+However, keep in mind that each worker process may need to re-evaluate shared
+dependencies of the attributes, which can introduce some overhead for each
+evaluation or cause workers to exceed their memory limit. If you encounter
+these situations, you can tune the following options:
+
+`--workers`: This option allows you to set the number of evaluation workers that
+nix-eval-jobs should spawn. You can increase or decrease this number to
+optimize the evaluation speed and memory usage. For example, if you have a
+system with many CPU cores but limited memory, you may want to reduce the
+number of workers to avoid exceeding the memory limit.
+
+`--max-memory-size`: This option allows you to adjust the memory limit for each
+worker process. By default, it's set to 4GiB, but you can increase or decrease
+this value as needed. For example, if you have a system with a lot of memory
+and want to speed up the evaluation, you may want to increase the memory limit
+to allow workers to cache more data in memory before getting restarted by
+nix-eval-jobs.
+
+Overall, tuning these options can help you optimize the performance and memory
+usage of nix-eval-jobs to better fit your system and evaluation needs.
diff --git a/src/nix-eval-jobs.cc b/src/nix-eval-jobs.cc
index b9c5a19..49aca05 100644
--- a/src/nix-eval-jobs.cc
+++ b/src/nix-eval-jobs.cc
@@ -90,11 +90,13 @@ struct MyArgs : MixEvalArgs, MixCommonArgs {
              .labels = {"workers"},
              .handler = {[=](std::string s) { nrWorkers = std::stoi(s); }}});
 
-        addFlag({.longName = "max-memory-size",
-                 .description = "maximum evaluation memory size",
-                 .labels = {"size"},
-                 .handler = {
-                     [=](std::string s) { maxMemorySize = std::stoi(s); }}});
+        addFlag(
+            {.longName = "max-memory-size",
+             .description =
+                 "maximum evaluation memory size (4GiB per worker by default)",
+             .labels = {"size"},
+             .handler = {
+                 [=](std::string s) { maxMemorySize = std::stoi(s); }}});
 
         addFlag({.longName = "flake",
                  .description = "build a flake",