Tarantool User Guide, version 1.4.9-85-gde90a61

box.process(op, request)

Process a request passed in as a binary string. This is an entry point into the server request processor. It can be used to insert, update, select and delete tuples from within a Lua procedure.

This is a low-level API, and it expects all arguments to be packed in accordance with the binary protocol (iproto header excluded). Normally, there is no need to use box.process() directly: box.select(), box.update() and other convenience wrappers invoke box.process() with correctly packed arguments.

Parameters

op — number, any Tarantool command code, except 22 (CALL). See doc/box-protocol.txt.

request — command arguments packed in binary format.

Returns

This function returns zero or more tuples. In Lua, a tuple is represented by a userdata object of type box.tuple. If a Lua procedure is called from the administrative console, returned tuples are printed out in YAML format. When called from the binary protocol, the binary format is used.

Errors

Any server error produced by the executed command.

Please note, that since all requests from Lua enter the core through box.process(), all checks and triggers run by the core automatically apply. For example, if the server is in read-only mode, an update or delete fails. Analogously, if a system-wide "instead of" trigger is defined, it is run.

box.select(space_no, index_no, ...)

Search for a tuple or tuples in the given space. A wrapper around box.process().

Parameters

space_no — space id,

index_no — index number in the space, to be used for match

...— index key, possibly multipart.

Returns

Returns zero or more tuples.

Errors

Same as in box.process(). Any error results in a Lua exception.

Example

localhost> call box.insert(0, 'test', 'my first tuple')
Call OK, 1 rows affected
['test', 'my first tuple']
localhost> call box.select(0, 0, 'test')
Call OK, 1 rows affected
['test', 'my first tuple']
localhost> lua box.insert(5, 'testtest', 'firstname', 'lastname')
---
 - 'testtest': {'firstname', 'lastname'}
...
localhost> lua box.select(5, 1, 'firstname', 'lastname')
---
 - 'testtest': {'firstname', 'lastname'}
...

box.insert(space_no, ...)

box.select(space_no, index_no, offset, limit, ...)

Search for tuples in the given space. This is a full version of the built-in SELECT command, in which one can specify offset and limit in a multi-tuple return. The server may return multiple tuples when the index is non-unique or a partial key is used for search.

box.replace(space_no, ...)

Insert a tuple into a space. Tuple fields follow space_no. If a tuple with the same primary key already exists, box.insert() returns an error, while box.replace() replaces the existing tuple with a new one. These functions are wrappers around box.process()

Returns

Returns the inserted tuple.

box.update(space_no, key, format, ...)

Update a tuple identified by a primary key. If a key is multipart, it is passed in as a Lua table. Update arguments follow, described by format. The format and arguments are passed to box.pack() and the result is sent to box.process(). A correct format is a sequence of pairs: update operation, operation arguments. A single character of format describes either an operation which needs to take place or operation argument. A format specifier also works as a placeholder for the number of a field, which needs to be updated, or for an argument value. For example:

+p=p — add a value to one field and assign another,

:p — splice a field: start at offset, cut length bytes, and add a string.

#p — delete a field.

!p — insert a field (before the one specified).

Possible format specifiers are: “+” for addition, “-” for subtraction, “&” for bitwise AND, “|” for bitwise OR, “^” for bitwise exclusive OR (XOR), “:” for string splice and “p” for operation argument.

Returns

Returns the updated tuple.

Example

localhost> lua box.insert(0, 0, 'hello world')
---
 - 0: {'hello world'}
...
localhost> lua box.update(0, 0, '+p', 1, 1) -- add value 1 to field #1
---
error: 'Illegal parameters, numeric operation on a field with length != 4'
...
localhost> lua box.update(0, 0, '=p', 1, 1) -- assign field #1 to value 1
---
 - 0: {1}
...
localhost> lua box.update(0, 0, '+p', 1, 1)
---
 - 0: {2}
...
localhost> lua box.update(0, 2, '!p', 1, 'Bienvenue tout le monde!')
---
 - 2: {'Bienvenue tout le monde!', 'Hello world!'}
...
localhost> lua box.update(0, 2, '#p', 2, 'Bienvenue tout le monde!')
---
 - 2: {'Bienvenue tout le monde!'}
...

box.delete(space_no, ...)

Delete a tuple identified by a primary key.

Returns

Returns the deleted tuple.

Example

localhost> call box.delete(0, 'test')
Call OK, 1 rows affected
['test', 'my first tuple']
localhost> call box.delete(0, 'test')
Call OK, 0 rows affected
localhost> call box.delete(0, 'tes')
Call ERROR, Illegal parameters, key is not u32 (ER_ILLEGAL_PARAMS)

box.select_range(space_no, index_no, limit, key, ...)

Select a range of tuples, starting from offset specified by key. The key can be multipart. Limit selection with at most limit tuples. If no key is specified, start from the first key in the index.

