docs: Add a note on concurrency and races (#6950)

akx · adamchainz · web-flow · commit b1004a47334a · 2022-04-24T23:16:18.000+01:00
Refs #5181 Co-authored-by: Adam Johnson <me@adamj.eu>
diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md
@@ -106,6 +106,12 @@ If you need to use a cache other than `'default'`, you can do so by creating a c
 
 You'll need to remember to also set your custom throttle class in the `'DEFAULT_THROTTLE_CLASSES'` settings key, or using the `throttle_classes` view attribute.
 
+## A note on concurrency
+
+The built-in throttle implementations are open to [race conditions][race], so under high concurrency they may allow a few extra requests through.
+
+If your project relies on guaranteeing the number of requests during concurrent requests, you will need to implement your own throttle class. See [issue #5181][gh5181] for more details.
+
 ---
 
 # API Reference
@@ -214,3 +220,5 @@ The following is an example of a rate throttle, that will randomly throttle 1 in
 [identifying-clients]: http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#Multiple_Proxies_in_front_of_the_cluster
 [cache-setting]: https://docs.djangoproject.com/en/stable/ref/settings/#caches
 [cache-docs]: https://docs.djangoproject.com/en/stable/topics/cache/#setting-up-the-cache
+[gh5181]: https://github.com/encode/django-rest-framework/issues/5181
+[race]: https://en.wikipedia.org/wiki/Race_condition#Data_race
