From d698464caf6b9af72d6af4ebf5b3af2c44ca0e8d Mon Sep 17 00:00:00 2001
From: Sverker Eriksson <sverker@erlang.org>
Date: Mon, 6 Feb 2023 17:19:57 +0100
Subject: [PATCH] stdlib: Improve ets documentation about insert/lookup times

Describe and warn about lots of objects with same keys
in bag and duplicate_bag.
---
 lib/stdlib/doc/src/ets.xml | 38 ++++++++++++++++++++++++++++++--------
 1 file changed, 30 insertions(+), 8 deletions(-)

diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml
index 005fda8089ec..65b4ac76e65d 100644
--- a/lib/stdlib/doc/src/ets.xml
+++ b/lib/stdlib/doc/src/ets.xml
@@ -48,7 +48,26 @@
       A <c>set</c> or <c>ordered_set</c> table can only have one object
       associated with each key. A <c>bag</c> or <c>duplicate_bag</c> table can
       have many objects associated with each key.</p>
-
+    <p>
+      Insert and lookup times in tables of type <c>set</c> are constant,
+      regardless of the table size. For table types <c>bag</c> and
+      <c>duplicate_bag</c> time is proportional to the number of objects with the
+      same key. Even seemingly unrelated keys may inflict linear search to be
+      skipped past while looking for the key of interest (due to hash collision).
+    </p>
+    <warning>
+      <p>
+	For tables of type <c>bag</c> and <c>duplicate_bag</c>, avoid inserting
+	an extensive amount of objects with the same key. It will hurt insert and
+	lookup performance as well as real time characteristics of the runtime
+	environment (hash bucket linear search do not yield).
+      </p>
+    </warning>
+    <p>
+      The <c>ordered_set</c> table type uses a binary search tree. Insert and
+      lookup times are proportional to the logarithm of the number of objects in
+      the table.
+    </p>
    <marker id="max_ets_tables"></marker>
    <note>
      <p>
@@ -814,6 +833,12 @@ Error: fun containing local Erlang function calls
               inserted object <em>compares equal</em> to the key of any object
               in the table, the old object is replaced.</p>
           </item>
+          <item>
+            <p>
+	      If the table type is <c>bag</c> and the object <em>matches</em>
+	      any whole object in the table, the object is not inserted.
+            </p>
+          </item>
           <item>
             <p>If the list contains more than one object with
               <em>matching</em> keys and the table type is <c>set</c>, one is
@@ -940,14 +965,11 @@ Error: fun containing local Erlang function calls
           element, as there cannot be more than one object with the same
           key. For tables of type <c>bag</c> or <c>duplicate_bag</c>, the
           function returns a list of arbitrary length.</p>
-        <p>Notice that the time order of object insertions is preserved;
+        <p>Notice that the sequential order of object insertions is preserved;
           the first object inserted with the specified key is the first
-          in the resulting list, and so on.</p>
-        <p>Insert and lookup times in tables of type <c>set</c>,
-          <c>bag</c>, and <c>duplicate_bag</c> are constant, regardless
-          of the table size. For the <c>ordered_set</c>
-          datatype, time is proportional to the (binary) logarithm of
-          the number of objects.</p>
+          in the resulting list, and so on. See also the note about
+          <seeerl marker="#insert_list_order">list insertion order</seeerl>.
+        </p>
       </desc>
     </func>