For TREE indexes, this returns tuples in sorted order. For HASH indexes, the order of tuples is unspecified, and can change significantly if data is inserted or deleted between two calls to box.select_range(). If key is nil or unspecified, the selection starts from the start of the index. This is a simple wrapper around box.space[space_no]:select_range(index_no, ...). BITSET index does not support this call.

Example

localhost> show configuration
---
...
  space[4].cardinality: "-1"
  space[4].estimated_rows: "0"
  space[4].index[0].type: "HASH"
  space[4].index[0].unique: "true"
  space[4].index[0].key_field[0].fieldno: "0"
  space[4].index[0].key_field[0].type: "STR"
  space[4].index[1].type: "TREE"
  space[4].index[1].unique: "false"
  space[4].index[1].key_field[0].fieldno: "1"
  space[4].index[1].key_field[0].type: "STR"
...
localhost> insert into t4 values ('0', '0')
Insert OK, 1 rows affected
localhost> insert into t4 values ('1', '1')
Insert OK, 1 rows affected
localhost> insert into t4 values ('2', '2')
Insert OK, 1 rows affected
localhost> insert into t4 values ('3', '3')
Insert OK, 1 rows affected
ocalhost> lua box.select_range(4, 0, 10)
---
 - '3': {'3'}
 - '0': {'0'}
 - '1': {'1'}
 - '2': {'2'}
...
localhost> lua box.select_range(4, 1, 10)
---
 - '0': {'0'}
 - '1': {'1'}
 - '2': {'2'}
 - '3': {'3'}
...
localhost> lua box.select_range(4, 1, 2)
---
 - '0': {'0'}
 - '1': {'1'}
...
localhost> lua box.select_range(4, 1, 2, '1')
---
 - '1': {'1'}
 - '2': {'2'}
...

box.select_reverse_range(space_no, index_no, limit, key, ...)

Select a reverse range of tuples, starting from the offset specified by key. The key can be multipart. Limit selection with at most limit tuples. If no key is specified, start from the last key in the index.

For TREE indexes, this returns tuples in sorted order. Other index types do not support this call. If key is nil or unspecified, the selection starts from the end of the index.

Example

localhost> show configuration
---
...
  space[4].cardinality: "-1"
  space[4].estimated_rows: "0"
  space[4].index[0].type: "HASH"
  space[4].index[0].unique: "true"
  space[4].index[0].key_field[0].fieldno: "0"
  space[4].index[0].key_field[0].type: "STR"
  space[4].index[1].type: "TREE"
  space[4].index[1].unique: "false"
  space[4].index[1].key_field[0].fieldno: "1"
  space[4].index[1].key_field[0].type: "STR"
...
localhost> insert into t4 values ('0', '0')
Insert OK, 1 rows affected
localhost> insert into t4 values ('1', '1')
Insert OK, 1 rows affected
localhost> insert into t4 values ('2', '2')
Insert OK, 1 rows affected
localhost> insert into t4 values ('3', '3')
Insert OK, 1 rows affected
localhost> lua box.select_reverse_range(4, 0, 10)
---
 error: 'Illegal parameters, hash iterator is forward only
...
localhost> lua box.select_reverse_range(4, 1, 10)
---
 - '3': {'3'}
 - '2': {'2'}
 - '1': {'1'}
 - '0': {'0'}
...
localhost> lua box.select_reverse_range(4, 1, 2)
---
 - '3': {'3'}
 - '2': {'2'}
...
localhost> lua box.select_reverse_range(4, 1, 2, '1')
---
 - '1': {'1'}
 - '0': {'0'}
...

box.pack(format, ...)

To use Tarantool binary protocol primitives from Lua, it's necessary to convert Lua variables to binary format. This helper function is prototyped after Perl 'pack'. It takes a format and a list of arguments, and returns a binary string with all arguments packed according to the format.

Format specifiers

b — converts Lua variable to a 1-byte integer, and stores the integer in the resulting string

s — converts Lua variable to a 2-byte integer, and stores the integer in the resulting string, low byte first,

i — converts Lua variable to a 4-byte integer, and stores the integer in the resulting string, low byte first,

l — converts Lua variable to a 8-byte integer, and stores the integer in the resulting string, low byte first,

w — converts Lua integer to a BER-encoded integer,

p — stores the length of the argument as a BER-encoded integer followed by the argument itself (a 4-bytes for integers (LE order) and a binary blob for other types),

=, +, &, |, ^, : — stores the corresponding Tarantool UPDATE operation code: field assignment, addition, conjunction, disjunction, exclusive disjunction, splice (from Perl SPLICE function). Expects field number to update as an argument. These format specifiers only store the corresponding operation code and field number to update, but do not describe operation arguments.

Errors

Unknown format specifier.

Example

localhost> lua box.insert(0, 0, 'hello world')
---
 - 0: {'hello world'}
