box.atomic tnx_isolation (#3593)

Author: andreyaksenov

doc/code_snippets/test/transactions/box_atomic_test.lua

@@ -15,7 +15,6 @@ g.before_each(function(cg)
             { name = 'band_name', type = 'string' },
             { name = 'year', type = 'unsigned' }
         })
-        box.space.bands:create_index('primary', { parts = { 'id' } })
     end)
 end)
 
@@ -26,18 +25,28 @@ end)
 
 g.test_space_is_updated = function(cg)
     cg.server:exec(function()
+        -- Create an index with the specified sequence --
+        box.schema.sequence.create('id_sequence', { min = 1 })
+        box.space.bands:create_index('primary', { parts = { 'id' }, sequence = 'id_sequence' })
+
         -- Insert test data --
         box.space.bands:insert { 1, 'Roxette', 1986 }
         box.space.bands:insert { 2, 'Scorpions', 1965 }
         box.space.bands:insert { 3, 'Ace of Base', 1987 }
 
-        -- Commit the transaction implicitly --
-        box.atomic(function()
-            box.space.bands:insert { 4, 'The Beatles', 1960 }
-            box.space.bands:replace { 1, 'Pink Floyd', 1965 }
-        end)
+        -- Define a function --
+        local function insert_band(band_name, year)
+            box.space.bands:insert { nil, band_name, year }
+        end
+
+        -- Begin and commit the transaction implicitly --
+        box.atomic(insert_band, 'The Beatles', 1960)
+
+        -- Begin the transaction with the specified isolation level --
+        box.atomic({ txn_isolation = 'read-committed' },
+                insert_band, 'The Rolling Stones', 1962)
 
-        t.assert_equals(box.space.bands:count(), 4)
-        t.assert_equals(box.space.bands:select { 1 }[1], { 1, 'Pink Floyd', 1965 })
+        t.assert_equals(box.space.bands:count(), 5)
+        t.assert_equals(box.space.bands:select { 5 }[1], { 5, 'The Rolling Stones', 1962 })
     end)
 end

doc/code_snippets/test/transactions/box_commit_test.lua

@@ -31,13 +31,19 @@ g.test_space_is_updated = function(cg)
         box.space.bands:insert { 2, 'Scorpions', 1965 }
         box.space.bands:insert { 3, 'Ace of Base', 1987 }
 
-        -- Commit the transaction --
+        -- Begin and commit the transaction explicitly --
         box.begin()
         box.space.bands:insert { 4, 'The Beatles', 1960 }
         box.space.bands:replace { 1, 'Pink Floyd', 1965 }
         box.commit()
 
-        t.assert_equals(box.space.bands:count(), 4)
-        t.assert_equals(box.space.bands:select { 1 }[1], { 1, 'Pink Floyd', 1965 })
+        -- Begin the transaction with the specified isolation level --
+        box.begin({ txn_isolation = 'read-committed' })
+        box.space.bands:insert { 5, 'The Rolling Stones', 1962 }
+        box.space.bands:replace { 1, 'The Doors', 1965 }
+        box.commit()
+
+        t.assert_equals(box.space.bands:count(), 5)
+        t.assert_equals(box.space.bands:select { 1 }[1], { 1, 'The Doors', 1965 })
     end)
 end

doc/reference/reference_lua/box_txn_management/atomic.rst

@@ -4,24 +4,35 @@
 box.atomic()
 ================================================================================
 
-.. function:: box.atomic(tx-function [, function-arguments])
+.. function:: box.atomic([opts,] tx-function [, function-arguments])
 
     Execute a function, acting as if the function starts with an implicit
     :doc:`/reference/reference_lua/box_txn_management/begin` and ends with an implicit
     :doc:`/reference/reference_lua/box_txn_management/commit` if successful, or ends with an implicit
     :doc:`/reference/reference_lua/box_txn_management/rollback` if there is an error.
 
-    :return: the result of the function passed to ``atomic()`` as an argument.
+    :param table opts: (optional) transaction options:
+
+                       *   ``txn_isolation`` -- the :ref:`transaction isolation level <txn_mode_mvcc-options>`
+                       *   ``timeout`` -- a timeout (in seconds), after which the transaction is rolled back
+
+    :param string tx-function: the function name
+
+    :param function-arguments: (optional) arguments passed to the function
+
+    :return: the result of the function passed to ``atomic()`` as an argument
 
     **Possible errors:**
 
     * error and abort the transaction in case of a conflict.
+    * error and abort the transaction if the timeout is exceeded.
     * error if the operation fails to write to disk.
     * error if for some reason memory cannot be allocated.
 
+
     **Example**
 
     ..  literalinclude:: /code_snippets/test/transactions/box_atomic_test.lua
         :language: lua
-        :lines: 29-38
+        :lines: 28-47
         :dedent:

doc/reference/reference_lua/box_txn_management/begin.rst

@@ -3,7 +3,7 @@
 box.begin()
 ===========
 
-.. function:: box.begin([txn_isolation])
+.. function:: box.begin([opts])
 
     Begin the transaction. Disable :ref:`implicit yields <app-implicit-yields>`
     until the transaction ends.
@@ -12,16 +12,20 @@ box.begin()
     In effect the fiber which executes ``box.begin()`` is starting an "active
     multi-request transaction", blocking all other fibers.
 
-    :param txn_isolation: :ref:`transaction isolation level <txn_mode_mvcc-options>`
+    :param table opts: (optional) transaction options:
+
+                       *   ``txn_isolation`` -- the :ref:`transaction isolation level <txn_mode_mvcc-options>`
+                       *   ``timeout`` -- a timeout (in seconds), after which the transaction is rolled back
 
     **Possible errors:**
 
     * error if this operation is not permitted because there is already an active transaction.
     * error if for some reason memory cannot be allocated.
+    * error and abort the transaction if the timeout is exceeded.
 
     **Example**
 
     ..  literalinclude:: /code_snippets/test/transactions/box_commit_test.lua
         :language: lua
-        :lines: 29-38
+        :lines: 29-44
         :dedent:

doc/reference/reference_lua/box_txn_management/commit.rst

@@ -18,5 +18,5 @@ box.commit()
 
     ..  literalinclude:: /code_snippets/test/transactions/box_commit_test.lua
         :language: lua
-        :lines: 29-38
+        :lines: 29-44
         :dedent: