From cba252886b651c4ae3f990a509b37b0c39a87081 Mon Sep 17 00:00:00 2001
From: Simon Jakobi <simon.jakobi@gmail.com>
Date: Sun, 2 Nov 2025 00:08:02 +0100
Subject: [PATCH] readme: Add section with performance tips

---
 README.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/README.md b/README.md
index 5caec826..9895e43e 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,44 @@ performance critical use, both in terms of large data quantities and high speed.
 The declared cost of each operation is either worst-case or amortized, but
 remains valid even if structures are shared.
 
+### How to get the best performance out of this package
+
+#### Enable hardware support for `popCount`
+
+This package makes heavy use of the `popCount` function. To allow GHC to use the
+`popcnt` instruction available on modern x86 and x86-64 platforms, enable GHC's
+`-msse4.2` option. Since code from `unordered-containers` may spread to other
+packages due to inlining and specialization, it's best to use this setting for
+all packages in your project:
+
+In your `cabal.project`:
+
+```
+package *
+  ghc-options: -msse4.2
+```
+
+In your `stack.yaml`:
+
+```
+ghc-options:
+  "$everything": -msse4.2
+```
+
+#### Make sure that your keys have a good hash distribution
+
+TODO (few collisions, good HAMT shape)
+
+#### Make sure that your keys' `hash` method is fast
+
+TODO
+
+#### Make sure that your keys' `(==)` method is fast
+
+TODO (pointer equality!)
+
+### More documentation
+
 For background information and design considerations on this package see the
 [Developer Guide](docs/developer-guide.md).