File 1208-stdlib-Improve-ets-documentation-about-ins... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 1208-stdlib-Improve-ets-documentation-about-insert-lookup.patch of Package erlang

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 2/2] 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 005fda8089..65b4ac76e6 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.
-
+ 
+ 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).
+ 
+ <warning>
+ 
+	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).
+ 
+ </warning>
+ 
+ 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.
+ 
 <marker id="max_ets_tables"></marker>
 <note>
 
@@ -814,6 +833,12 @@ Error: fun containing local Erlang function calls
 inserted object compares equal to the key of any object
 in the table, the old object is replaced.
 </item>
+ <item>
+ 
+	 If the table type is <c>bag</c> and the object matches
+	 any whole object in the table, the object is not inserted.
+ 
+ </item>
 <item>
 If the list contains more than one object with
 matching 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.
- Notice that the time order of object insertions is preserved;
+ 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.
- 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.
+ in the resulting list, and so on. See also the note about
+ <seeerl marker="#insert_list_order">list insertion order</seeerl>.
+ 
 </desc>
 </func>
 
-- 
2.35.3

Places

File 1208-stdlib-Improve-ets-documentation-about-insert-lookup.patch of Package erlang

Places