...
localhost> lua box.update(0, 0, "=p", 1, 'bye world')
---
 - 0: {'bye world'}
...
localhost> lua box.update(0, 0, ":p", 1, box.pack('ppp', 0, 3, 'hello'))
---
 - 0: {'hello world'}
...
localhost> lua box.update(0, 0, "=p", 1, 4)
---
 - 0: {4}
...
localhost> lua box.update(0, 0, "+p", 1, 4)
---
 - 0: {8}
...
localhost> lua box.update(0, 0, "^p", 1, 4)
---
 - 0: {12}
...

box.unpack(format, binary)

Counterpart to box.pack().

Example

localhost> lua tuple=box.replace(2, 0)
---
...
localhost> lua string.len(tuple[0])
---
 - 4
...
localhost> lua box.unpack('i', tuple[0])
---
 - 0
...
localhost> lua box.unpack('bsil', box.pack('bsil', 255, 65535, 4294967295, tonumber64('18446744073709551615')))
---
 - 255
 - 65535
 - 4294967295
 - 18446744073709551615
...
localhost> lua num, str, num64 = box.unpack('ppp', box.pack('ppp', 666, 'string', tonumber64('666666666666666')))
---
...
localhost> lua print(box.unpack('i', num));
---
666
...
localhost> lua print(str);
---
string
...
localhost> lua print(box.unpack('l', num64))
---
666666666666666
...
localhost> lua box.unpack('=p', box.pack('=p', 1, '666'))
---
 - 1
 - 666

box.print(...)

Redefines Lua print() built-in to print either to the log file (when Lua is used from the binary port) or back to the user (for the administrative console).

When printing to the log file, INFO log level is used. When printing to the administrative console, all output is sent directly to the socket.

Note: the administrative console output must be YAML-compatible.

box.dostring(s, ...)

Evaluates an arbitrary chunk of Lua code passed in s. If there is a compilation error, it's raised as a Lua error. In case of compilation success, all arguments which follow s are passed to the compiled chunk and the chunk is invoked.

This function is mainly useful to define and run an arbitrary piece of Lua code, without having to introduce changes to the global Lua environment.

Example

lua box.dostring('abc')
---
error: '[string "abc"]:1: ''='' expected near ''<eof>'''
...
lua box.dostring('return 1')
---
 - 1
...
lua box.dostring('return ...', 'hello', 'world')
---
 - hello
 - world
...
lua box.dostring('local f = function(key) t=box.select(0, 0, key); if t ~= nil then return t[0] else return nil end end return f(...)', 0)
---
 - nil
...

box.time()

Returns current system time (in seconds) as a Lua number. The time is taken from the event loop clock, which makes this call very cheap, but still useful for constructing artificial tuple keys.

box.time64()

Returns current system time (in seconds) as a 64-bit integer. The time is taken from the event loop clock.

box.uuid()

Generate 128-bit (16 bytes) unique id. The id is returned in binary form.

Requires libuuid library to be installed. The library is loaded in runtime, and if the library is not available, this function returns an error.

box.uuid_hex()

Generate hex-string of 128-bit (16 bytes) unique id. Return 32-bytes string.

Example

                lua box.uuid_hex()
                ---
                 - a4f29fa0eb6d11e19f7737696d7fa8ff
                ...
            

box.raise(errcode, errtext)

Raises a client error. The difference between this function and the built-in error() function in Lua is that when the error reaches the client, it's error code is preserved, whereas every Lua error is presented to the client as ER_PROC_LUA. This function makes it possible to emulate any kind of native exception, such as a unique constraint violation, no such space/index, etc. A complete list of errors is present in errcode.h file in the source tree. Lua constants which correspond to Tarantool errors are defined in box.error module. The error message can be arbitrary. Throws client error. Lua procedure can emulate any request errors (for example: unique key exception).

Example

                lua box.raise(box.error.ER_WAL_IO, 'Wal I/O error')
                ---
                error: 'Wal I/O error'
                ...
            

box.auto_increment(space_no, ...)

Insert values into space designated by space_no, using an auto-increment primary key. The space must have a NUM or NUM64 primary key index of type TREE.

Example

localhost> lua box.auto_increment(0, "I am a duplicate")
---
 - 1: {'I am a duplicate'}
...
localhost> lua box.auto_increment(0, "I am a duplicate")
---
 - 2: {'I am a duplicate'}
...
            

box.counter.inc(space_no, key)

Increments a counter identified by the key. The key can be multi-part, but there must be an index covering all fields of the key. If there is no tuple identified by the given key, creates a new one with initial counter value set to 1. Returns the new counter value back.

Example

localhost> lua box.counter.inc(0, 'top.mail.ru')
---
 - 1
...
localhost> lua box.counter.inc(0, 'top.mail.ru')
---
 - 2
...

box.counter.dec(space_no, key)

Decrements a counter identified by the given key. If the key is not found, is a no-op. When counter value drops to 0, the tuple is deleted.

