cgroup-rts-threads: A container-/cgroup-aware substitute for the GHC RTS `-N` flag

[ concurrency, library, mpl ] [ Propose Tags ]

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

[Skip to Readme]


Maintainer's Corner

For package maintainers and hackage trustees


  • No Candidates
Versions [RSS],,,
Change log
Dependencies base (>=4.13 && <5), directory (>= && <1.4), megaparsec (>=8 && <10), path (>=0.7 && <0.10), text [details]
License MPL-2.0
Author Connor James
Category Concurrency
Home page
Bug tracker
Source repo head: git clone
Uploaded by cnr at 2022-07-02T18:17:32Z
Distributions NixOS:
Downloads 418 total (26 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for cgroup-rts-threads-

[back to package description]


Hackage tests

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.


  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
  1. In your program's main function, call initRTSThreads:
module Main (main) where

import Control.Concurrent.CGroup (initRTSThreads)

main :: IO ()
main = do


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.