# cgroup-rts-threads
This library provides a container-/cgroup-aware substitute for GHC's [RTS `-N` flag][rts-n], 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?](#why) section for details.
## Usage
1. Remove `-N` from your executable's `rtsopts`. In `yourproject.cabal`:
```cabal-config
-- 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`:
```haskell
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][cgroup-quota-v1] or [`cpu.max` under cgroups v2][cgroup-quota-v2]) to set a limit on the cpu time a process is allowed to consume.
The GHC threaded RTS offers [a flag, `-N`,][rts-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`][cpuset-commit], 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.
[cpuset-commit]: https://gitlab.haskell.org/ghc/ghc/-/commit/4413828b7c507872c56719fb8920e1c2322830f8
[rts-n]: https://downloads.haskell.org/~ghc/9.0.1/docs/html/users_guide/using-concurrent.html#rts-options-for-smp-parallelism
[cgroup-quota-v1]: https://www.kernel.org/doc/html/latest/scheduler/sched-bwc.html#management
[cgroup-quota-v2]: https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html#cpu-interface-files