Example

localhost> lua box.counter.dec(0, 'top.mail.ru')
---
 - 1
...
localhost> lua box.counter.dec(0, 'top.mail.ru')
---
 - 0
...

The package stands for box.tuple userdata type. It is possible to access individual tuple fields using an index, select a range of fields, iterate over all fields in a tuple or convert a tuple to a Lua table. Tuples are immutable.

Example

localhost> lua t=box.insert(0, 1, 'abc', 'cde', 'efg', 'ghq', 'qkl')
---
...
localhost> lua #t
---
 - 6
...
localhost> lua t[1], t[5]
---
 - abc
 - qkl
...
localhost> lua t[6]
---
error: 'Lua error: [string "return t[6]"]:1: box.tuple: index 6 is out of bounds (0..5)'
...
localhost> lua for k,v in t:pairs() do print(v) end
---

abc
cde
efg
ghq
qkl
...
localhost> lua t:unpack()
---
 -
 - abc
 - cde
 - efg
 - ghq
 - qkl
...
localhost> lua t:slice(1, 2)
---
 - abc
...
localhost> lua t:slice(1, 3)
---
 - abc
 - cde
...
localhost> lua t:slice(1, -1)
---
 - abc
 - cde
 - efg
 - ghq
...
localhost> lua t:transform(1, 3)
---
 - 1: {'ghq', 'qkl'}
...
localhost> lua t:transform(0, 1, 'zyx')
---
 - 'zyx': {'abc', 'cde', 'efg', 'ghq', 'qkl'}
...
localhost> lua t:transform(-1, 1, 'zyx')
---
 - 1: {'abc', 'cde', 'efg', 'ghq', 'zyx'}
...
localhost> lua t=box.insert(0, 'abc', 'def', 'abc')
---
...
localhost> lua t:find('abc')
---
 - 0
...
localhost> lua t:findall('abc')
---
 - 0
 - 2
...
localhost> lua t:find(1, 'abc')
---
 - 2
...

box.tuple.new(...)

Construct a new tuple from a Lua table or a scalar.

Example

localhost> lua box.tuple.new({tonumber64('18446744073709551615'), 'string', 1})
---
 - 18446744073709551615: {'string', 1}
...

This package is a container for all configured spaces. A space object provides access to space attributes, such as id, whether or not a space is enabled, space cardinality, estimated number of rows. It also contains object-oriented versions of box functions. For example, instead of box.insert(0, ...) one can write box.space[0]:insert(...). Package source code is available in file src/box/box.lua

A list of all space members follows.

space.n

Ordinal space number, box.space[i].n == i

space.enabled

Whether or not this space is enabled in the configuration file.

space.cardinality

A limit on tuple field count for tuples in this space. This limit can be set in the configuration file. Value 0 stands for “unlimited”.

space.index[]

A container for all defined indexes. An index is a Lua object of type box.index with methods to search tuples and iterate over them in predefined order.

space:select(index_no, ...)

space:select_range(index_no, limit, key)

Select a range of tuples, starting from offset specified by key. The key can be multipart. Limit selection with at most limit tuples. If no key is specified, start from the first key in the index.

For TREE indexes, this returns tuples in sorted order. For other indexes, the order of tuples is unspecified, and can change significantly if data is inserted or deleted between two calls to select_range(). If key is nil or unspecified, the selection starts from the start of the index.

space:select_reverse_range(limit, key)

Select a reverse range of tuples, limited by limit, starting from key. The key can be multipart. TREE index returns tuples in descending order. Other index types do not support this call.

space:insert(...)

space:replace(...)

space:delete(key)

space:update(key, format, ...)

space:insert(...)

Object-oriented forms of respective box methods.

space:len()

Returns number of tuples in the space.

space:truncate()

Deletes all tuples.

space:pairs()

A helper function to iterate over all space tuples, Lua style.

Example

localhost> lua for k,v in box.space[0]:pairs() do print(v) end
---
1: {'hello'}
2: {'my     '}
3: {'Lua    '}
4: {'world'}
...

This package implements methods of type box.index. Indexes are contained in box.space[i].index[] array within each space object. They provide an API for ordered iteration over tuples. This API is a direct binding to corresponding methods of index objects in the storage engine.

index.unique

Boolean, true if the index is unique.

index.type

A string for index type, either 'TREE', 'HASH', 'BITSET'.

index.key_field[]

An array describing index key fields.

index.idx

The underlying userdata which does all the magic.

index:iterator(type, ...)

This method provides iteration support within an index. Parameter type is used to identify the semantics of iteration. Different index types support different iterators. The remaining arguments of the function are varying and depend on the iteration type. For example, TREE index maintains a strict order of keys and can return all tuples in ascending or descending order, starting from the specified key. Other index types, however, do not support ordering.

