ldoc

Contents

• Functions
• Functions (shortcuts)
• Class error_class
• Class error_object
• Tools for API deprecation

Modules

• errors

Topics

• README
• CHANGELOG

Module errors

Convenient error handling in Tarantool.

Functions

is_error_object (obj)	Check if the argument is an error object.
new_class (class_name[, options])	Create new error class.
netbox_eval (conn, code[, arguments[, options]])	Do protected net.box evaluation.
netbox_call (conn, function_name[, arguments[, options]])	Perform protected net.box call.
netbox_wait_async (future, timeout)	Wait for result from async net.box call / eval.
wrap ([...])	Postprocess arguments.

Functions (shortcuts)

new (class_name[, level], fmt[, ...])	Shortcut for error_class:new.
pcall (class_name, fn[, ...])	Shortcut for error_class:pcall.
assert (class_name, cond[, ...])	Shortcut for error_class:assert.

Class error_class

error_class:new ([level], fmt[, ...])	Create error object.
error_class:pcall (fn[, ...])	Perform protected Lua call, gathering error as object.
error_class:assert (cond[, ...])	Raise an error object unless condition is true.

Class error_object

error_object:tostring ()

Get string representation.

Tools for API deprecation

deprecate (message)	Issue deprecation error.
set_deprecation_handler (fn)	Set new deprecation handler.

Functions

is_error_object (obj)

Check if the argument is an error object.

The check is positive if it's a table with mandatory fields: err, str, line, file, class_name. Their types aren't checked. Other fields are ignored.

Parameters:

• obj

Returns:

boolean true/false

new_class (class_name[, options])

Create new error class.

Parameters:

• class_name string
• options
  • capture_stack boolean Capture backtrace at creation. (default: true)
  • log_on_creation boolean Produce error log at creation. (default: false)

Returns:

error_class

netbox_eval (conn, code[, arguments[, options]])

Do protected net.box evaluation. Execute code on remote server using Tarantool built-in net.box conn:eval. Additionally postprocess returned values with wrap.

Parameters:

• conn net.box connection object
• code string
• arguments passed to net.box eval (optional)
• options passed to net.box eval (optional)

Returns:

Postprocessed conn:eval() result

Or

1. nil
2. error_object Error description

See also:

netbox_call

netbox_call (conn, function_name[, arguments[, options]])

Perform protected net.box call. Similar to netbox_eval, execute code on remote server using Tarantool built-in net.box conn:call. Additionally postprocess returned values with wrap.

Parameters:

• conn net.box connection object
• function_name string
• arguments passed to net.box call (optional)
• options passed to net.box call (optional)

Returns:

Postprocessed conn:call() result

Or

1. nil
2. error_object Error description

See also:

netbox_eval

netbox_wait_async (future, timeout)

Wait for result from async net.box call / eval.

Additionally postprocess returned values with wrap.

Parameters:

• future net.box future object
• timeout number

Returns:

Postprocessed future:wait_result() result

Or

1. nil
2. error_object Error description

See also:

• netbox_call
• netbox_eval

wrap ([...])

Postprocess arguments. Mostly useful for postprocessing net.box and vshard call results.

• Substitute all box.NULL with nil;
• Repair metatables of error objects because they are not transfered over network;
• Extend stacktrace of remote call if possible;

Parameters:

• ... (optional)

Returns:

Postprocessed values

Functions (shortcuts)

new (class_name[, level], fmt[, ...])

Shortcut for error_class:new.

errors.new_class(class_name):new(...)

Parameters:

• class_name string
• level number (optional)
• fmt string
• ... (optional)

pcall (class_name, fn[, ...])

Shortcut for error_class:pcall. Equivalent for

errors.new_class(class_name):pcall(...)

Parameters:

• class_name string
• fn function
• ... (optional)

assert (class_name, cond[, ...])

Shortcut for error_class:assert.

errors.new_class(class_name):assert(...)

Parameters:

• class_name string
• cond condition to be checked
• ... error_class:new args (optional)

Class error_class

error_class:new ([level], fmt[, ...])

Create error object. Error payload is formatted by string.format

Parameters:

• level number within the meaning of Lua debug.getinfo(level) (optional)
• fmt string used for string.format(fmt, ...)
• ... formatting arguments (optional)

Returns:

error_object

error_class:pcall (fn[, ...])

Perform protected Lua call, gathering error as object.

Parameters:

• fn function called function
• ... call arguments (optional)

Returns:

fn(...) if the call succeeds without errors

Or

1. nil
2. error_object

error_class:assert (cond[, ...])

Raise an error object unless condition is true.

Parameters:

• cond condition to be checked
• ... error_class:new args (optional)

Returns:

1. cond
2. ...

Raises:

(error_object) error_class:new(...)

Class error_object

error_object:tostring ()

Get string representation. Including class_name and err. And optional stack, if it was not disabled for this class.

Returns:

string

Tools for API deprecation

deprecate (message)

Issue deprecation error. Do it once for every location in code, which points on the second-level caller.

Parameters:

• message string

Returns:

error_object

set_deprecation_handler (fn)

Set new deprecation handler. It may be used in tests and development environment to turn warnings into noticable errors.

By default (if handler is nil) all errors are logged using log.warn().

Parameters:

• fn nil or functon