A container-/cgroup-aware substitute for the GHC RTS -N flag.

This library provides a container-/cgroup-aware substitute for the GHC RTS `-N` flag. See the README for details.

cgroup-rts-threads

This library provides a container-/cgroup-aware substitute for GHC's RTS -N flag, used to set the number of runtime threads.

Similar to the RTS -N flag, this library considers the number of cpu cores (as reported by GHC.Conc.getNumProcessors) to set this number.

Unlike the RTS -N flag, this library observes the process' cgroup cpu quota to constrain the number of runtime threads, as applicable.

When running outside of a cgroup, or on a platform other than linux, this library matches the behavior of -N.

See the Why? section for details.

Usage

1. Remove -N from your executable's rtsopts. In yourproject.cabal:

-- before
executable my-executable
  ghc-options: -threaded -with-rtsopts=-N

-- after
executable my-executable
  ghc-options: -threaded

2. In your program's main function, call initRTSThreads:

module Main (main) where

import Control.Concurrent.CGroup (initRTSThreads)

main :: IO ()
main = do
  initRTSThreads
  [...]

Why?

It's common in containerized environments to limit cpu consumption of individual containers. There are two primary ways of doing this:

1. Configure a cgroup's cpuset to pin a process to specific cpu cores.
2. Configure a cgroup's cpu quota (cfs under cgroups v1 or cpu.max under cgroups v2) to set a limit on the cpu time a process is allowed to consume.

The GHC threaded RTS offers a flag, -N, that automatically determines the number of threads to use, based on the number of physical processors.

The RTS -N flag, as of GHC 9.0.1, respects the cpuset options when determining the number of threads to use.

Unfortunately, the RTS -N flag does not respect cgroup cpu quotas. This leads to substantially degraded performance when there's a large disparity between a cgroup's cpu quota and the number of physical cpu cores -- a very common scenario in, e.g., production kubernetes clusters.