To understand consistency of tuples, returned by an iterator, it's essential to know the principles of the Tarantool transaction processing subsystem. An iterator in Tarantool does not own a consistent read view. Instead, each procedure is granted exclusive access to all tuples and spaces until it encounters a "context switch": caused a write to disk, network, or by an explicit call to box.fiber.yield(). When the execution flow returns to the yielded procedure, the data set could have changed significantly. Iteration, resumed after a yield point, does not preserve the read view, but continues with the new content of the database.

Parameters

type — iteration strategy as defined in tables below.

Returns

This method returns an iterator closure, i.e. a function which can be used to get the next value on each invocation.

Errors

Selected iteration type is not supported in the subject index type or supplied parameters do not match iteration type.

Table 4.1. Common iterator types

Type	Arguments	HASH	TREE	BITSET	Description
box.index.ALL	none	yes	yes	yes	Iterate over all tuples in an index. When iterating over a TREE index, tuples are returned in ascending order of the key. When iterating over a HASH or BITSET index, tuples are returned in physical order or, in other words, unordered.
box.index.EQ	key	yes	yes	yes	Equality iterator: iterate over all tuples matching the key. Parts of a multipart key need to be separated by comma. Semantics of the match depends on the index. A HASH and TREE index only supports exact match: all parts of a key participating in the index must be provided. In case of TREE index, only few parts of a key or a key prefix are accepted for search. In this case, all tuples with the same prefix or matching key parts are considered matching the search criteria. A non-unique HASH index returns tuples in unspecified order. When a TREE index is not unique, or only part of a key is given as a search criteria, matching tuples are returned in ascending order. BITSET indexes are always unique.
box.index.GT	key	yes (*)	yes	no	Iterate over tuples strictly greater than the search key. For TREE indexes, a key prefix or key part can be sufficient. If the key is nil, iteration starts from the smallest key in the index. The tuples are returned in ascending order of the key. HASH index also supports this iterator type, but returns tuples in unspecified order. However, if the server does not receive updates, this iterator can be used to retrieve all tuples via a HASH index piece by piece, by supplying the last key from the previous range as the start key for an iterator over the next range. BITSET index does not support this iteration type yet.

Table 4.2. TREE iterator types

Type	Arguments	Description
box.index.REQ	key or key part	Reverse equality iterator. Is equivalent to box.index.EQ with only distinction that the order of returned tuples is descending, not ascending.
box.index.GE	key or key part	Iterate over all tuples for which the corresponding fields are greater or equal to the search key. The tuples are returned in ascending order. Similarly to box.index.EQ, key prefix or key part can be used to seed the iterator. If the key is nil, iteration starts from the smallest key in the index.
box.index.LT	key or key part	Similar to box.index.GT, but returns all tuples which are strictly less than the search key. The tuples are returned in the descending order of the key. nil key can be used to start from the end of the index range.
box.index.LE	key or key part	Similar to box.index.GE, but returns all tuples which are less or equal to the search key or key prefix, and returns tuples in descending order, from biggest to smallest. If the key is nil, iteration starts from the end of the index range.

Table 4.3. BITSET iterator types

Type	Arguments	Description
box.index.BITS_ALL_SET	bit mask	Matches tuples in which all specified bits are set.
box.index.BITS_ANY_SET	bit mask	Matches tuples in which any of the specified bits is set.
box.index.BITS_ALL_NOT_SET	bit mask	Matches tuples in which none of the specified bits is set.

Examples

localhost> show configuration
---
...
  space[0].enabled: "true"
  space[0].index[0].type: "HASH"
  space[0].index[0].unique: "true"
  space[0].index[0].key_field[0].fieldno: "0"
  space[0].index[0].key_field[0].type: "NUM"
  space[0].index[1].type: "TREE"
  space[0].index[1].unique: "false"
  space[0].index[1].key_field[0].fieldno: "1"
  space[0].index[1].key_field[0].type: "NUM"
  space[0].index[1].key_field[1].fieldno: "2"
  space[0].index[1].key_field[1].type: "NUM"
...
localhost> INSERT INTO t0 VALUES (1, 1, 0)
Insert OK, 1 rows affected
localhost> INSERT INTO t0 VALUES (2, 1, 1)
Insert OK, 1 rows affected
localhost> INSERT INTO t0 VALUES (3, 1, 2)
Insert OK, 1 rows affected
localhost> INSERT INTO t0 VALUES (4, 2, 0)
Insert OK, 1 rows affected
localhost> INSERT INTO t0 VALUES (5, 2, 1)
Insert OK, 1 rows affected
localhost> INSERT INTO t0 VALUES (6, 2, 2)
Insert OK, 1 rows affected
localhost> lua it = box.space[0].index[1]:iterator(box.index.EQ, 1); print(it(), " ", it(), " ", it());
---
1: {1, 0} 2: {1, 1} 3: {1, 2}
...
localhost> lua it = box.space[0].index[1]:iterator(box.index.EQ, 1, 2); print(it(), " ", it(), " ", it());
---
3: {1, 2} nil nil
...
localhost> lua i = box.space[0].index[1]:iterator(box.index.GE, 2, 1);  print(it(), " ", it(), " ", it());
---
5: {2, 1} 6: {2, 2} nil
...
localhost> lua for v in box.space[0].index[1]:iterator(box.index.ALL) do print(v) end
---
1: {1, 0}
2: {1, 1}
3: {1, 2}
4: {2, 0}
5: {2, 1}
6: {2, 2}
...
localhost> lua i = box.space[0].index[0]:iterator(box.index.LT, 1);
---
error: 'Iterator type is not supported'

