Merge branch 'sverker/ets-select-replace-const'

* sverker/ets-select-replace-const:
  stdlib: Add examples for ets:select_replace docs
  erts: Fix ets:select_replace with {const, NewTuple}

2 files changed, 48 insertions, 8 deletions

diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml
index 0d1e5c6e3a..342be80f98 100644
--- a/lib/stdlib/doc/src/ets.xml
+++ b/lib/stdlib/doc/src/ets.xml
@@ -1495,17 +1495,37 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code>
       <fsummary>Match and replace objects atomically in an ETS table</fsummary>
       <desc>
         <p>Matches the objects in the table <c><anno>Tab</anno></c> using a
-          <seealso marker="#match_spec">match specification</seealso>. If
-          an object is matched, the existing object is replaced with
-          the match specification result, which <em>must</em> retain
-          the original key or the operation will fail with <c>badarg</c>.</p>
+          <seealso marker="#match_spec">match specification</seealso>. For each
+          matched object, the existing object is replaced with
+          the match specification result.</p>
+	<p>The match-and-replace operation for each individual object is guaranteed to be
+	  <seealso marker="#concurrency">atomic and isolated</seealso>. The
+	  <c>select_replace</c> table iteration as a whole, like all other select functions,
+	  does not give such guarantees.</p>
+	<p>The match specifiction must be guaranteed to <em>retain the key</em>
+	  of any matched object. If not, <c>select_replace</c> will fail with <c>badarg</c>
+	  without updating any objects.</p>
         <p>For the moment, due to performance and semantic constraints,
           tables of type <c>bag</c> are not yet supported.</p>
         <p>The function returns the total number of replaced objects.</p>
-        <note>
-          <p>The match/replacement operation atomicity scope is limited
-            to each individual object.</p>
-        </note>
+        <p><em>Example</em></p>
+	<p>For all 2-tuples with a list in second position, add atom <c>'marker'</c> first in the list:</p>
+	<pre>
+1> <input>T = ets:new(x,[]), ets:insert(T, {key, [1, 2, 3]}).</input>
+true
+2> <input>MS = ets:fun2ms(fun({K, L}) when is_list(L) -> {K, [marker | L]} end).</input>
+[{{'$1','$2'},[{is_list,'$2'}],[{{'$1',[marker|'$2']}}]}]
+3> <input>ets:select_replace(T, MS).</input>
+1
+4> <input>ets:tab2list(T).</input>
+[{key,[marker,1,2,3]}]
+	</pre>
+	<p>A generic single object compare-and-swap operation:</p>
+        <pre>
+[Old] = ets:lookup(T, Key),
+New = update_object(Old),
+Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])),
+	</pre>
       </desc>
     </func>
 
diff --git a/lib/stdlib/test/ets_SUITE.erl b/lib/stdlib/test/ets_SUITE.erl
index 4c2f6cfe9e..05451a83fb 100644
--- a/lib/stdlib/test/ets_SUITE.erl
+++ b/lib/stdlib/test/ets_SUITE.erl
@@ -1349,6 +1349,26 @@ t_select_replace(Config) when is_list(Config) ->
                    NeqPairs(X,Y)) || X <- Terms, Y <- Terms],
 
 
+    %% Wrap entire tuple with 'const'
+    [[begin
+          Old = {Key, 1, 2},
+          ets:insert(T2, Old),
+          1 = ets:select_replace(T2, [{Old, [], [{const, New}]}]),
+          [New] = ets:lookup(T2, Key),
+          ets:delete(T2, Key)
+      end || New <- [{Key, 1, 2}, {Key, 3, 4}, {Key, 1}, {Key, 1, 2, 3}, {Key}]
+     ]
+     || Key <- [{1, tuple}, {nested, {tuple, {a,b}}} | Terms]],
+
+    %% 'const' wrap does not work with maps or variables in keys
+    [[begin
+          Old = {Key, 1, 2},
+          {'EXIT',{badarg,_}} = (catch ets:select_replace(T2, [{Old, [], [{const, New}]}]))
+      end || New <- [{Key, 1, 2}, {Key, 3, 4}, {Key, 1}, {Key, 1, 2, 3}, {Key}]
+     ]
+     || Key <- [#{a => 1}, {nested, #{a => 1}}, '$1']],
+
+
     ets:delete(T2),
 
     verify_etsmem(EtsMem).