[llvm] r312667 - [docs] Add a note on iteration of unordered containers to coding standards

[Mandeep Singh Grang via llvm-commits]

Author: mgrang
Date: Wed Sep  6 13:19:10 2017
New Revision: 312667

URL: http://llvm.org/viewvc/llvm-project?rev=312667&view=rev
Log:
[docs] Add a note on iteration of unordered containers to coding standards

Summary: Beware of non-determinism due to ordering of pointers

Reviewers: dblaikie, dexonsmith

Reviewed By: dblaikie

Subscribers: llvm-commits

Differential Revision: https://reviews.llvm.org/D37525

Modified:
    llvm/trunk/docs/CodingStandards.rst

Modified: llvm/trunk/docs/CodingStandards.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CodingStandards.rst?rev=312667&r1=312666&r2=312667&view=diff
==============================================================================
--- llvm/trunk/docs/CodingStandards.rst (original)
+++ llvm/trunk/docs/CodingStandards.rst Wed Sep  6 13:19:10 2017
@@ -811,6 +811,21 @@ As a rule of thumb, use ``auto &`` unles
   for (const auto *Ptr : Container) { observe(*Ptr); }
   for (auto *Ptr : Container) { Ptr->change(); }
 
+Beware of non-determinism due to ordering of pointers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In general, there is no relative ordering among pointers. As a result,
+when unordered containers like sets and maps are used with pointer keys
+the iteration order is undefined. Hence, iterating such containers may
+result in non-deterministic code generation. While the generated code
+might not necessarily be "wrong code", this non-determinism might result
+in unexpected runtime crashes or simply hard to reproduce bugs on the
+customer side making it harder to debug and fix.
+
+As a rule of thumb, in case an ordered result is expected, remember to
+sort an unordered container before iteration. Or use ordered containers
+like vector/MapVector/SetVector if you want to iterate pointer keys.
+
 Style Issues
 ============