index:min()

The smallest value in the index. Available only for indexes of type 'TREE'.

index:max()

The biggest value in the index. Available only for indexes of type 'TREE'.

index:random(randint)

Return a random value from an index. A random non-negative integer must be supplied as input, and a value is selected accordingly in index-specific fashion. This method is useful when it's important to get insight into data distribution in an index without having to iterate over the entire data set.

index:count()

Iterate over an index, count the number of tuples which equal the provided search criteria. The argument can either point to a tuple, a key, or one or more key parts. Returns the number of matched tuples.

box.fiber.id(fiber)

Return a numeric id of the fiber.

box.fiber.self()

Return box.fiber userdata object for the currently scheduled fiber.

box.fiber.find(id)

Locate a fiber userdata object by id.

box.fiber.create(function)

Create a fiber for function.

Errors

Can hit a recursion limit.

box.fiber.resume(fiber, ...)

Resume a created or suspended fiber.

box.fiber.yield(...)

Yield control to the calling fiber, if the fiber is attached, or to sched otherwise.

If the fiber is attached, whatever arguments are passed to this call, are passed on to the calling fiber. If the fiber is detached, box.fiber.yield() returns back everything passed into it.

box.fiber.detach()

Detach the current fiber. This is a cancellation point. This is a yield point.

box.fiber.sleep(time)

Yield to the sched fiber and sleep time seconds. Only the current fiber can be made to sleep.

box.fiber.cancel(fiber)

Cancel a fiber. Running and suspended fibers can be canceled. Returns an error if the subject fiber does not permit cancel.

box.fiber.testcancel()

Check if the current fiber has been canceled and throw an exception if this is the case.

box.session.id()

Return a unique monotonic identifier of the current session. The identifier can be used to check whether or not a session is alive. 0 means there is no session (e.g. a procedure is running in a detached fiber).

box.session.fd(id)

Return an integer file descriptor associated with the connected client.

box.session.exists(id)

Return true if a session is alive, false otherwise.

box.ipc.channel(capacity)

Create a new communication channel with predefined capacity. The channel can be used to synchronously exchange messages between stored procedures. The channel is garbage collected when no one is using it, just like any other Lua object. Channels can be worked with using functional or object-oriented syntax. For example, the following two lines are equivalent:

    channel:put(message)
    box.ipc.channel.put(channel, message)

box.ipc.channel.put(channel, message, timeout)

Send a message using a channel. If the channel is full, box.ipc.channel.put() blocks until there is a free slot in the channel. If timeout is provided, and the channel doesn't become empty for the duration of the timeout, box.ipc.channel.put() returns false. Otherwise it returns true.

box.ipc.channel.get(channel, timeout)

Fetch a message from a channel. If the channel is empty, box.ipc.channel.get() blocks until there is a message. If timeout is provided, and there are no new messages for the duration of the timeout, box.ipc.channel.get() returns error.

box.ipc.channel.broadcast(channel, message, timeout)

If the channel is empty, is equivalent to box.ipc.channel.put(). Otherwise sends the message to all readers of the channel.

box.ipc.channel.is_empty(channel)

Check if the channel is empty (has no messages).

box.ipc.channel.is_full(channel)

Check if the channel is full (has no room for a new message).

box.ipc.channel.has_readers(channel)

Check if the channel is empty and has readers waiting for a message.

box.ipc.channel.has_writers(channel)

Check if the channel is full and has writers waiting for empty room.

Example

local channel = box.ipc.channel(10)
function consumer_fiber()
    while true do
        local task = channel:get()
        ...
    end
end

function consumer2_fiber()
    while true do
        local task = channel:get(10)        -- 10 seconds
        if task ~= nil then
            ...
        else
            print("timeout!")
        end
    end
end

function producer_fiber()
    while true do
        task = box.select(...)
        ...
        if channel:is_empty() then
            # channel is empty
        end

        if channel:is_full() then
            # channel is full
        end

        ...
        if channel:has_readers() then
            # there are some fibers that wait data
        end
        ...

        if channel:has_writers() then
            # there are some fibers that wait readers
        end
        channel:put(task)
    end
end

