diff --git a/doc/code_snippets/test/errors/error_list_test.lua b/doc/code_snippets/test/errors/error_list_test.lua new file mode 100644 index 0000000000..474561d26a --- /dev/null +++ b/doc/code_snippets/test/errors/error_list_test.lua @@ -0,0 +1,47 @@ +local status, err = pcall(function() + -- snippet_start + local base_server_error = box.error.new({ code = 500, + reason = 'Base server error', + type = 'BaseServerError' }) + local storage_server_error = box.error.new({ code = 507, + reason = 'Not enough storage', + type = 'StorageServerError' }) + + base_server_error:set_prev(storage_server_error) + --[[ + --- + ... + --]] + + box.error(base_server_error) + --[[ + --- + - error: Base server error + ... + --]] + + box.error.last().prev:unpack() + --[[ + --- + - code: 507 + base_type: CustomError + type: StorageServerError + custom_type: StorageServerError + message: Not enough storage + trace: + - file: '[string "storage_server_error = box.error.new({ code =..."]' + line: 1 + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'BaseServerError') + luatest.assert_equals(err:unpack().message, 'Base server error') + luatest.assert_equals(err.prev:unpack().type, 'StorageServerError') + luatest.assert_equals(err.prev:unpack().message, 'Not enough storage') +end diff --git a/doc/code_snippets/test/errors/raise_error_array_custom_type_args_test.lua b/doc/code_snippets/test/errors/raise_error_array_custom_type_args_test.lua new file mode 100644 index 0000000000..dbed30cde4 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_error_array_custom_type_args_test.lua @@ -0,0 +1,18 @@ +local status, err = pcall(function() + -- snippet_start + box.error('CustomConnectionError', '%s cannot connect to the port %u', 'client', 8080) + --[[ + --- + - error: client cannot connect to the port 8080 + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'CustomConnectionError') + luatest.assert_equals(err:unpack().message, 'client cannot connect to the port 8080') +end diff --git a/doc/code_snippets/test/errors/raise_error_array_custom_type_test.lua b/doc/code_snippets/test/errors/raise_error_array_custom_type_test.lua new file mode 100644 index 0000000000..8723a60b30 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_error_array_custom_type_test.lua @@ -0,0 +1,18 @@ +local status, err = pcall(function() + -- snippet_start + box.error('CustomConnectionError', 'cannot connect to the given port') + --[[ + --- + - error: cannot connect to the given port + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'CustomConnectionError') + luatest.assert_equals(err:unpack().message, 'cannot connect to the given port') +end diff --git a/doc/code_snippets/test/errors/raise_error_table_custom_type_test.lua b/doc/code_snippets/test/errors/raise_error_table_custom_type_test.lua new file mode 100644 index 0000000000..d8a9181433 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_error_table_custom_type_test.lua @@ -0,0 +1,20 @@ +local status, err = pcall(function() + -- snippet_start + box.error { code = 500, + reason = 'Internal server error', + type = 'CustomInternalError' } + --[[ + --- + - error: Internal server error + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'CustomInternalError') + luatest.assert_equals(err:unpack().message, 'Internal server error') +end diff --git a/doc/code_snippets/test/errors/raise_error_table_test.lua b/doc/code_snippets/test/errors/raise_error_table_test.lua new file mode 100644 index 0000000000..2189b57c25 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_error_table_test.lua @@ -0,0 +1,18 @@ +local status, err = pcall(function() + -- snippet_start + box.error { code = 500, + reason = 'Custom server error' } + --[[ + --- + - error: Custom server error + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().message, 'Custom server error') +end diff --git a/doc/code_snippets/test/errors/raise_new_error_array_custom_type_test.lua b/doc/code_snippets/test/errors/raise_new_error_array_custom_type_test.lua new file mode 100644 index 0000000000..2cf1c6fb15 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_new_error_array_custom_type_test.lua @@ -0,0 +1,20 @@ +local status, err = pcall(function() + -- snippet_start + local custom_error = box.error.new('CustomInternalError', 'Internal server error') + + box.error(custom_error) + --[[ + --- + - error: Internal server error + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'CustomInternalError') + luatest.assert_equals(err:unpack().message, 'Internal server error') +end diff --git a/doc/code_snippets/test/errors/raise_new_error_table_custom_type_test.lua b/doc/code_snippets/test/errors/raise_new_error_table_custom_type_test.lua new file mode 100644 index 0000000000..4e42eba73c --- /dev/null +++ b/doc/code_snippets/test/errors/raise_new_error_table_custom_type_test.lua @@ -0,0 +1,22 @@ +local status, err = pcall(function() + -- snippet_start + local custom_error = box.error.new({ code = 500, + reason = 'Internal server error', + type = 'CustomInternalError' }) + + box.error(custom_error) + --[[ + --- + - error: Internal server error + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'CustomInternalError') + luatest.assert_equals(err:unpack().message, 'Internal server error') +end diff --git a/doc/code_snippets/test/errors/raise_new_error_table_test.lua b/doc/code_snippets/test/errors/raise_new_error_table_test.lua new file mode 100644 index 0000000000..0fdb81f01f --- /dev/null +++ b/doc/code_snippets/test/errors/raise_new_error_table_test.lua @@ -0,0 +1,21 @@ +local status, err = pcall(function() + -- snippet_start + local custom_error = box.error.new({ code = 500, + reason = 'Internal server error' }) + + box.error(custom_error) + --[[ + --- + - error: Internal server error + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'ClientError') + luatest.assert_equals(err:unpack().message, 'Internal server error') +end diff --git a/doc/code_snippets/test/errors/raise_new_tarantool_error_multiple_arg_test.lua b/doc/code_snippets/test/errors/raise_new_tarantool_error_multiple_arg_test.lua new file mode 100644 index 0000000000..e2c16f5ed1 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_new_tarantool_error_multiple_arg_test.lua @@ -0,0 +1,19 @@ +local status, err = pcall(function() + -- snippet_start + local custom_error = box.error.new(box.error.CREATE_SPACE, 'my_space', 'the space already exists') + + box.error(custom_error) + --[[ + --- + - error: 'Failed to create space ''my_space'': the space already exists' + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_tarantool_error_is_raised = function() + luatest.assert_equals(err:unpack().message, "Failed to create space 'my_space': the space already exists") +end diff --git a/doc/code_snippets/test/errors/raise_new_tarantool_error_one_arg_test.lua b/doc/code_snippets/test/errors/raise_new_tarantool_error_one_arg_test.lua new file mode 100644 index 0000000000..cec550a4ed --- /dev/null +++ b/doc/code_snippets/test/errors/raise_new_tarantool_error_one_arg_test.lua @@ -0,0 +1,19 @@ +local status, err = pcall(function() + -- snippet_start + local custom_error = box.error.new(box.error.NO_SUCH_USER, 'John') + + box.error(custom_error) + --[[ + --- + - error: User 'John' is not found + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_tarantool_error_is_raised = function() + luatest.assert_equals(err:unpack().message, "User 'John' is not found") +end diff --git a/doc/code_snippets/test/errors/raise_tarantool_error_multiple_arg_test.lua b/doc/code_snippets/test/errors/raise_tarantool_error_multiple_arg_test.lua new file mode 100644 index 0000000000..fd04684337 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_tarantool_error_multiple_arg_test.lua @@ -0,0 +1,17 @@ +local status, err = pcall(function() + -- snippet_start + box.error(box.error.CREATE_SPACE, 'my_space', 'the space already exists') + --[[ + --- + - error: 'Failed to create space ''my_space'': the space already exists' + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_tarantool_error_is_raised = function() + luatest.assert_equals(err:unpack().message, "Failed to create space 'my_space': the space already exists") +end diff --git a/doc/code_snippets/test/errors/raise_tarantool_error_no_arg_test.lua b/doc/code_snippets/test/errors/raise_tarantool_error_no_arg_test.lua new file mode 100644 index 0000000000..4c1cfd6324 --- /dev/null +++ b/doc/code_snippets/test/errors/raise_tarantool_error_no_arg_test.lua @@ -0,0 +1,17 @@ +local status, err = pcall(function() + -- snippet_start + box.error(box.error.READONLY) + --[[ + --- + - error: Can't modify data on a read-only instance + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_tarantool_error_is_raised = function() + luatest.assert_equals(err:unpack().message, "Can't modify data on a read-only instance") +end diff --git a/doc/code_snippets/test/errors/raise_tarantool_error_one_arg_test.lua b/doc/code_snippets/test/errors/raise_tarantool_error_one_arg_test.lua new file mode 100644 index 0000000000..6bb3d769bc --- /dev/null +++ b/doc/code_snippets/test/errors/raise_tarantool_error_one_arg_test.lua @@ -0,0 +1,17 @@ +local status, err = pcall(function() + -- snippet_start + box.error(box.error.NO_SUCH_USER, 'John') + --[[ + --- + - error: User 'John' is not found + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_tarantool_error_is_raised = function() + luatest.assert_equals(err:unpack().message, "User 'John' is not found") +end diff --git a/doc/code_snippets/test/errors/set_error_test.lua b/doc/code_snippets/test/errors/set_error_test.lua new file mode 100644 index 0000000000..1b341a72ef --- /dev/null +++ b/doc/code_snippets/test/errors/set_error_test.lua @@ -0,0 +1,45 @@ +local status, err = pcall(function() + -- snippet_start + -- Create two errors -- + local error1 = box.error.new({ code = 500, reason = 'Custom error 1' }) + local error2 = box.error.new({ code = 505, reason = 'Custom error 2' }) + + -- Raise the first error -- + box.error(error1) + --[[ + --- + - error: Custom error 1 + ... + --]] + + -- Get the last error -- + box.error.last() + --[[ + --- + - Custom error 1 + ... + --]] + + -- Set the second error as the last error -- + box.error.set(error2) + --[[ + --- + ... + --]] + + -- Get the last error -- + box.error.last() + --[[ + --- + - Custom error 2 + ... + --]] + -- snippet_end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().message, 'Custom error 1') +end diff --git a/doc/code_snippets/test/errors/unpack_clear_error_test.lua b/doc/code_snippets/test/errors/unpack_clear_error_test.lua new file mode 100644 index 0000000000..06e0c2ae7c --- /dev/null +++ b/doc/code_snippets/test/errors/unpack_clear_error_test.lua @@ -0,0 +1,63 @@ +local status, err = pcall(function() + -- Create an error: start + local custom_error = box.error.new({ code = 500, + reason = 'Internal server error', + type = 'CustomInternalError' }) + -- Create an error: end + + -- Raise the error: start + box.error(custom_error) + --[[ + --- + - error: Internal server error + ... + --]] + -- Raise the error: end + + -- Get the last error: start + box.error.last() + --[[ + --- + - error: Internal server error + ... + --]] + -- Get the last error: end + + -- Get error details: start + box.error.last():unpack() + --[[ + --- + - code: 500 + base_type: CustomError + type: CustomInternalError + custom_type: CustomInternalError + message: Internal server error + trace: + - file: '[string "custom_error = box.error.new({ code = 500,..."]' + line: 1 + ... + --]] + -- Get error details: end + + -- Clear the errors: start + box.error.clear() + --[[ + --- + ... + --]] + box.error.last() + --[[ + --- + - null + ... + --]] + -- Clear the errors: end +end) + +-- Tests +local luatest = require('luatest') +local test_group = luatest.group() +test_group.test_error_is_raised = function() + luatest.assert_equals(err:unpack().type, 'CustomInternalError') + luatest.assert_equals(err:unpack().message, 'Internal server error') +end diff --git a/doc/reference/reference_lua/box_error.rst b/doc/reference/reference_lua/box_error.rst index 131662de84..7202ae13e5 100644 --- a/doc/reference/reference_lua/box_error.rst +++ b/doc/reference/reference_lua/box_error.rst @@ -1,14 +1,253 @@ -------------------------------------------------------------------------------- - Submodule box.error -------------------------------------------------------------------------------- +.. _box-error-submodule: -The ``box.error`` function is for raising an error. The difference between this -function and Lua's built-in `error `_ function +Submodule box.error +=================== + +The ``box.error`` submodule can be used to work with errors in your application. +For example, you can get the information about the last error raised by Tarantool or +raise custom errors manually. + +The difference between raising an error using ``box.error`` +and a Lua's built-in `error `_ function is that when the error reaches the client, its error code is preserved. In contrast, a Lua error would always be presented to the client as :errcode:`ER_PROC_LUA`. -Below is a list of all ``box.error`` functions. +.. NOTE:: + + To learn how to handle errors in your application, see the :ref:`Handling errors ` section. + + +.. _box_error_create_error: + +Creating an error +----------------- + +You can create an error object using the :ref:`box.error.new() ` function. +The created object can be passed to :ref:`box.error() ` to raise the error. +You can also raise the error using :ref:`error_object:raise() `. + +The example below shows how to create and raise the error with the specified code and reason. + +.. literalinclude:: /code_snippets/test/errors/raise_new_error_table_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +``box.error.new()`` provides different overloads for creating an error object with different parameters. +These overloads are similar to the ``box.error()`` overloads described in the :ref:`next section `. + + +.. _box_error_raise_error: + +Raising an error +---------------- + +To raise an error, call the :ref:`box.error() ` function. +This function can accept the specified error parameters or an error object :ref:`created using box.error.new() `. +In both cases, you can use ``box.error()`` to raise the following error types: + +* A custom error with the specified reason, code, and type. +* A predefined Tarantool error. + + +.. _box_error_raise_custom_error: + +Custom error +~~~~~~~~~~~~ + +The following ``box.error()`` overloads are available for raising a custom error: + +* :ref:`box.error({ reason = string[, code = number, type = string] }) ` accepts a Lua table containing the error reason, code, and type. +* :ref:`box.error(type, reason[, args]) ` accepts the error type, its reason, and optional arguments passed to a reason's string. + +.. NOTE:: + + The same overloads are available for :ref:`box.error.new() `. + + +.. _box_error_raise_custom_table_error: + +box.error({ reason = string[, ...] }) +************************************* + +In the example below, ``box.error()`` accepts a Lua table with the specified error code and reason: + +.. literalinclude:: /code_snippets/test/errors/raise_error_table_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +The next example shows how to specify a custom error type: + +.. literalinclude:: /code_snippets/test/errors/raise_error_table_custom_type_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +When a custom type is specified, it is returned in the :ref:`error_object.type ` attribute. +When it is not specified, ``error_object.type`` returns one of the built-in errors, such as +``ClientError`` or ``OutOfMemory``. + +.. _box_error_raise_custom_array_error: + +box.error(type, reason[, ...]) +****************************** + +This example shows how to raise an error with the type and reason specified in the ``box.error()`` arguments: + +.. literalinclude:: /code_snippets/test/errors/raise_error_array_custom_type_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +You can also use a format string to compose an error reason: + +.. literalinclude:: /code_snippets/test/errors/raise_error_array_custom_type_args_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + + + +.. _box_error_raise_tarantool_error: + +Tarantool error +~~~~~~~~~~~~~~~ + +The :ref:`box.error(code[, ...]) ` overload raises a predefined +:ref:`Tarantool error ` specified by its identifier. +The error code defines the error message format and the number of required arguments. +In the example below, no arguments are passed for the ``box.error.READONLY`` error code: + +.. literalinclude:: /code_snippets/test/errors/raise_tarantool_error_no_arg_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +For the ``box.error.NO_SUCH_USER`` error code, you need to pass one argument: + +.. literalinclude:: /code_snippets/test/errors/raise_tarantool_error_one_arg_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +``box.error.CREATE_SPACE`` requires two arguments: + +.. literalinclude:: /code_snippets/test/errors/raise_tarantool_error_multiple_arg_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + + +.. _box_error_get_last_error: + +Getting the last error +---------------------- + +To get the last raised error, call :ref:`box.error.last() `: + +.. literalinclude:: /code_snippets/test/errors/unpack_clear_error_test.lua + :language: lua + :start-after: Get the last error: start + :end-before: Get the last error: end + :dedent: + +.. _box_error_get_error_details: + +Obtaining error details +----------------------- + +To get error details, call the :ref:`error_object.unpack() `. +Error details may include an error code, type, message, and trace. + +.. literalinclude:: /code_snippets/test/errors/unpack_clear_error_test.lua + :language: lua + :start-after: Get error details: start + :end-before: Get error details: end + :dedent: + +.. _box_error_set_last_error: + +Setting the last error +---------------------- + +You can set the last error explicitly by calling :ref:`box.error.set() `: + +.. literalinclude:: /code_snippets/test/errors/set_error_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +.. _box_error_error_lists: + +Error lists +----------- + +:ref:`error_object ` provides the API for organizing errors into lists. +To set and get the previous error, use the :ref:`error_object:set_prev() ` method and :ref:`error_object.prev ` attribute. + +.. literalinclude:: /code_snippets/test/errors/error_list_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +Cycles are not allowed for error lists: + +.. code-block:: lua + + storage_server_error:set_prev(base_server_error) + --[[ + --- + - error: 'builtin/error.lua:120: Cycles are not allowed' + ... + --]] + +Setting the previous error does not erase its own previous members: + +.. code-block:: Lua + + -- e1 -> e2 -> e3 -> e4 + e1:set_prev(e2) + e2:set_prev(e3) + e3:set_prev(e4) + e2:set_prev(e5) + -- Now there are two lists: e1 -> e2 -> e5 and e3 -> e4 + +IPROTO also supports stacked diagnostics. +See details in :ref:`MessagePack extensions -- The ERROR type `. + +.. _box_error_clear_errors: + +Clearing errors +--------------- + +To clear the errors, call :ref:`box.error.clear() `. + +.. literalinclude:: /code_snippets/test/errors/unpack_clear_error_test.lua + :language: lua + :start-after: Clear the errors: start + :end-before: Clear the errors: end + :dedent: + + + +.. _box-error-submodule-api-reference: + +API Reference +------------- + +Below is a list of ``box.error`` functions and related objects. .. container:: table @@ -23,25 +262,23 @@ Below is a list of all ``box.error`` functions. - Use * - :doc:`./box_error/error` - - Throw an error + - Raise the last error or the error defined by the specified parameters * - :doc:`./box_error/last` - - Get a description of the last error + - Get the last raised error * - :doc:`./box_error/clear` - - Clear the record of errors + - Clear the errors * - :doc:`./box_error/new` - - Create an error but do not throw + - Create the error but do not raise it * - :doc:`./box_error/set` - - Set an error as ``box.error.last()`` + - Set the specified error as the last system error explicitly * - :doc:`./box_error/error_object` - - Error object methods + - An object that defines an error - * - :doc:`./box_error/custom_type` - - Create a custom error type .. toctree:: :hidden: @@ -52,4 +289,3 @@ Below is a list of all ``box.error`` functions. box_error/new box_error/set box_error/error_object - box_error/custom_type \ No newline at end of file diff --git a/doc/reference/reference_lua/box_error/clear.rst b/doc/reference/reference_lua/box_error/clear.rst index f107b0b2d8..5ff1d68ff8 100644 --- a/doc/reference/reference_lua/box_error/clear.rst +++ b/doc/reference/reference_lua/box_error/clear.rst @@ -6,21 +6,12 @@ box.error.clear() .. function:: box.error.clear() - Clear the record of errors, so functions like ``box.error()`` - or ``box.error.last()`` will have no effect. + Clear the errors. - **Example:** + **Example** - .. code-block:: tarantoolsession - - tarantool> box.error.last() - --- - - Invalid identifier '' (expected printable symbols only or it is too long) - ... - tarantool> box.error.clear() - --- - ... - tarantool> box.error.last() - --- - - null - ... + .. literalinclude:: /code_snippets/test/errors/unpack_clear_error_test.lua + :language: lua + :start-after: Clear the errors: start + :end-before: Clear the errors: end + :dedent: diff --git a/doc/reference/reference_lua/box_error/custom_type.rst b/doc/reference/reference_lua/box_error/custom_type.rst index b4e896e284..a2b6e7f809 100644 --- a/doc/reference/reference_lua/box_error/custom_type.rst +++ b/doc/reference/reference_lua/box_error/custom_type.rst @@ -37,7 +37,7 @@ Or a no-throw version: When a custom type is specified, it is reported in the ``err.type`` attribute. When it is not specified, ``err.type`` reports one of built-in errors such as -``'ClientError'``, ``'OurOfMemory'``, etc. +``'ClientError'``, ``'OutOfMemory'``, etc. The maximum name length for a custom type is *63 bytes*. Everything longer than this limit is truncated. diff --git a/doc/reference/reference_lua/box_error/error.rst b/doc/reference/reference_lua/box_error/error.rst index 904e19c6d7..b31823f6ed 100644 --- a/doc/reference/reference_lua/box_error/error.rst +++ b/doc/reference/reference_lua/box_error/error.rst @@ -1,70 +1,115 @@ .. _box_error-error: -=============================================================================== box.error() -=============================================================================== +=========== + +.. _box_error-error-no-arg: .. function:: box.error() - When called without arguments, ``box.error()`` re-throws whatever the last - error was. + Raise the last error. + + **See also:** :ref:`box.error.last() ` + +.. _box_error-error-object: + +.. function:: box.error(error_object) + + Raise the error defined by :ref:`error_object `. + + :param error_object error_object: an error object + + **Example** + + .. literalinclude:: /code_snippets/test/errors/raise_new_error_table_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +.. _box_error-error-table: + +.. function:: box.error({ reason = string[, code = number, type = string] }) + + Raise the error defined by the specified parameters. + + :param string reason: an error description + :param integer code: (optional) a numeric code for this error + :param string type: (optional) an error type + + **Example 1** + + .. literalinclude:: /code_snippets/test/errors/raise_error_table_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + + **Example 2: custom type** + + .. literalinclude:: /code_snippets/test/errors/raise_error_table_custom_type_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +.. _box_error-error-array: + +.. function:: box.error(type, reason[, ...]) + + Raise the error defined by the specified type and description. -.. function:: box.error{reason = string [, code = number]} + :param string type: an error type + :param string reason: an error description + :param ...: description arguments - Throw an error. When called with a Lua-table argument, the code and reason - have any user-desired values. The result will be those values. + **Example 1: without arguments** - :param string reason: description of an error, defined by user - :param integer code: numeric code for this error, defined by user + .. literalinclude:: /code_snippets/test/errors/raise_error_array_custom_type_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: -.. function:: box.error(code, errtext [, errtext ...]) + **Example 2: with arguments** - Throw an error. This method emulates a request error, with text based on one - of the pre-defined Tarantool errors defined in the file `errcode.h - `_ in - the source tree. Lua constants which correspond to those Tarantool errors are - defined as members of ``box.error``, for example ``box.error.NO_SUCH_USER == 45``. + .. literalinclude:: /code_snippets/test/errors/raise_error_array_custom_type_args_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: - :param number code: number of a pre-defined error - :param string errtext(s): part of the message which will accompany the error +.. _box_error-error-predefined: - For example: +.. function:: box.error(code[, ...]) - the ``NO_SUCH_USER`` message is "``User '%s' is not found``" -- it includes - one "``%s``" component which will be replaced with errtext. Thus a call to - ``box.error(box.error.NO_SUCH_USER, 'joe')`` or ``box.error(45, 'joe')`` - will result in an error with the accompanying message "``User 'joe' is not found``". + Raise a predefined :ref:`Tarantool error ` specified by its identifier. + You can see all Tarantool errors in the `errcode.h + `_ file. - :except: whatever is specified in errcode-number. + :param number code: a pre-defined error identifier; Lua constants that correspond to those Tarantool errors are defined as members of ``box.error``, for example, ``box.error.NO_SUCH_USER == 45`` + :param ...: description arguments - ``box.error()`` accepts two sets of arguments: + **Example 1: no arguments** - * error code and reason/errtext (``box.error{code = 555, reason = 'Arbitrary - message'}``), or - * error object (``box.error(err)``). + .. literalinclude:: /code_snippets/test/errors/raise_tarantool_error_no_arg_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: - In both cases the error is promoted as the last error. + **Example 2: one argument** - **Example:** + .. literalinclude:: /code_snippets/test/errors/raise_tarantool_error_one_arg_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: - .. code-block:: tarantoolsession + **Example 3: two arguments** - tarantool> e1 = box.error.new({code = 111, reason = 'Сause'}) - --- - ... - tarantool> box.error(e1) - --- - - error: Сause - ... - tarantool> box.error{code = 555, reason = 'Arbitrary message'} - --- - - error: Arbitrary message - ... - tarantool> box.error() - --- - - error: Arbitrary message - ... - tarantool> box.error(box.error.FUNCTION_ACCESS_DENIED, 'A', 'B', 'C') - --- - - error: A access denied for user 'B' to function 'C' - ... + .. literalinclude:: /code_snippets/test/errors/raise_tarantool_error_multiple_arg_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: diff --git a/doc/reference/reference_lua/box_error/error_object.rst b/doc/reference/reference_lua/box_error/error_object.rst index 63ffa6985e..93266c3e03 100644 --- a/doc/reference/reference_lua/box_error/error_object.rst +++ b/doc/reference/reference_lua/box_error/error_object.rst @@ -6,59 +6,186 @@ error_object .. class:: error_object - Since version :doc:`2.4.1 `. - Errors can be organized into lists. To achieve this, a Lua table representing an - error object has ``.prev`` field and ``e:set_prev(err)`` method. + An object that defines an error. + ``error_object`` is returned by the following methods: + + * :ref:`box.error.new() ` + * :ref:`box.error.last() ` + + .. _box_error-unpack: + + .. method:: unpack() + + Get error details that may include an error code, type, message, and trace. + + **Example** + + .. literalinclude:: /code_snippets/test/errors/unpack_clear_error_test.lua + :language: lua + :start-after: Get error details: start + :end-before: Get error details: end + :dedent: + + .. NOTE:: + + Depending on the error type, error details may include other attributes, such as :ref:`errno ` or :ref:`reason `. + + .. _box_error-raise: + + .. method:: raise() + + Raise the current error. + + **See also:** :ref:`Raising an error ` + + .. _box_error-set_prev: + + .. method:: set_prev(error_object) + + **Since:** :doc:`2.4.1 ` + + Set the previous error for the current one. + + :param error_object body: an error object + + **See also:** :ref:`Error lists ` .. _box_error-prev: .. data:: prev - Return a previous error, if any. + **Since:** :doc:`2.4.1 ` - .. _box_error-set_prev: + Get the previous error for the current one. + + :rtype: error_object + + **See also:** :ref:`Error lists ` + + .. _box_error-code: + + .. data:: code + + The error code. + This attribute may return a :ref:`custom error ` code or a :ref:`Tarantool error ` code. + + :rtype: number + + .. _box_error-type: + + .. data:: type + + The error type. + + :rtype: string + + **See also:** :ref:`Custom error ` + + .. _box_error-message: + + .. data:: message + + The error message. + + :rtype: string + + .. _box_error-trace: + + .. data:: trace + + The error trace. + + :rtype: table + + .. _box_error-errno: + + .. data:: errno + + If the error is a system error (for example, a socket or file IO failure), + returns a C standard error number. + + :rtype: number + + .. _box_error-reason: + + .. data:: reason + + **Since:** :doc:`2.10.0 ` + + Returns the :ref:`box.info.ro_reason ` value at the moment of throwing the ``box.error.READONLY`` error. + + The following values may be returned: + + - ``election`` if the instance has :ref:`box.cfg.election_mode ` set to a value other than ``off`` and this instance is not a leader. + In this case, ``error_object`` may include the following attributes: ``state``, ``leader_id``, ``leader_uuid``, and ``term``. + - ``synchro`` if the synchronous queue has an owner that is not the given instance. + This error usually happens if :ref:`synchronous replication ` is used and another instance is called :ref:`box.ctl.promote() `. + In this case, ``error_object`` may include the ``queue_owner_id``, ``queue_owner_uuid``, and ``term`` attributes. + - ``config`` if the :ref:`box.cfg.read_only ` is set to ``true``. + - ``orphan`` if the instance is in the :ref:`orphan ` state. + + .. NOTE:: + + If multiple reasons are true at the same time, then only one is returned in the following order of preference: ``election``, ``synchro``, ``config``, ``orphan``. + + :rtype: string + + .. _box_error-state: + + .. data:: state + + **Since:** :doc:`2.10.0 ` + + For the ``box.error.READONLY`` error, returns the current state of a replica set node in regards to leader election (see :ref:`box.info.election.state `). + This attribute presents if the :ref:`error reason ` is ``election``. + + :rtype: string + + .. _box_error-leader_id: + + .. data:: leader_id + + **Since:** :doc:`2.10.0 ` + + For the ``box.error.READONLY`` error, returns a numeric identifier (:ref:`box.info.id `) of the replica set leader. + This attribute may present if the :ref:`error reason ` is ``election``. + + :rtype: number + + .. _box_error-leader_uuid: + + .. data:: leader_uuid + + **Since:** :doc:`2.10.0 ` + + For the ``box.error.READONLY`` error, returns a globally unique identifier (:ref:`box.info.uuid `) of the replica set leader. + This attribute may present if the :ref:`error reason ` is ``election``. + + .. _box_error-queue_owner_id: - .. method:: set_prev(error object) + .. data:: queue_owner_id - Set an error as the previous error. Accepts an ``error object`` or ``nil``. + **Since:** :doc:`2.10.0 ` - **Example:** + For the ``box.error.READONLY`` error, returns a numeric identifier (:ref:`box.info.id `) of the synchronous queue owner. + This attribute may present if the :ref:`error reason ` is ``synchro``. - .. code-block:: tarantoolsession + :rtype: number - tarantool> e1 = box.error.new({code = 111, reason = 'some cause'}) - --- - ... - tarantool> e2 = box.error.new({code = 111, reason = 'cause of cause'}) - --- - ... - tarantool> e1:set_prev(e2) - --- - ... - tarantool> e1.prev - --- - - cause of cause - ... + .. _box_error-queue_owner_uuid: - Cycles are not allowed for error lists: + .. data:: queue_owner_uuid - .. code-block:: tarantoolsession + **Since:** :doc:`2.10.0 ` - tarantool> e2:set_prev(e1) - --- - - error: 'builtin/error.lua:147: Cycles are not allowed' - ... + For the ``box.error.READONLY`` error, returns a globally unique identifier (:ref:`box.info.uuid `) of the synchronous queue owner. + This attribute may present if the :ref:`error reason ` is ``synchro``. - Setting the previous error does not erase its own previous members: + .. _box_error-term: - .. code-block:: Lua + .. data:: term - -- e1 -> e2 -> e3 -> e4 - e1:set_prev(e2) - e2:set_prev(e3) - e3:set_prev(e4) - e2:set_prev(e5) - -- Now there are two lists: e1->e2->e5 and e3->e4 + **Since:** :doc:`2.10.0 ` - The iProto protocol also supports stacked diagnostics. See details in - :ref:`MessagePack extensions -- The ERROR type `. + For the ``box.error.READONLY`` error, returns the current election term (see :ref:`box.info.election.term `). + This attribute may present if the :ref:`error reason ` is ``election`` or ``synchro``. diff --git a/doc/reference/reference_lua/box_error/last.rst b/doc/reference/reference_lua/box_error/last.rst index c57cd65e7c..d13c6e2145 100644 --- a/doc/reference/reference_lua/box_error/last.rst +++ b/doc/reference/reference_lua/box_error/last.rst @@ -6,39 +6,16 @@ box.error.last() .. function:: box.error.last() - Return a description of the last error, as a Lua table with four members: + Get the last raised error. - * "code" (number) error’s number - * "type" (string) error’s C++ class - * "message" (string) error’s message - * "trace" (table) with 2 members: - * "line" (number) Tarantool source file line number - * "file" (string) Tarantool source file + :return: an :ref:`error_object ` representing the last error - Additionally, if the error is a system error (for example due to a - failure in socket or file io), there may be a fifth member: - "errno" (number) C standard error number. + **Example** - :rtype: table + .. literalinclude:: /code_snippets/test/errors/unpack_clear_error_test.lua + :language: lua + :start-after: Get the last error: start + :end-before: Get the last error: end + :dedent: - To show the table, use ``unpack()``: - - .. code-block:: tarantoolsession - - tarantool> box.schema.space.create('') - --- - - error: Invalid identifier '' (expected printable symbols only or it is too long) - ... - tarantool> box.error.last() - --- - - Invalid identifier '' (expected printable symbols only or it is too long) - ... - tarantool> box.error.last():unpack() - --- - - type: ClientError - code: 70 - message: Invalid identifier '' (expected printable symbols only or it is too long) - trace: - - file: /tmp/tarantool-20200109-43082-1pv0594/tarantool-2.3.1.1/src/box/identifier.c - line: 68 - ... \ No newline at end of file + **See also:** :ref:`error_object:unpack() ` diff --git a/doc/reference/reference_lua/box_error/new.rst b/doc/reference/reference_lua/box_error/new.rst index 45ec640ff7..628ee036ab 100644 --- a/doc/reference/reference_lua/box_error/new.rst +++ b/doc/reference/reference_lua/box_error/new.rst @@ -4,62 +4,73 @@ box.error.new() =============================================================================== -.. function:: box.error.new(code, errtext [, errtext ...]) - - Create an error object, but not throw it as - :doc:`/reference/reference_lua/box_error/error` - does. This is useful when error information should be saved for later retrieval. - Since version :doc:`2.4.1 `, to set an error as the last explicitly use - :doc:`/reference/reference_lua/box_error/set`. - - :param number code: number of a pre-defined error - :param string errtext(s): part of the message which will accompany the error - - **Example:** - - .. code-block:: tarantoolsession - - tarantool> e=box.error.new{code=5,reason='A',type='B'} - --- - ... - tarantool> e:unpack() - --- - - code: 5 - base_type: CustomError - type: B - custom_type: B - message: A - trace: - - file: '[string "e=box.error.new{code=5,reason=''A'',type=''B''}"]' - line: 1 - ... - tarantool> box.error.last() - --- - - null - - Since version :doc:`2.4.1 `, the ``error_marshaling_enabled`` setting - has been introduced in :ref:`_session_settings `. - The new setting affects the structure of error objects. If ``error_marshaling_enabled`` - is set to ``true``, the object will have the MP_EXT type and the - MP_ERROR subtype. - - Using the :ref:`binary protocol `, - the server can send a packet in response to ``box.error.new()``. - The body of that packet contains the following data: - - - the encoding of MP_EXT according to the - `MessagePack specification `_ - (usually 0xc7) - - the encoding of MP_ERROR (0x03) - - the encoding of MP_ERROR_STACK (0x81) - - all of the MP_ERROR_STACK components: - an MP_ARRAY containing an MP_MAP which, in turn, contains - keys like MP_ERROR_MESSAGE, MP_ERROR_CODE, etc. - These components are described and illustrated in the section - :ref:`MessagePack extensions -- The ERROR type `. - - The error object map fields correspond to specific keys: - - - "type" corresponds to MP_ERROR_TYPE - - "code" corresponds to MP_ERROR_ERRCODE - - "message" corresponds to MP_ERROR_MESSAGE. +.. _box_error-new-error-table: + +.. function:: box.error.new({ reason = string[, code = number, type = string] }) + + Create an error object with the specified parameters. + + :param string reason: an error description + :param integer code: (optional) a numeric code for this error + :param string type: (optional) an error type + + **Example 1** + + .. literalinclude:: /code_snippets/test/errors/raise_new_error_table_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + + **Example 2: custom type** + + .. literalinclude:: /code_snippets/test/errors/raise_new_error_table_custom_type_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +.. _box_error-new-error-array: + +.. function:: box.error.new(type, reason[, ...]) + + Create an error object with the specified type and description. + + :param string type: an error type + :param string reason: an error description + :param ...: description arguments + + **Example** + + .. literalinclude:: /code_snippets/test/errors/raise_new_error_array_custom_type_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + +.. _box_error-new-error-predefined: + +.. function:: box.error.new(code[, ...]) + + Create a predefined :ref:`Tarantool error ` specified by its identifier. + You can see all Tarantool errors in the `errcode.h + `_ file. + + :param number code: a pre-defined error identifier; Lua constants that correspond to those Tarantool errors are defined as members of ``box.error``, for example, ``box.error.NO_SUCH_USER == 45`` + :param ...: description arguments + + **Example 1: one argument** + + .. literalinclude:: /code_snippets/test/errors/raise_new_tarantool_error_one_arg_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: + + **Example 2: two arguments** + + .. literalinclude:: /code_snippets/test/errors/raise_new_tarantool_error_multiple_arg_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: diff --git a/doc/reference/reference_lua/box_error/set.rst b/doc/reference/reference_lua/box_error/set.rst index 864a7858a5..66bbe2f508 100644 --- a/doc/reference/reference_lua/box_error/set.rst +++ b/doc/reference/reference_lua/box_error/set.rst @@ -4,28 +4,19 @@ box.error.set() =============================================================================== -.. function:: box.error.set(error object) +.. function:: box.error.set(error_object) - Since version :doc:`2.4.1 `. - Set an error as the last system error explicitly. Accepts an error object and - makes it available via :doc:`/reference/reference_lua/box_error/last`. + **Since:** :doc:`2.4.1 ` - **Example:** + Set the specified error as the last system error explicitly. + This error is returned by :doc:`/reference/reference_lua/box_error/last`. - .. code-block:: tarantoolsession + :param error_object error_object: an error object - tarantool> err = box.error.new({code = 111, reason = 'cause'}) - --- - ... - tarantool> box.error.last() - --- - - error: '[string "return tarantool> box.error.last()"]:1: attempt to compare two - nil values' - ... - tarantool> box.error.set(err) - --- - ... - tarantool> box.error.last() - --- - - cause - ... + **Example** + + .. literalinclude:: /code_snippets/test/errors/set_error_test.lua + :language: lua + :start-after: snippet_start + :end-before: snippet_end + :dedent: diff --git a/doc/reference/reference_lua/box_space/_session_settings.rst b/doc/reference/reference_lua/box_space/_session_settings.rst index a0866e696a..e300a08720 100644 --- a/doc/reference/reference_lua/box_space/_session_settings.rst +++ b/doc/reference/reference_lua/box_space/_session_settings.rst @@ -15,8 +15,6 @@ box.space._session_settings Every settings tuple has two fields: ``name`` (the primary key) and ``value``. The tuples' names and default values are: - * ``error_marshaling_enabled``: whether :doc:`error objects ` have - a special structure. Default: ``false``. * ``sql_default_engine``: default :ref:`storage engine ` for new SQL tables. Default: ``memtx``. * ``sql_full_column_names``: use full column names in :ref:`SQL result set metadata `. Default: ``false``. @@ -29,8 +27,10 @@ box.space._session_settings Default: ``false``. * ``sql_select_debug``: show execution steps during :ref:`SELECT `. Default:``false``. * ``sql_vdbe_debug``: for internal use. Default:``false``. - * ``sql_defer_foreign_keys``: **(removed in :doc:`2.11.0 `)** whether foreign-key checks can wait till + * ``sql_defer_foreign_keys`` (removed in :doc:`2.11.0 `): whether foreign-key checks can wait till commit. Default: ``false``. + * ``error_marshaling_enabled`` (removed in :doc:`2.10.0 `): whether :doc:`error objects ` have + a special structure. Default: ``false``. Three requests are possible: :doc:`select `, :doc:`get ` and :doc:`update `. diff --git a/doc/reference/reference_lua/checks.rst b/doc/reference/reference_lua/checks.rst index 20f4f4d5d3..cff7877566 100644 --- a/doc/reference/reference_lua/checks.rst +++ b/doc/reference/reference_lua/checks.rst @@ -1,4 +1,4 @@ -.. checks-module: +.. _checks-module: Module checks ============= diff --git a/doc/reference/reference_lua/errcodes.rst b/doc/reference/reference_lua/errcodes.rst index f92654ab01..a7539cc4b9 100644 --- a/doc/reference/reference_lua/errcodes.rst +++ b/doc/reference/reference_lua/errcodes.rst @@ -1,112 +1,136 @@ .. _error_codes: -------------------------------------------------------------------------------- Database error codes -------------------------------------------------------------------------------- +==================== -In the current version of the binary protocol, error messages, which are usually -more descriptive than error codes, are not present in server responses. The actual -message may contain a filename, a detailed reason or operating system error code. -All such messages, however, are logged in the error log. Below are general -descriptions of some popular codes. A complete list of errors can be found in file -`errcode.h `_ in the source tree. +The table below lists some popular errors that can be raised by Tarantool in case of various issues. +You can find a complete list of errors in the +`errcode.h `_ file. + +.. NOTE:: + + The :ref:`box.error ` module provides the ability to get the information about the last error raised by Tarantool or raise custom errors manually. .. container:: table - **List of error codes** - - .. rst-class:: left-align-column-1 - .. rst-class:: left-align-column-2 - - .. tabularcolumns:: |\Y{0.3}|\Y{0.7}| - - +-------------------+--------------------------------------------------------+ - | ER_NONMASTER | (In replication) A server instance cannot modify data | - | | unless it is a master. | - +-------------------+--------------------------------------------------------+ - | ER_ILLEGAL_PARAMS | Illegal parameters. Malformed protocol | - | | message. | - +-------------------+--------------------------------------------------------+ - | ER_MEMORY_ISSUE | Out of memory: | - | | :ref:`memtx_memory ` | - | | limit has been reached. | - +-------------------+--------------------------------------------------------+ - | ER_WAL_IO | Failed to write to disk. May mean: failed | - | | to record a change in the | - | | write-ahead log. Some sort of disk error. | - +-------------------+--------------------------------------------------------+ - | ER_KEY_PART_COUNT | Key part count is not the same as | - | | index part count | - +-------------------+--------------------------------------------------------+ - | ER_NO_SUCH_SPACE | The specified space does not exist. | - | | | - +-------------------+--------------------------------------------------------+ - | ER_NO_SUCH_INDEX | The specified index in the specified | - | | space does not exist. | - +-------------------+--------------------------------------------------------+ - | ER_PROC_LUA | An error occurred inside a Lua procedure. | - | | | - +-------------------+--------------------------------------------------------+ - | ER_FIBER_STACK | The recursion limit was reached when | - | | creating a new fiber. This usually | - | | indicates that a stored procedure is | - | | recursively invoking itself too often. | - +-------------------+--------------------------------------------------------+ - | ER_UPDATE_FIELD | An error occurred during update of a | - | | field. | - +-------------------+--------------------------------------------------------+ - | ER_TUPLE_FOUND | A duplicate key exists in a unique | - | | index. | - +-------------------+--------------------------------------------------------+ + .. rst-class:: left-align-column-1 + .. rst-class:: left-align-column-2 + + .. list-table:: + :widths: 25 35 40 + :header-rows: 1 + + * - Code + - box.error value + - Description + + * - ER_NONMASTER + - box.error.NONMASTER + - (In replication) A server instance cannot modify data unless it is a master. + + * - ER_ILLEGAL_PARAMS + - box.error.ILLEGAL_PARAMS + - Illegal parameters. Malformed protocol message. + + * - ER_MEMORY_ISSUE + - box.error.MEMORY_ISSUE + - Out of memory: :ref:`memtx_memory ` limit has been reached. + + * - ER_WAL_IO + - box.error.WAL_IO + - Failed to write to disk. May mean: failed to record a change in the write-ahead log. + + * - ER_READONLY + - box.error.READONLY + - Can't modify data on a read-only instance. + + * - ER_KEY_PART_COUNT + - box.error.KEY_PART_COUNT + - Key part count is not the same as index part count. + + * - ER_NO_SUCH_SPACE + - box.error.NO_SUCH_SPACE + - The specified space does not exist. + + * - ER_NO_SUCH_INDEX + - box.error.NO_SUCH_INDEX + - The specified index in the specified space does not exist. + + * - ER_PROC_LUA + - box.error.PROC_LUA + - An error occurred inside a Lua procedure. + + * - ER_FIBER_STACK + - box.error.FIBER_STACK + - The recursion limit was reached when creating a new fiber. This usually indicates that a stored procedure is recursively invoking itself too often. + + * - ER_UPDATE_FIELD + - box.error.UPDATE_FIELD + - An error occurred during update of a field. + + * - ER_TUPLE_FOUND + - box.error.TUPLE_FOUND + - A duplicate key exists in a unique index. + + .. _error_handling: -------------------------------------------------------------------------------- Handling errors -------------------------------------------------------------------------------- +--------------- Here are some procedures that can make Lua functions more robust when there are errors, particularly database errors. -1. Invoke with pcall. +1. Invoke a function using ``pcall``. + + Take advantage of Lua's mechanisms for `Error handling and exceptions `_, particularly ``pcall``. + That is, instead of invoking with ... + + .. code-block:: lua + + box.space.{space-name}:{function-name}() + + ... call the function as follows: + + .. code-block:: lua + + if pcall(box.space.{space-name}.{function-name}, box.space.{space-name}) ... + + For some Tarantool box functions, ``pcall`` also returns error details, + including a file-name and line-number within Tarantool's source code. + This can be seen by unpacking, for example: - | Take advantage of Lua's mechanisms for `"Error handling and exceptions" - `_, particularly ``pcall``. That is, - instead of simply invoking with - | :samp:`box.space.{space-name}:{function-name}()` - | say - | :samp:`if pcall(box.space.{space-name}.{function-name}, box.space.{space-name}) ...` + .. code-block:: lua - | For some Tarantool box functions, pcall also returns error details - including a file-name and line-number within Tarantool's source code. - This can be seen by unpacking. For example: - | ``x, y = pcall(function() box.schema.space.create('') end)`` - | ``y:unpack()`` + status, error = pcall(function() box.schema.space.create('') end) + error:unpack() - See the tutorial :ref:`Sum a JSON field for all tuples ` - to see how pcall can fit in an application. + See the tutorial :ref:`Sum a JSON field for all tuples ` + to see how ``pcall`` can fit in an application. -2. Examine and raise with box.error. +2. Examine errors and raise new errors using ``box.error``. - To make a new error and pass it on, the box.error module provides - :doc:`box.error(code, errtext [, errtext ...]) `. + To make a new error and pass it on, the ``box.error`` module provides + :doc:`box.error() `. - To find the last error, the box.error module provides - :doc:`/reference/reference_lua/box_error/last`. (There is also a way to find - the text of the last operating-system error for certain functions -- - :ref:`errno.strerror([code]) `.) + To find the last error, the ``box.error`` submodule provides + :doc:`/reference/reference_lua/box_error/last`. + There is also a way to find + the text of the last operating-system error for certain functions -- + :ref:`errno.strerror([code]) `. -3. Log. +3. Log. - Put messages in a log using the :ref:`log module `. + Put messages in a log using the :ref:`log module `. - And filter messages that are automatically generated, with the - :ref:`log ` configuration parameter. + Filter automatically generated messages using the + :ref:`log ` configuration parameter. Generally, for Tarantool built-in functions which are designed to return objects: -the result will be an object, or nil, or `a Lua error `_. -For example consider the :ref:`fio_read.lua ` program in our cookbook: +the result is an object, or nil, or `a Lua error `_. +For example consider the :ref:`fio_read.lua ` program in a cookbook: .. code-block:: lua diff --git a/doc/reference/reference_sql/sql_statements_and_clauses.rst b/doc/reference/reference_sql/sql_statements_and_clauses.rst index c2f12a9563..895260a50c 100644 --- a/doc/reference/reference_sql/sql_statements_and_clauses.rst +++ b/doc/reference/reference_sql/sql_statements_and_clauses.rst @@ -1712,7 +1712,6 @@ temporary system space. ``setting-name`` can have the following values: -* ``"error_marshaling_enabled"`` * ``"sql_default_engine"`` * ``"sql_full_column_names"`` * ``"sql_full_metadata"`` @@ -1721,7 +1720,8 @@ temporary system space. * ``"sql_reverse_unordered_selects"`` * ``"sql_select_debug"`` * ``"sql_vdbe_debug"`` -* ``"sql_defer_foreign_keys"`` **(removed in :doc:`2.11.0 `)** +* ``"sql_defer_foreign_keys"`` (removed in :doc:`2.11.0 `) +* ``"error_marshaling_enabled"`` (removed in :doc:`2.10.0 `) The quote marks are necessary. diff --git a/doc/release/2.4.2.rst b/doc/release/2.4.2.rst index 531aca44c3..5dfdeb1f3f 100644 --- a/doc/release/2.4.2.rst +++ b/doc/release/2.4.2.rst @@ -103,7 +103,7 @@ Lua ~~~ - Added format string usage to form a CustomError message (:tarantool-issue:`4903`). - Read more: :doc:`/reference/reference_lua/box_error/custom_type`. + Read more: :ref:`Custom error `. - Fixed error while closing socket.tcp_server socket (:tarantool-issue:`4087`). - Extended box.error objects reference counter to 64 bit to prevent possible overflow (:tarantool-issue:`4902`). diff --git a/doc/release/2.5.1.rst b/doc/release/2.5.1.rst index 777100fee6..1606d69e7d 100644 --- a/doc/release/2.5.1.rst +++ b/doc/release/2.5.1.rst @@ -156,7 +156,7 @@ Lua ~~~ - Added format string usage to form a CustomError message (:tarantool-issue:`4903`). - Read more: :doc:`/reference/reference_lua/box_error/custom_type`. + Read more: :ref:`Custom error `. - Fixed error while closing socket.tcp_server socket (:tarantool-issue:`4087`). - Extended box.error objects reference counter to 64 bit to prevent possible overflow (:tarantool-issue:`4902`). diff --git a/doc/release/major-features.rst b/doc/release/major-features.rst index df61c581e7..753736fb3a 100644 --- a/doc/release/major-features.rst +++ b/doc/release/major-features.rst @@ -120,7 +120,7 @@ Versions that only include bug fixes are not listed in this table. * - 2.4.1 - :ref:`UUID type for field and index ` (:tarantool-issue:`4268`, :tarantool-issue:`2916`) |br| :doc:`popen ` built-in module (:tarantool-issue:`4031`) |br| - Ability to create :doc:`custom error types ` (:tarantool-issue:`4398`) |br| + Ability to create :ref:`custom error types ` (:tarantool-issue:`4398`) |br| :doc:`Transparent marshalling ` through ``net.box`` (:tarantool-issue:`4398`) |br| :doc:`Stacked diagnostic area ` (:tarantool-issue:`1148`) |br| diff --git a/locale/ru/LC_MESSAGES/reference/reference_lua/box_error/error.po b/locale/ru/LC_MESSAGES/reference/reference_lua/box_error/error.po index 451734e671..bb69170e82 100644 --- a/locale/ru/LC_MESSAGES/reference/reference_lua/box_error/error.po +++ b/locale/ru/LC_MESSAGES/reference/reference_lua/box_error/error.po @@ -29,14 +29,14 @@ msgstr "(целое число) числовой код ошибки, задае msgid "" "Throw an error. This method emulates a request error, with text based on one" " of the pre-defined Tarantool errors defined in the file `errcode.h " -"`_ in the" +"`_ in the" " source tree. Lua constants which correspond to those Tarantool errors are " "defined as members of ``box.error``, for example ``box.error.NO_SUCH_USER ==" " 45``." msgstr "" "Выдача ошибки. Моделирование ошибки запроса с текстом на основе одной из " "ошибок Tarantool, заданных в файле `errcode.h " -"`_ в " +"`_ в " "исходном дереве. Lua-постоянные, которые соответствуют этим ошибкам в " "Tarantool, определяются как элементы ``box.error``, например " "``box.error.NO_SUCH_USER == 45``."