function producer2_fiber()
    while true do
        task = box.select(...)

        if channel:put(task, 10) then       -- 10 seconds
            ...
        else
            print("timeout!")
        end
    end
end

BSD sockets is a mechanism to exchange data with a local or remote host in connection-oriented (TCP) or datagram-oriented (UDP) mode. Semantics of the calls in box.socket API closely follows semantics of the corresponding POSIX calls. Function names and signatures are mostly compatible with luasocket.

Similarly to luasocket, box.socket doesn't throw exceptions on errors. On success, most calls return a socket object. On error, a multiple return of nil, status, errno, errstr is produced. Status can be one of "error", "timeout", "eof" or "limit". On success, status is always nil. A call which returns data (recv(), recvfrom(), readline()) on success returns a Lua string of the requested size and nil status. On error or timeout, an empty string is followed by the corresponding status, error number and message. A call which sends data (send(), sendto()) on success returns the number of bytes sent, and the status is, again, nil. On error or timeout 0 is returned, followed by status, error number and message.

The last error can be retrieved from the socket using socket:error(). Any call except error() clears the last error first (but may set a new one).

Calls which require a socket address and in POSIX expect struct sockaddr_in, in box.socket simply accept host name and port as additional arguments. Name resolution is done automatically. If it fails, status is set to "error", errno is set to -1 and error string is set to "Host name resolution failed".

All calls that can take time block the calling fiber and can get it preempted. The implementation, however, uses non-blocking cooperative I/O, so Tarantool continues processing queries while a call is blocked. A timeout can be provided for any socket call which can take a long time.

As all other box libraries, the API can be used in procedural style (e.g. box.socket.close(socket)) as well as in object-oriented style (socket:close()).

A closed socket should not be used any more. Alternatively, the socket will be closed when its userdata is garbage collected by Lua.

box.socket.tcp()

Create a new TCP socket.

Returns

A new socket or nil.

box.socket.udp()

Create a new UDP socket.

Returns

A new socket or nil.

socket:connect(host, port, [timeout])

Connect a socket to a remote host. Can be used with IPv6 and IPv4 addresses, as well as domain names. If multiple addresses correspond to a domain, tries them all until successfully connected.

Returns

Returns a connected socket on success, nil, status, errno, errstr on error or timeout.

socket:send(data, [timeout])

Send data over a connected socket.

Returns

The number of bytes sent. On success, this is exactly the length of data. In case of error or timeout, returns the number of bytes sent before error, followed by status, errno, errstr.

socket:recv(size, [timeout])

Read size bytes from a connected socket. An internal read-ahead buffer is used to reduce the cost of this call.

Returns

A string of the requested length on success. On error or timeout, returns an empty string, followed by status, errno, errstr. If there was some data read before a timeout occurred, it will be available on the next call. In case the writing side has closed its end, returns the remainder read from the socket (possibly an empty string), followed by "eof" status.

socket:readline([limit], [separator list], [timeout])

Read a line from a connected socket.

socket:readline() with no arguments reads data from a socket until '\n' or eof. If a limit is set, the call reads data until a separator is found, or the limit is reached. By default, there is no limit. Instead of the default separator, a Lua table can be used with one or multiple separators. Then the data is read until the first matching separator is found.

Returns

A Lua string with data in case of success or an empty string in case of error. When multiple separators were provided in a separator table, the matched separator is returned as the third argument.

Table 4.4. readline() returns

data, nil, separator	success
"", "timeout", ETIMEDOUT, errstr	timeout
"", "error", errno, errstr	error
data, "limit"	limit
data, "eof"	eof

socket:bind(host, port[, timeout])

Bind a socket to the given host/port. A UDP socket after binding can be used to receive data (see recvfrom()). A TCP socket can be used to accept new connections, after it's been put in listen mode. The timeout is used for name resolution only. If host name is an IP address, the call never yields and the timeout is unused.

Returns

Socket object on success, nil, status, errno, errstr on error.

socket:listen()

Start listening for incoming connections. The listen backlog, on Linux, is taken from /proc/sys/net/core/somaxconn, whereas on BSD is set to SOMAXCONN.

Returns

Socket on success, nil, "error", errno, errstr on error.

socket:accept([timeout])

Wait for a new client connection and create a connected socket.

Returns

peer_socket, nil, peer_host, peer_port on success. nil, status, errno, errstr on error.

socket:sendto(data, host, port, [timeout])

Send a message on a UDP socket to a specified host.

Returns

The number of bytes sent on success, 0, status, errno, errstr on error or timeout.

socket:recvfrom(limit[, timeout])

Receive a message on a UDP socket.

Returns

Message, nil, client address, client port on success, "", status, errno, errstr on error or timeout.

socket:shutdown(how)

Shutdown a reading, writing or both ends of a socket. Accepts box.socket.SHUT_RD, box.socket.SHUT_WR and box.socket.SHUT_RDWR.

Returns

Socket on success, nil, "error", errno, errstr on error.

socket:close()

Close (destroy) a socket. A closed socket should not be used any more.

socket:error()

Retrieve the last error occurred on a socket.

Returns

errno, errstr. 0, "Success" if there is no error.

Package box.cfg

This package provides read-only access to all server configuration parameters.

box.cfg

Example

localhost> lua for k, v in pairs(box.cfg) do print(k, " = ", v) end
---
io_collect_interval = 0
pid_file = box.pid
panic_on_wal_error = false
slab_alloc_factor = 2
slab_alloc_minimal = 64
admin_port = 33015
logger = cat - >> tarantool.log
...

Package box.info

This package provides access to information about server variables: pid, uptime, version and such. Its contents is identical to output of SHOW INFO.

box.info()

Since contents of box.info is dynamic, it's not possible to iterate over keys with Lua pairs() function. For this purpose, box.info() builds and returns a Lua table with all keys and values provided in the package.

Example

localhost> lua for k,v in pairs(box.info()) do print(k, ": ", v) end
---
version: 1.4.7-92-g4ba95ca
status: primary
pid: 1747
lsn: 1712
recovery_last_update: 1306964594.980
recovery_lag: 0.000
uptime: 39
build: table: 0x419cb880
logger_pid: 1748
config: /home/unera/work/tarantool/test/box/tarantool_good.cfg
...

box.info.status, box.info.pid, box.info.lsn, ...

Example

localhost> lua box.info.pid
---
 - 1747
...
localhost> lua box.info.logger_pid
---
 - 1748
...
localhost> lua box.info.version
---
 - 1.4.7-92-g4ba95ca
...
localhost> lua box.info.config
---
 - /home/unera/work/tarantool/test/box/tarantool_good.cfg
...
localhost> lua box.info.uptime
---
 - 3672
...
localhost> lua box.info.lsn
---
 - 1712
...
localhost> lua box.info.status
---
 - primary
...
localhost> lua box.info.recovery_lag
---
 - 0.000
...
localhost> lua box.info.recovery_last_update
---
 - 1306964594.980
...
localhost> lua box.info.snapshot_pid
---
 - 0
...
localhost> lua for k, v in pairs(box.info.build) do print(k .. ': ', v) end
---
flags:  -D_GNU_SOURCE -D_FILE_OFFSET_BITS=64 -DCORO_ASM -fno-omit-frame-pointer -fno-stack-protector -fexceptions -funwind-tables -fgnu89-inline -pthread  -Wno-sign-compare -Wno-strict-aliasing -std=gnu99 -Wall -Wextra -Werror
target: Linux-x86_64-Debug
compiler: /usr/bin/gcc
options: cmake . -DCMAKE_INSTALL_PREFIX=/usr/local -DENABLE_STATIC=OFF -DENABLE_GCOV=OFF -DENABLE_TRACE=ON -DENABLE_BACKTRACE=ON -DENABLE_CLIENT=OFF
...

Package box.slab

This package provides access to slab allocator statistics.

box.slab

Example

localhost> lua box.slab.arena_used
---
 - 4194304
...
localhost> lua box.slab.arena_size
---
 - 104857600
...
localhost> lua for k, v in pairs(box.slab.slabs) do print(k) end
---
64
128
...
localhost> lua for k, v in pairs(box.slab.slabs[64]) do print(k, ':', v) end
---
items:1
bytes_used:160
item_size:64
slabs:1
bytes_free:4194144
...

Package box.stat

This package provides access to request statistics.

box.stat

Example

localhost> lua box.stat -- a virtual table
---
 - table: 0x41a07a08
...
localhost> lua box.stat() -- a full table (the same)
---
 - table: 0x41a0ebb0
...
localhost> lua for k, v in pairs(box.stat()) do print(k) end
---
DELETE
SELECT
REPLACE
CALL
UPDATE
DELETE_1_3
...
localhost> lua for k, v in pairs(box.stat().DELETE) do print(k, ': ', v) end
---
total: 23210
rps: 22
...
localhost> lua for k, v in pairs(box.stat.DELETE) do print(k, ': ', v) end -- the same
---
total: 23210
rps: 22
...
localhost> lua for k, v in pairs(box.stat.SELECT) do print(k, ': ', v) end
---
total: 34553330
rps: 23
...
localhost>

box.session.on_connect(chunk)

Set a callback (trigger) invoked on each connected session. The callback doesn't get any arguments, but is the first thing invoked in the scope of the newly created session. If the trigger fails by raising an error, the error is sent to the client and the connection is shut down. Returns the old value of the trigger.

Warning

If a trigger always results in an error, it may become impossible to connect to the server to reset it.

box.session.on_disconnect(chunk)

Set a trigger invoked after a client has disconnected. Returns the old value of the trigger. If the trigger raises an error, the error is logged but otherwise is ignored. The trigger is invoked while the session associated with the client still exists and can access session properties, such as id.