diff --git a/.gitignore b/.gitignore
index 01cc0a4774c006cf51c031a14c1c96d4a0ceede9..290c2d0411137d37dd3f4ca158cafc232dc76b37 100644
--- a/.gitignore
+++ b/.gitignore
@@ -63,3 +63,7 @@ third_party/luajit/src/lj_recdef.h
third_party/luajit/src/lj_vm.s
VERSION
src/00000000000000000001.snap
+
+doc/sphinx/_build/*
+!doc/sphinx/_build/.gitignore
+doc/www/content/doc
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 1bfa06173cd573bfb44180db296977c38a2d56c6..d0ea9006d5f1ba8a17d78233c13df963f9220a0d 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -44,7 +44,6 @@ include(GNUInstallDirs)
include(cmake/utils.cmake)
include(cmake/pod2man.cmake)
-
# the order is significant: we need to know os and compiler to configure libs
include(cmake/arch.cmake)
include(cmake/os.cmake)
@@ -52,6 +51,7 @@ include(cmake/compiler.cmake)
include(cmake/simd.cmake)
include(cmake/profile.cmake)
include(cmake/FindReadline.cmake)
+include(cmake/FindSphinx.cmake)
include(cmake/systemd.cmake)
if (NOT READLINE_FOUND)
diff --git a/cmake/FindReadline.cmake b/cmake/FindReadline.cmake
index 24b6e4740e8e9e213006b61d098d96a98d19927f..bde282b9d1aa028c924e027acbe4b6ae17b7386d 100644
--- a/cmake/FindReadline.cmake
+++ b/cmake/FindReadline.cmake
@@ -28,7 +28,13 @@ IF (READLINE_READLINE_LIBRARY AND READLINE_INCLUDE_DIR)
SET (READLINE_FOUND TRUE)
SET (READLINE_INCLUDE_DIR ${READLINE_INCLUDE_DIR})
SET (READLINE_LIBRARIES ${READLINE_READLINE_LIBRARY})
- MESSAGE(STATUS "Found GNU readline: ${READLINE_READLINE_LIBRARY}, include dir ${READLINE_INCLUDE_DIR}")
+ IF (EXISTS ${READLINE_INCLUDE_DIR}/readline/rlconf.h)
+ set(HAVE_GNU_READLINE 1)
+ set(libname "GNU readline")
+ ELSE()
+ set(libname "readline")
+ ENDIF ()
+ MESSAGE(STATUS "Found ${libname}: ${READLINE_READLINE_LIBRARY}, include dir ${READLINE_INCLUDE_DIR}")
IF (TERMCAP_FOUND)
SET (READLINE_LIBRARIES ${READLINE_LIBRARIES} ${TERMCAP_LIBRARY})
ENDIF (TERMCAP_FOUND)
diff --git a/cmake/FindSphinx.cmake b/cmake/FindSphinx.cmake
new file mode 100644
index 0000000000000000000000000000000000000000..f26a37c5b4c14d56054f6e9b151314030d8cd971
--- /dev/null
+++ b/cmake/FindSphinx.cmake
@@ -0,0 +1,10 @@
+include(FindPackageHandleStandardArgs)
+
+find_program(SPHINX_EXECUTABLE NAMES sphinx-build
+ HINTS
+ $ENV{SPHINX_DIR}
+ PATH_SUFFIXES bin
+)
+
+find_package_handle_standard_args(Sphinx DEFAULT_MSG SPHINX_EXECUTABLE)
+mark_as_advanced(SPHINX_EXECUTABLE)
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 1054cdcf6912d6f9c4fd3c7739c203a38095f3da..cbe16b27a66c88f44988f60d89398cfbf6f54376 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -1,8 +1,3 @@
-configure_file(
- "${PROJECT_SOURCE_DIR}/doc/tnt.ent.cmake"
- "${PROJECT_BINARY_DIR}/doc/tnt.ent"
- )
-
configure_file(
"${PROJECT_SOURCE_DIR}/doc/www/content/newsite/download.yml.in"
"${PROJECT_BINARY_DIR}/doc/www/content/newsite/download.yml"
@@ -11,8 +6,7 @@ configure_file(
add_subdirectory(man)
if (ENABLE_DOC)
- add_subdirectory(user)
- add_subdirectory(developer)
+ add_subdirectory(sphinx)
add_subdirectory(www)
endif()
diff --git a/doc/coding-style-python.txt b/doc/coding-style-python.txt
deleted file mode 100644
index 73b518fc517aa43255ecc017d866f0bd27fe0835..0000000000000000000000000000000000000000
--- a/doc/coding-style-python.txt
+++ /dev/null
@@ -1,854 +0,0 @@
-The project's coding style for Python Code is based on a version of the PEP8
-coding style.
-
-The latest version of the Linux style can be found at:
-
-http://www.python.org/dev/peps/pep-0008/
--------------------------------------------------------------------------------
-
-Introduction
- This document gives coding conventions for the Python code comprising the
- standard library in the main Python distribution. Please see the
- companion informational PEP describing style guidelines for the C code in
- the C implementation of Python[1].
-
- This document was adapted from Guido's original Python Style Guide
- essay[2], with some additions from Barry's style guide[5]. Where there's
- conflict, Guido's style rules for the purposes of this PEP. This PEP may
- still be incomplete (in fact, it may never be finished <wink>).
-
-
-A Foolish Consistency is the Hobgoblin of Little Minds
- One of Guido's key insights is that code is read much more often than it
- is written. The guidelines provided here are intended to improve the
- readability of code and make it consistent across the wide spectrum of
- Python code. As PEP 20 [6] says, "Readability counts".
-
- A style guide is about consistency. Consistency with this style guide is
- important. Consistency within a project is more important. Consistency
- within one module or function is most important.
-
- But most importantly: know when to be inconsistent -- sometimes the style
- guide just doesn't apply. When in doubt, use your best judgment. Look
- at other examples and decide what looks best. And don't hesitate to ask!
-
- Two good reasons to break a particular rule:
-
- (1) When applying the rule would make the code less readable, even for
- someone who is used to reading code that follows the rules.
-
- (2) To be consistent with surrounding code that also breaks it (maybe for
- historic reasons) -- although this is also an opportunity to clean up
- someone else's mess (in true XP style).
-
-
-Code lay-out
- Indentation
-
- Use 4 spaces per indentation level.
-
- For really old code that you don't want to mess up, you can continue to
- use 8-space tabs.
-
- Continuation lines should align wrapped elements either vertically using
- Python's implicit line joining inside parentheses, brackets and braces, or
- using a hanging indent. When using a hanging indent the following
- considerations should be applied; there should be no arguments on the
- first line and further indentation should be used to clearly distinguish
- itself as a continuation line.
-
- Yes: # Aligned with opening delimiter
- foo = long_function_name(var_one, var_two,
- var_three, var_four)
-
- # More indentation included to distinguish this from the rest.
- def long_function_name(
- var_one, var_two, var_three,
- var_four):
- print(var_one)
-
- No: # Arguments on first line forbidden when not using vertical alignment
- foo = long_function_name(var_one, var_two,
- var_three, var_four)
-
- # Further indentation required as indentation is not distinguishable
- def long_function_name(
- var_one, var_two, var_three,
- var_four):
- print(var_one)
-
- Optional:
- # Extra indentation is not necessary.
- foo = long_function_name(
- var_one, var_two,
- var_three, var_four)
-
- Tabs or Spaces?
-
- Never mix tabs and spaces.
-
- The most popular way of indenting Python is with spaces only. The
- second-most popular way is with tabs only. Code indented with a mixture
- of tabs and spaces should be converted to using spaces exclusively. When
- invoking the Python command line interpreter with the -t option, it issues
- warnings about code that illegally mixes tabs and spaces. When using -tt
- these warnings become errors. These options are highly recommended!
-
- For new projects, spaces-only are strongly recommended over tabs. Most
- editors have features that make this easy to do.
-
- Maximum Line Length
-
- Limit all lines to a maximum of 79 characters.
-
- There are still many devices around that are limited to 80 character
- lines; plus, limiting windows to 80 characters makes it possible to have
- several windows side-by-side. The default wrapping on such devices
- disrupts the visual structure of the code, making it more difficult to
- understand. Therefore, please limit all lines to a maximum of 79
- characters. For flowing long blocks of text (docstrings or comments),
- limiting the length to 72 characters is recommended.
-
- The preferred way of wrapping long lines is by using Python's implied line
- continuation inside parentheses, brackets and braces. Long lines can be
- broken over multiple lines by wrapping expressions in parentheses. These
- should be used in preference to using a backslash for line continuation.
- Make sure to indent the continued line appropriately. The preferred place
- to break around a binary operator is *after* the operator, not before it.
- Some examples:
-
- class Rectangle(Blob):
-
- def __init__(self, width, height,
- color='black', emphasis=None, highlight=0):
- if (width == 0 and height == 0 and
- color == 'red' and emphasis == 'strong' or
- highlight > 100):
- raise ValueError("sorry, you lose")
- if width == 0 and height == 0 and (color == 'red' or
- emphasis is None):
- raise ValueError("I don't think so -- values are %s, %s" %
- (width, height))
- Blob.__init__(self, width, height,
- color, emphasis, highlight)
-
- Blank Lines
-
- Separate top-level function and class definitions with two blank lines.
-
- Method definitions inside a class are separated by a single blank line.
-
- Extra blank lines may be used (sparingly) to separate groups of related
- functions. Blank lines may be omitted between a bunch of related
- one-liners (e.g. a set of dummy implementations).
-
- Use blank lines in functions, sparingly, to indicate logical sections.
-
- Python accepts the control-L (i.e. ^L) form feed character as whitespace;
- Many tools treat these characters as page separators, so you may use them
- to separate pages of related sections of your file. Note, some editors
- and web-based code viewers may not recognize control-L as a form feed
- and will show another glyph in its place.
-
- Encodings (PEP 263)
-
- Code in the core Python distribution should always use the ASCII or
- Latin-1 encoding (a.k.a. ISO-8859-1). For Python 3.0 and beyond,
- UTF-8 is preferred over Latin-1, see PEP 3120.
-
- Files using ASCII should not have a coding cookie. Latin-1 (or
- UTF-8) should only be used when a comment or docstring needs to
- mention an author name that requires Latin-1; otherwise, using
- \x, \u or \U escapes is the preferred way to include non-ASCII
- data in string literals.
-
- For Python 3.0 and beyond, the following policy is prescribed for
- the standard library (see PEP 3131): All identifiers in the Python
- standard library MUST use ASCII-only identifiers, and SHOULD use
- English words wherever feasible (in many cases, abbreviations and
- technical terms are used which aren't English). In addition,
- string literals and comments must also be in ASCII. The only
- exceptions are (a) test cases testing the non-ASCII features, and
- (b) names of authors. Authors whose names are not based on the
- latin alphabet MUST provide a latin transliteration of their
- names.
-
- Open source projects with a global audience are encouraged to
- adopt a similar policy.
-
-
-Imports
- - Imports should usually be on separate lines, e.g.:
-
- Yes: import os
- import sys
-
- No: import sys, os
-
- it's okay to say this though:
-
- from subprocess import Popen, PIPE
-
- - Imports are always put at the top of the file, just after any module
- comments and docstrings, and before module globals and constants.
-
- Imports should be grouped in the following order:
-
- 1. standard library imports
- 2. related third party imports
- 3. local application/library specific imports
-
- You should put a blank line between each group of imports.
-
- Put any relevant __all__ specification after the imports.
-
- - Relative imports for intra-package imports are highly discouraged.
- Always use the absolute package path for all imports.
- Even now that PEP 328 [7] is fully implemented in Python 2.5,
- its style of explicit relative imports is actively discouraged;
- absolute imports are more portable and usually more readable.
-
- - When importing a class from a class-containing module, it's usually okay
- to spell this
-
- from myclass import MyClass
- from foo.bar.yourclass import YourClass
-
- If this spelling causes local name clashes, then spell them
-
- import myclass
- import foo.bar.yourclass
-
- and use "myclass.MyClass" and "foo.bar.yourclass.YourClass"
-
-
-Whitespace in Expressions and Statements
- Pet Peeves
-
- Avoid extraneous whitespace in the following situations:
-
- - Immediately inside parentheses, brackets or braces.
-
- Yes: spam(ham[1], {eggs: 2})
- No: spam( ham[ 1 ], { eggs: 2 } )
-
- - Immediately before a comma, semicolon, or colon:
-
- Yes: if x == 4: print x, y; x, y = y, x
- No: if x == 4 : print x , y ; x , y = y , x
-
- - Immediately before the open parenthesis that starts the argument
- list of a function call:
-
- Yes: spam(1)
- No: spam (1)
-
- - Immediately before the open parenthesis that starts an indexing or
- slicing:
-
- Yes: dict['key'] = list[index]
- No: dict ['key'] = list [index]
-
- - More than one space around an assignment (or other) operator to
- align it with another.
-
- Yes:
-
- x = 1
- y = 2
- long_variable = 3
-
- No:
-
- x = 1
- y = 2
- long_variable = 3
-
-
- Other Recommendations
-
- - Always surround these binary operators with a single space on
- either side: assignment (=), augmented assignment (+=, -= etc.),
- comparisons (==, <, >, !=, <>, <=, >=, in, not in, is, is not),
- Booleans (and, or, not).
-
- - Use spaces around arithmetic operators:
-
- Yes:
-
- i = i + 1
- submitted += 1
- x = x * 2 - 1
- hypot2 = x * x + y * y
- c = (a + b) * (a - b)
-
- No:
-
- i=i+1
- submitted +=1
- x = x*2 - 1
- hypot2 = x*x + y*y
- c = (a+b) * (a-b)
-
- - Don't use spaces around the '=' sign when used to indicate a
- keyword argument or a default parameter value.
-
- Yes:
-
- def complex(real, imag=0.0):
- return magic(r=real, i=imag)
-
- No:
-
- def complex(real, imag = 0.0):
- return magic(r = real, i = imag)
-
- - Compound statements (multiple statements on the same line) are
- generally discouraged.
-
- Yes:
-
- if foo == 'blah':
- do_blah_thing()
- do_one()
- do_two()
- do_three()
-
- Rather not:
-
- if foo == 'blah': do_blah_thing()
- do_one(); do_two(); do_three()
-
- - While sometimes it's okay to put an if/for/while with a small
- body on the same line, never do this for multi-clause
- statements. Also avoid folding such long lines!
-
- Rather not:
-
- if foo == 'blah': do_blah_thing()
- for x in lst: total += x
- while t < 10: t = delay()
-
- Definitely not:
-
- if foo == 'blah': do_blah_thing()
- else: do_non_blah_thing()
-
- try: something()
- finally: cleanup()
-
- do_one(); do_two(); do_three(long, argument,
- list, like, this)
-
- if foo == 'blah': one(); two(); three()
-
-Comments
- Comments that contradict the code are worse than no comments. Always make
- a priority of keeping the comments up-to-date when the code changes!
-
- Comments should be complete sentences. If a comment is a phrase or
- sentence, its first word should be capitalized, unless it is an identifier
- that begins with a lower case letter (never alter the case of
- identifiers!).
-
- If a comment is short, the period at the end can be omitted. Block
- comments generally consist of one or more paragraphs built out of complete
- sentences, and each sentence should end in a period.
-
- You should use two spaces after a sentence-ending period.
-
- When writing English, Strunk and White apply.
-
- Python coders from non-English speaking countries: please write
- your comments in English, unless you are 120% sure that the code
- will never be read by people who don't speak your language.
-
-
- Block Comments
-
- Block comments generally apply to some (or all) code that follows them,
- and are indented to the same level as that code. Each line of a block
- comment starts with a # and a single space (unless it is indented text
- inside the comment).
-
- Paragraphs inside a block comment are separated by a line containing a
- single #.
-
- Inline Comments
-
- Use inline comments sparingly.
-
- An inline comment is a comment on the same line as a statement. Inline
- comments should be separated by at least two spaces from the statement.
- They should start with a # and a single space.
-
- Inline comments are unnecessary and in fact distracting if they state
- the obvious. Don't do this:
-
- x = x + 1 # Increment x
-
- But sometimes, this is useful:
-
- x = x + 1 # Compensate for border
-
-
-Documentation Strings
- Conventions for writing good documentation strings (a.k.a. "docstrings")
- are immortalized in PEP 257 [3].
-
- - Write docstrings for all public modules, functions, classes, and
- methods. Docstrings are not necessary for non-public methods, but you
- should have a comment that describes what the method does. This comment
- should appear after the "def" line.
-
- - PEP 257 describes good docstring conventions. Note that most
- importantly, the """ that ends a multiline docstring should be on a line
- by itself, and preferably preceded by a blank line, e.g.:
-
- """Return a foobang
-
- Optional plotz says to frobnicate the bizbaz first.
-
- """
-
- - For one liner docstrings, it's okay to keep the closing """ on the same
- line.
-
-
-Version Bookkeeping
- If you have to have Subversion, CVS, or RCS crud in your source file, do
- it as follows.
-
- __version__ = "$Revision: 00f8e3bb1197 $"
- # $Source$
-
- These lines should be included after the module's docstring, before any
- other code, separated by a blank line above and below.
-
-
-Naming Conventions
- The naming conventions of Python's library are a bit of a mess, so we'll
- never get this completely consistent -- nevertheless, here are the
- currently recommended naming standards. New modules and packages
- (including third party frameworks) should be written to these standards,
- but where an existing library has a different style, internal consistency
- is preferred.
-
- Descriptive: Naming Styles
-
- There are a lot of different naming styles. It helps to be able to
- recognize what naming style is being used, independently from what they
- are used for.
-
- The following naming styles are commonly distinguished:
-
- - b (single lowercase letter)
-
- - B (single uppercase letter)
-
- - lowercase
-
- - lower_case_with_underscores
-
- - UPPERCASE
-
- - UPPER_CASE_WITH_UNDERSCORES
-
- - CapitalizedWords (or CapWords, or CamelCase -- so named because
- of the bumpy look of its letters[4]). This is also sometimes known as
- StudlyCaps.
-
- Note: When using abbreviations in CapWords, capitalize all the letters
- of the abbreviation. Thus HTTPServerError is better than
- HttpServerError.
-
- - mixedCase (differs from CapitalizedWords by initial lowercase
- character!)
-
- - Capitalized_Words_With_Underscores (ugly!)
-
- There's also the style of using a short unique prefix to group related
- names together. This is not used much in Python, but it is mentioned for
- completeness. For example, the os.stat() function returns a tuple whose
- items traditionally have names like st_mode, st_size, st_mtime and so on.
- (This is done to emphasize the correspondence with the fields of the
- POSIX system call struct, which helps programmers familiar with that.)
-
- The X11 library uses a leading X for all its public functions. In Python,
- this style is generally deemed unnecessary because attribute and method
- names are prefixed with an object, and function names are prefixed with a
- module name.
-
- In addition, the following special forms using leading or trailing
- underscores are recognized (these can generally be combined with any case
- convention):
-
- - _single_leading_underscore: weak "internal use" indicator. E.g. "from M
- import *" does not import objects whose name starts with an underscore.
-
- - single_trailing_underscore_: used by convention to avoid conflicts with
- Python keyword, e.g.
-
- Tkinter.Toplevel(master, class_='ClassName')
-
- - __double_leading_underscore: when naming a class attribute, invokes name
- mangling (inside class FooBar, __boo becomes _FooBar__boo; see below).
-
- - __double_leading_and_trailing_underscore__: "magic" objects or
- attributes that live in user-controlled namespaces. E.g. __init__,
- __import__ or __file__. Never invent such names; only use them
- as documented.
-
- Prescriptive: Naming Conventions
-
- Names to Avoid
-
- Never use the characters `l' (lowercase letter el), `O' (uppercase
- letter oh), or `I' (uppercase letter eye) as single character variable
- names.
-
- In some fonts, these characters are indistinguishable from the numerals
- one and zero. When tempted to use `l', use `L' instead.
-
- Package and Module Names
-
- Modules should have short, all-lowercase names. Underscores can be used
- in the module name if it improves readability. Python packages should
- also have short, all-lowercase names, although the use of underscores is
- discouraged.
-
- Since module names are mapped to file names, and some file systems are
- case insensitive and truncate long names, it is important that module
- names be chosen to be fairly short -- this won't be a problem on Unix,
- but it may be a problem when the code is transported to older Mac or
- Windows versions, or DOS.
-
- When an extension module written in C or C++ has an accompanying Python
- module that provides a higher level (e.g. more object oriented)
- interface, the C/C++ module has a leading underscore (e.g. _socket).
-
- Class Names
-
- Almost without exception, class names use the CapWords convention.
- Classes for internal use have a leading underscore in addition.
-
- Exception Names
-
- Because exceptions should be classes, the class naming convention
- applies here. However, you should use the suffix "Error" on your
- exception names (if the exception actually is an error).
-
- Global Variable Names
-
- (Let's hope that these variables are meant for use inside one module
- only.) The conventions are about the same as those for functions.
-
- Modules that are designed for use via "from M import *" should use the
- __all__ mechanism to prevent exporting globals, or use the older
- convention of prefixing such globals with an underscore (which you might
- want to do to indicate these globals are "module non-public").
-
- Function Names
-
- Function names should be lowercase, with words separated by underscores
- as necessary to improve readability.
-
- mixedCase is allowed only in contexts where that's already the
- prevailing style (e.g. threading.py), to retain backwards compatibility.
-
- Function and method arguments
-
- Always use 'self' for the first argument to instance methods.
-
- Always use 'cls' for the first argument to class methods.
-
- If a function argument's name clashes with a reserved keyword, it is
- generally better to append a single trailing underscore rather than use
- an abbreviation or spelling corruption. Thus "print_" is better than
- "prnt". (Perhaps better is to avoid such clashes by using a synonym.)
-
- Method Names and Instance Variables
-
- Use the function naming rules: lowercase with words separated by
- underscores as necessary to improve readability.
-
- Use one leading underscore only for non-public methods and instance
- variables.
-
- To avoid name clashes with subclasses, use two leading underscores to
- invoke Python's name mangling rules.
-
- Python mangles these names with the class name: if class Foo has an
- attribute named __a, it cannot be accessed by Foo.__a. (An insistent
- user could still gain access by calling Foo._Foo__a.) Generally, double
- leading underscores should be used only to avoid name conflicts with
- attributes in classes designed to be subclassed.
-
- Note: there is some controversy about the use of __names (see below).
-
- Constants
-
- Constants are usually defined on a module level and written in all
- capital letters with underscores separating words. Examples include
- MAX_OVERFLOW and TOTAL.
-
- Designing for inheritance
-
- Always decide whether a class's methods and instance variables
- (collectively: "attributes") should be public or non-public. If in
- doubt, choose non-public; it's easier to make it public later than to
- make a public attribute non-public.
-
- Public attributes are those that you expect unrelated clients of your
- class to use, with your commitment to avoid backward incompatible
- changes. Non-public attributes are those that are not intended to be
- used by third parties; you make no guarantees that non-public attributes
- won't change or even be removed.
-
- We don't use the term "private" here, since no attribute is really
- private in Python (without a generally unnecessary amount of work).
-
- Another category of attributes are those that are part of the "subclass
- API" (often called "protected" in other languages). Some classes are
- designed to be inherited from, either to extend or modify aspects of the
- class's behavior. When designing such a class, take care to make
- explicit decisions about which attributes are public, which are part of
- the subclass API, and which are truly only to be used by your base
- class.
-
- With this in mind, here are the Pythonic guidelines:
-
- - Public attributes should have no leading underscores.
-
- - If your public attribute name collides with a reserved keyword, append
- a single trailing underscore to your attribute name. This is
- preferable to an abbreviation or corrupted spelling. (However,
- notwithstanding this rule, 'cls' is the preferred spelling for any
- variable or argument which is known to be a class, especially the
- first argument to a class method.)
-
- Note 1: See the argument name recommendation above for class methods.
-
- - For simple public data attributes, it is best to expose just the
- attribute name, without complicated accessor/mutator methods. Keep in
- mind that Python provides an easy path to future enhancement, should
- you find that a simple data attribute needs to grow functional
- behavior. In that case, use properties to hide functional
- implementation behind simple data attribute access syntax.
-
- Note 1: Properties only work on new-style classes.
-
- Note 2: Try to keep the functional behavior side-effect free, although
- side-effects such as caching are generally fine.
-
- Note 3: Avoid using properties for computationally expensive
- operations; the attribute notation makes the caller believe
- that access is (relatively) cheap.
-
- - If your class is intended to be subclassed, and you have attributes
- that you do not want subclasses to use, consider naming them with
- double leading underscores and no trailing underscores. This invokes
- Python's name mangling algorithm, where the name of the class is
- mangled into the attribute name. This helps avoid attribute name
- collisions should subclasses inadvertently contain attributes with the
- same name.
-
- Note 1: Note that only the simple class name is used in the mangled
- name, so if a subclass chooses both the same class name and attribute
- name, you can still get name collisions.
-
- Note 2: Name mangling can make certain uses, such as debugging and
- __getattr__(), less convenient. However the name mangling algorithm
- is well documented and easy to perform manually.
-
- Note 3: Not everyone likes name mangling. Try to balance the
- need to avoid accidental name clashes with potential use by
- advanced callers.
-
-
-Programming Recommendations
- - Code should be written in a way that does not disadvantage other
- implementations of Python (PyPy, Jython, IronPython, Pyrex, Psyco,
- and such).
-
- For example, do not rely on CPython's efficient implementation of
- in-place string concatenation for statements in the form a+=b or a=a+b.
- Those statements run more slowly in Jython. In performance sensitive
- parts of the library, the ''.join() form should be used instead. This
- will ensure that concatenation occurs in linear time across various
- implementations.
-
- - Comparisons to singletons like None should always be done with
- 'is' or 'is not', never the equality operators.
-
- Also, beware of writing "if x" when you really mean "if x is not None"
- -- e.g. when testing whether a variable or argument that defaults to
- None was set to some other value. The other value might have a type
- (such as a container) that could be false in a boolean context!
-
- - When implementing ordering operations with rich comparisons, it is best to
- implement all six operations (__eq__, __ne__, __lt__, __le__, __gt__,
- __ge__) rather than relying on other code to only exercise a particular
- comparison.
-
- To minimize the effort involved, the functools.total_ordering() decorator
- provides a tool to generate missing comparison methods.
-
- PEP 207 indicates that reflexivity rules *are* assumed by Python. Thus,
- the interpreter may swap y>x with x<y, y>=x with x<=y, and may swap the
- arguments of x==y and x!=y. The sort() and min() operations are
- guaranteed to use the < operator and the max() function uses the >
- operator. However, it is best to implement all six operations so that
- confusion doesn't arise in other contexts.
-
- - Use class-based exceptions.
-
- String exceptions in new code are forbidden, because this language
- feature is being removed in Python 2.6.
-
- Modules or packages should define their own domain-specific base
- exception class, which should be subclassed from the built-in Exception
- class. Always include a class docstring. E.g.:
-
- class MessageError(Exception):
- """Base class for errors in the email package."""
-
- Class naming conventions apply here, although you should add the suffix
- "Error" to your exception classes, if the exception is an error.
- Non-error exceptions need no special suffix.
-
- - When raising an exception, use "raise ValueError('message')" instead of
- the older form "raise ValueError, 'message'".
-
- The paren-using form is preferred because when the exception arguments
- are long or include string formatting, you don't need to use line
- continuation characters thanks to the containing parentheses. The older
- form will be removed in Python 3000.
-
- - When catching exceptions, mention specific exceptions
- whenever possible instead of using a bare 'except:' clause.
-
- For example, use:
-
- try:
- import platform_specific_module
- except ImportError:
- platform_specific_module = None
-
- A bare 'except:' clause will catch SystemExit and KeyboardInterrupt
- exceptions, making it harder to interrupt a program with Control-C,
- and can disguise other problems. If you want to catch all
- exceptions that signal program errors, use 'except Exception:'.
-
- A good rule of thumb is to limit use of bare 'except' clauses to two
- cases:
-
- 1) If the exception handler will be printing out or logging
- the traceback; at least the user will be aware that an
- error has occurred.
-
- 2) If the code needs to do some cleanup work, but then lets
- the exception propagate upwards with 'raise'.
- 'try...finally' is a better way to handle this case.
-
- - Additionally, for all try/except clauses, limit the 'try' clause
- to the absolute minimum amount of code necessary. Again, this
- avoids masking bugs.
-
- Yes:
-
- try:
- value = collection[key]
- except KeyError:
- return key_not_found(key)
- else:
- return handle_value(value)
-
- No:
-
- try:
- # Too broad!
- return handle_value(collection[key])
- except KeyError:
- # Will also catch KeyError raised by handle_value()
- return key_not_found(key)
-
- - Use string methods instead of the string module.
-
- String methods are always much faster and share the same API with
- unicode strings. Override this rule if backward compatibility with
- Pythons older than 2.0 is required.
-
- - Use ''.startswith() and ''.endswith() instead of string slicing to check
- for prefixes or suffixes.
-
- startswith() and endswith() are cleaner and less error prone. For
- example:
-
- Yes: if foo.startswith('bar'):
-
- No: if foo[:3] == 'bar':
-
- The exception is if your code must work with Python 1.5.2 (but let's
- hope not!).
-
- - Object type comparisons should always use isinstance() instead
- of comparing types directly.
-
- Yes: if isinstance(obj, int):
-
- No: if type(obj) is type(1):
-
- When checking if an object is a string, keep in mind that it might be a
- unicode string too! In Python 2.3, str and unicode have a common base
- class, basestring, so you can do:
-
- if isinstance(obj, basestring):
-
- - For sequences, (strings, lists, tuples), use the fact that empty
- sequences are false.
-
- Yes: if not seq:
- if seq:
-
- No: if len(seq)
- if not len(seq)
-
- - Don't write string literals that rely on significant trailing
- whitespace. Such trailing whitespace is visually indistinguishable and
- some editors (or more recently, reindent.py) will trim them.
-
- - Don't compare boolean values to True or False using ==
-
- Yes: if greeting:
-
- No: if greeting == True:
-
- Worse: if greeting is True:
-
-Rules that apply only to the standard library
- - Do not use function type annotations in the standard library.
- These are reserved for users and third-party modules. See
- PEP 3107 and the bug 10899 for details.
-
-
-References
- [1] PEP 7, Style Guide for C Code, van Rossum
-
- [2] http://www.python.org/doc/essays/styleguide.html
-
- [3] PEP 257, Docstring Conventions, Goodger, van Rossum
-
- [4] http://www.wikipedia.com/wiki/CamelCase
-
- [5] Barry's GNU Mailman style guide
- http://barry.warsaw.us/software/STYLEGUIDE.txt
-
- [6] PEP 20, The Zen of Python
-
- [7] PEP 328, Imports: Multi-Line and Absolute/Relative
-
-
-Copyright
- This document has been placed in the public domain.
-
diff --git a/doc/developer/CMakeLists.txt b/doc/developer/CMakeLists.txt
deleted file mode 100644
index ad9f9dd121af444ea5338f07a75b2c4f061c8c78..0000000000000000000000000000000000000000
--- a/doc/developer/CMakeLists.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-set(PATH_DEVGUIDE_HTML "${PROJECT_BINARY_DIR}/doc/www/content/doc/dev_guide.html")
-set(PATH_DEVGUIDE_TXT "${PROJECT_BINARY_DIR}/doc/developer/dev_guide.txt")
-
-add_custom_target(dev-doc-check
- COMMAND ${JING} http://docbook.org/xml/5.0/rng/docbookxi.rng
- ${CMAKE_SOURCE_DIR}/doc/developer/developer.xml)
-
-add_custom_target(dev-html
- COMMAND ${XSLTPROC} --nonet
- --stringparam collect.xref.targets "all"
- --xinclude -o ${PATH_DEVGUIDE_HTML} tnt-html.xsl
- ${CMAKE_SOURCE_DIR}/doc/developer/developer.xml)
-
-add_custom_target(dev-html-saxon
- COMMAND java -cp "/usr/share/java/saxon.jar:/usr/share/java/xml-resolver.jar:/usr/share/java/docbook-xsl-saxon.jar:/usr/share/java/xercesImpl.jar:/etc/xml/resolver:/usr/share/java/xslthl.jar:/usr/share/java/xml-commons-resolver-1.1.jar"
- -Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl
- -Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl
- -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XIncludeParserConfiguration
- com.icl.saxon.StyleSheet
- -x org.apache.xml.resolver.tools.ResolvingXMLReader
- -y org.apache.xml.resolver.tools.ResolvingXMLReader
- -r org.apache.xml.resolver.tools.CatalogResolver
- -u -o ${PATH_DEVGUIDE_HTML} -w1 developer.xml tnt-html.xsl)
-
-
diff --git a/doc/developer/developer.xml b/doc/developer/developer.xml
deleted file mode 100644
index 3109ae0452893f3e369e69e15d63094750a8dbe9..0000000000000000000000000000000000000000
--- a/doc/developer/developer.xml
+++ /dev/null
@@ -1,153 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE book [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<book xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0">
-<title>Tarantool Developer Guide</title>
-<preface>
- <title>What documentation there is</title>
- <para>
- Tarantool documentation consists of:
- <itemizedlist>
- <listitem><para>a user guide</para></listitem>
- <listitem><para>a developer guide (you're reading it)</para></listitem>
- <listitem><para>protocol description doc/www/content/doc/box-protocol.rst</para></listitem>
- <listitem><para>coding style guides for Lua, Objective C, C, Python (for
- other connectors, we use conventions of the connector programming
- language community)</para></listitem>
- </itemizedlist>
- </para>
-</preface>
-<chapter>
-<title>Compiling</title>
-<section>
-<title>How to build the XML manual</title>
-<para>
-To build XML manual, you'll need:
-
-<itemizedlist>
-<listitem><para>xsltproc</para></listitem>
-<listitem><para>docbook5-xml</para></listitem>
-<listitem><para>docbook-xsl-ns</para></listitem>
-<listitem><para>w3c-sgml-lib</para></listitem>
-<listitem><para>libsaxon-java- for saxon processing</para></listitem>
-<listitem><para>libxml-commons-resolver1.1-java</para></listitem>
-<listitem><para>libxml2-utils</para></listitem>
-<listitem><para>libxerces2-java</para></listitem>
-<listitem><para>libxslthl-java</para></listitem>
-<listitem><para>lynx</para></listitem>
-<listitem><para>jing</para></listitem>
-</itemizedlist>
-
-
-
-When all pre-requisites are met, you should run:
-
-<programlisting>
- <prompt>$ </prompt> cmake . -DENABLE_DOC=yes
-</programlisting>
-
-to enable documentation builder.
-
-If you want to make tarantool user guide, you should run the following command
-from taratnool root directory:
-
-<programlisting>
- <prompt>$ </prompt> make html
-</programlisting>
-
-or
-
-<programlisting>
- <prompt>$ </prompt> cd doc/user
- <prompt>$ </prompt> make
-</programlisting>
-
-The html version of the user guide will be generated in doc/www-data.
-
-To building the developer guilde, you should run:
-
-<programlisting>
- <prompt>$ </prompt> cd doc/developer
- <prompt>$ </prompt> make
-</programlisting>
-
-The html version of the developer guide will be generated in doc/www-data.
-
-</para>
-</section>
-</chapter>
-<chapter>
-<title>Release management</title>
- <section><title>How to make a minor release</title>
- <para>
- <programlisting>git tag -a 1.4.4 -m "Next minor in 1.4 series"
-vim CMakeLists.txt # edit CPACK_PACKAGE_VERSION_PATCH
-git push --tags
-</programlisting>
-Update the Web site in doc/www-data.
-</para>
-<para>
-Update all blueprints, upload the ChangeLog, based on <prompt>git log</prompt>output.
-The ChangeLog must only include items which are mentioned as bugs
-or blueprints on Launchpad. If anything significant is there,
-which is not mentioned, something went wrong in release planning
-and the release should be held up until this is cleared.
- </para>
-<para>
-Click 'Release milestone'. Create a milestone for the next minor
-release. Alert the driver to target bugs and blueprints
-to the new milestone.
-</para>
-<para>
-</para>
- </section>
-</chapter>
-<chapter>
-<title>Developer guidelines</title>
-<section>
-<title>How to work on a bug</title>
-<para>Any defect, even minor, if it changes the user-visible
-server behavior, needs a bug report. Report a bug at
-http://github.com/tarantool/tarantool/issues.
-
-When reporting a bug, try to come up with a test case right away.
-Set the current maintenance milestone for the bug fix, and specify
-the series. Assign the bug to yourself. Put the status to 'In
-progress' Once the patch is ready, put the bug the bug to 'In
-review' and solicit a review for the fix.
-</para>
-<para>
-Once there is a positive code review, push the patch
-and set the status to 'Closed'
-</para>
-<para>
-Patches for bugs should contain a reference to the respective
-Launchpad bug page or at least bug id. Each patch should have a
-test, unless coming up with one is difficult in the current
-framework, in which case QA should be alerted.
-</para>
-<para>
-There are two things you need to do when your patch makes it
-into the master:
-<itemizedlist>
- <listitem><para>
- put the bug to 'fix committed',
- </para></listitem>
- <listitem><para>
- delete the remote branch.
- </para></listitem>
-</itemizedlist>
-
-</para>
-</section>
-</chapter>
-</book>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/developer/html-highlight.xsl b/doc/developer/html-highlight.xsl
deleted file mode 120000
index a1674ed2d13746f26d3c4bac1980c0e74beb2738..0000000000000000000000000000000000000000
--- a/doc/developer/html-highlight.xsl
+++ /dev/null
@@ -1 +0,0 @@
-../user/html-highlight.xsl
\ No newline at end of file
diff --git a/doc/developer/intro.xml b/doc/developer/intro.xml
deleted file mode 100644
index 27402b9dd35e4a89720f07c9935821c5acbedbcf..0000000000000000000000000000000000000000
--- a/doc/developer/intro.xml
+++ /dev/null
@@ -1,29 +0,0 @@
-
-<para>
-
-
-
-
-
-arantool is a single-threaded server that supports cooperative multi-processing, developed with work accounting for high loads (e.g. tens of thousands of RPS). It is possible to divide the system functionality into two logical groups: core and module. Currently, modules are installed into the system at compilation time. The core level includes the base functionality, such as network communications, operations on binary logs, replication over the network, fast switchover to the reserve server, etc. The modules implement the business logic of a concrete application, using the core API.
-
-Tarantool/Silverbox is a key-based memory-based data store. Storage of data in memory allows the use of simpler algorithms, decrease of the number of processor instructions, and, most importantly, avoidance of the slowest component in any server system, the hard disk. Database performance of saved information in memory is noticeably higher than that of equivalent systems, which utilize the disk.
-
-It was developed for internal goals of the company Mail.Ru. Once deployed the system proved to be attractive for a number of different projects in the company, and was subsequently adopted by them. The high productivity and reliability of the system under heavy loads made it possible to increase the stability of the services that adopted Tarantool. The first version of the server, which implemented the basic goals for a storage family, went online in 2008. Since that time, Tarantool server has been reworked and perfected for providing specialized storage. The code is written in C and uses gcc extensions.
-
-Basics
-
-Tarantool’s custom allocators avoid external fragmentation of base memory and degradation of performance when working with large numbers of small objects;
-The system is optimized for work with large volumes of data;
-Tarantool uses snapshot files, which contain the state of the database at the time of copy to disk;
-Transaction logging in binary log files preserves all changes to database state, allowing automatic restoration of information after system reboot;
-The system provides high availability, automatic switchover to an available replica in case of crash of any part of the system;
-The system is fully compatible with the memcached protocol;
-Local replicas allow system update without interruption to client services;
-The system provides data replication over the network;
-Tarantool supplies a simply binary protocol for replication, supporting the creation of additional logic.
-The system currently builds only under gcc;
-Tarantool has currently been tested only under Linux;
-When very frequent and rapid changes are made in a large quantity of data, the saving of the snapshot requires a large amount of memory.
-
-</para>
diff --git a/doc/developer/tnt-html.xsl b/doc/developer/tnt-html.xsl
deleted file mode 120000
index f06ef7416c4b83e55a9d986daa01ba3ea995414b..0000000000000000000000000000000000000000
--- a/doc/developer/tnt-html.xsl
+++ /dev/null
@@ -1 +0,0 @@
-../user/tnt-html.xsl
\ No newline at end of file
diff --git a/doc/isopub.ent b/doc/isopub.ent
deleted file mode 100644
index a11787828a38f60b2716ef56ba4c108165af4c54..0000000000000000000000000000000000000000
--- a/doc/isopub.ent
+++ /dev/null
@@ -1,125 +0,0 @@
-
-<!--
- File isopub.ent produced by the XSL script entities.xsl
- from input data in unicode.xml.
-
- Please report any errors to David Carlisle
- via the public W3C list www-math@w3.org.
-
- The numeric character values assigned to each entity
- (should) match the Unicode assignments in Unicode 4.0.
-
- Entity names in this file are derived from files carrying the
- following notice:
-
- (C) International Organization for Standardization 1986
- Permission to copy in any form is granted for use with
- conforming SGML systems and applications as defined in
- ISO 8879, provided this notice is included in all copies.
-
--->
-
-
-<!--
- Version: $Id: isopub.ent,v 1.2 2003/12/08 15:14:43 davidc Exp $
-
- Public identifier: ISO 8879:1986//ENTITIES Publishing//EN//XML
- System identifier: http://www.w3.org/2003/entities/iso8879/isopub.ent
-
- The public identifier should always be used verbatim.
- The system identifier may be changed to suit local requirements.
-
- Typical invocation:
-
- <!ENTITY % isopub PUBLIC
- "ISO 8879:1986//ENTITIES Publishing//EN//XML"
- "http://www.w3.org/2003/entities/iso8879/isopub.ent"
- >
- %isopub;
-
--->
-
-<!ENTITY blank "␣" ><!--OPEN BOX -->
-<!ENTITY blk12 "▒" ><!--MEDIUM SHADE -->
-<!ENTITY blk14 "░" ><!--LIGHT SHADE -->
-<!ENTITY blk34 "▓" ><!--DARK SHADE -->
-<!ENTITY block "█" ><!--FULL BLOCK -->
-<!ENTITY bull "•" ><!--BULLET -->
-<!ENTITY caret "⁁" ><!--CARET INSERTION POINT -->
-<!ENTITY check "✓" ><!--CHECK MARK -->
-<!ENTITY cir "○" ><!--WHITE CIRCLE -->
-<!ENTITY clubs "♣" ><!--BLACK CLUB SUIT -->
-<!ENTITY copysr "℗" ><!--SOUND RECORDING COPYRIGHT -->
-<!ENTITY cross "✗" ><!--BALLOT X -->
-<!ENTITY Dagger "‡" ><!--DOUBLE DAGGER -->
-<!ENTITY dagger "†" ><!--DAGGER -->
-<!ENTITY dash "‐" ><!--HYPHEN -->
-<!ENTITY diams "♦" ><!--BLACK DIAMOND SUIT -->
-<!ENTITY dlcrop "⌍" ><!--BOTTOM LEFT CROP -->
-<!ENTITY drcrop "⌌" ><!--BOTTOM RIGHT CROP -->
-<!ENTITY dtri "▿" ><!--WHITE DOWN-POINTING SMALL TRIANGLE -->
-<!ENTITY dtrif "▾" ><!--BLACK DOWN-POINTING SMALL TRIANGLE -->
-<!ENTITY emsp " " ><!--EM SPACE -->
-<!ENTITY emsp13 " " ><!--THREE-PER-EM SPACE -->
-<!ENTITY emsp14 " " ><!--FOUR-PER-EM SPACE -->
-<!ENTITY ensp " " ><!--EN SPACE -->
-<!ENTITY female "♀" ><!--FEMALE SIGN -->
-<!ENTITY ffilig "ffi" ><!--LATIN SMALL LIGATURE FFI -->
-<!ENTITY fflig "ff" ><!--LATIN SMALL LIGATURE FF -->
-<!ENTITY ffllig "ffl" ><!--LATIN SMALL LIGATURE FFL -->
-<!ENTITY filig "fi" ><!--LATIN SMALL LIGATURE FI -->
-<!ENTITY flat "♭" ><!--MUSIC FLAT SIGN -->
-<!ENTITY fllig "fl" ><!--LATIN SMALL LIGATURE FL -->
-<!ENTITY frac13 "⅓" ><!--VULGAR FRACTION ONE THIRD -->
-<!ENTITY frac15 "⅕" ><!--VULGAR FRACTION ONE FIFTH -->
-<!ENTITY frac16 "⅙" ><!--VULGAR FRACTION ONE SIXTH -->
-<!ENTITY frac23 "⅔" ><!--VULGAR FRACTION TWO THIRDS -->
-<!ENTITY frac25 "⅖" ><!--VULGAR FRACTION TWO FIFTHS -->
-<!ENTITY frac35 "⅗" ><!--VULGAR FRACTION THREE FIFTHS -->
-<!ENTITY frac45 "⅘" ><!--VULGAR FRACTION FOUR FIFTHS -->
-<!ENTITY frac56 "⅚" ><!--VULGAR FRACTION FIVE SIXTHS -->
-<!ENTITY hairsp " " ><!--HAIR SPACE -->
-<!ENTITY hearts "♥" ><!--BLACK HEART SUIT -->
-<!ENTITY hellip "…" ><!--HORIZONTAL ELLIPSIS -->
-<!ENTITY hybull "⁃" ><!--HYPHEN BULLET -->
-<!ENTITY incare "℅" ><!--CARE OF -->
-<!ENTITY ldquor "„" ><!--DOUBLE LOW-9 QUOTATION MARK -->
-<!ENTITY lhblk "▄" ><!--LOWER HALF BLOCK -->
-<!ENTITY loz "◊" ><!--LOZENGE -->
-<!ENTITY lozf "⧫" ><!--BLACK LOZENGE -->
-<!ENTITY lsquor "‚" ><!--SINGLE LOW-9 QUOTATION MARK -->
-<!ENTITY ltri "◃" ><!--WHITE LEFT-POINTING SMALL TRIANGLE -->
-<!ENTITY ltrif "◂" ><!--BLACK LEFT-POINTING SMALL TRIANGLE -->
-<!ENTITY male "♂" ><!--MALE SIGN -->
-<!ENTITY malt "✠" ><!--MALTESE CROSS -->
-<!ENTITY marker "▮" ><!--BLACK VERTICAL RECTANGLE -->
-<!ENTITY mdash "—" ><!--EM DASH -->
-<!ENTITY mldr "…" ><!--HORIZONTAL ELLIPSIS -->
-<!ENTITY natur "♮" ><!--MUSIC NATURAL SIGN -->
-<!ENTITY ndash "–" ><!--EN DASH -->
-<!ENTITY nldr "‥" ><!--TWO DOT LEADER -->
-<!ENTITY numsp " " ><!--FIGURE SPACE -->
-<!ENTITY phone "☎" ><!--BLACK TELEPHONE -->
-<!ENTITY puncsp " " ><!--PUNCTUATION SPACE -->
-<!ENTITY rdquor "”" ><!--RIGHT DOUBLE QUOTATION MARK -->
-<!ENTITY rect "▭" ><!--WHITE RECTANGLE -->
-<!ENTITY rsquor "’" ><!--RIGHT SINGLE QUOTATION MARK -->
-<!ENTITY rtri "▹" ><!--WHITE RIGHT-POINTING SMALL TRIANGLE -->
-<!ENTITY rtrif "▸" ><!--BLACK RIGHT-POINTING SMALL TRIANGLE -->
-<!ENTITY rx "℞" ><!--PRESCRIPTION TAKE -->
-<!ENTITY sext "✶" ><!--SIX POINTED BLACK STAR -->
-<!ENTITY sharp "♯" ><!--MUSIC SHARP SIGN -->
-<!ENTITY spades "♠" ><!--BLACK SPADE SUIT -->
-<!ENTITY squ "□" ><!--WHITE SQUARE -->
-<!ENTITY squf "▪" ><!--BLACK SMALL SQUARE -->
-<!ENTITY star "☆" ><!--WHITE STAR -->
-<!ENTITY starf "★" ><!--BLACK STAR -->
-<!ENTITY target "⌖" ><!--POSITION INDICATOR -->
-<!ENTITY telrec "⌕" ><!--TELEPHONE RECORDER -->
-<!ENTITY thinsp " " ><!--THIN SPACE -->
-<!ENTITY uhblk "▀" ><!--UPPER HALF BLOCK -->
-<!ENTITY ulcrop "⌏" ><!--TOP LEFT CROP -->
-<!ENTITY urcrop "⌎" ><!--TOP RIGHT CROP -->
-<!ENTITY utri "▵" ><!--WHITE UP-POINTING SMALL TRIANGLE -->
-<!ENTITY utrif "▴" ><!--BLACK UP-POINTING SMALL TRIANGLE -->
-<!ENTITY vellip "⋮" ><!--VERTICAL ELLIPSIS -->
diff --git a/doc/sphinx/.gitignore b/doc/sphinx/.gitignore
new file mode 100644
index 0000000000000000000000000000000000000000..7705395c26abd9044835278630dc14086fe4aee3
--- /dev/null
+++ b/doc/sphinx/.gitignore
@@ -0,0 +1,2 @@
+!.gitignore
+*.pyc
diff --git a/doc/sphinx/CMakeLists.txt b/doc/sphinx/CMakeLists.txt
new file mode 100644
index 0000000000000000000000000000000000000000..1da35b2d48649b15b9253666fe9528ba3bcede4a
--- /dev/null
+++ b/doc/sphinx/CMakeLists.txt
@@ -0,0 +1,21 @@
+find_package(Sphinx REQUIRED)
+
+#find_program(MKDIR mkdir)
+
+set(SPHINX_BUILD_DIR "${PROJECT_BINARY_DIR}/doc/sphinx/_build/")
+set(SPHINX_HTML_DIR "${PROJECT_BINARY_DIR}/doc/www/output/doc/")
+
+#add_custom_command(OUTPUT
+# ${MKDIR} -p ${SPHINX_BUILD_DIR})
+#add_custom_command(OUTPUT
+# ${MKDIR} -p ${SPHINX_HTML_DIR})
+
+add_custom_target(sphinx ALL
+# DEPENDS ${SPHINX_BUILD_DIR} ${SPHINX_HTML_DIR}
+ COMMAND "${SPHINX_EXECUTABLE}"
+ -b html
+ -d "${SPHINX_BUILD_DIR}"
+ "${PROJECT_SOURCE_DIR}/doc/sphinx"
+ "${SPHINX_HTML_DIR}"
+ COMMENT "Building HTML documentation with Sphinx"
+)
diff --git a/doc/sphinx/_static/.gitignore b/doc/sphinx/_static/.gitignore
new file mode 100644
index 0000000000000000000000000000000000000000..803a390878133a4b2156b4e85eedae407043a82c
--- /dev/null
+++ b/doc/sphinx/_static/.gitignore
@@ -0,0 +1,2 @@
+!Makefile
+!.gitignore
diff --git a/doc/sphinx/_static/font-awesome.min.css b/doc/sphinx/_static/font-awesome.min.css
new file mode 100644
index 0000000000000000000000000000000000000000..24fcc04c4ed56775bffd4597800eb544bac91178
--- /dev/null
+++ b/doc/sphinx/_static/font-awesome.min.css
@@ -0,0 +1,4 @@
+/*!
+ * Font Awesome 4.3.0 by @davegandy - http://fontawesome.io - @fontawesome
+ * License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License)
+ */@font-face{font-family:'FontAwesome';src:url('../fonts/fontawesome-webfont.eot?v=4.3.0');src:url('../fonts/fontawesome-webfont.eot?#iefix&v=4.3.0') format('embedded-opentype'),url('../fonts/fontawesome-webfont.woff2?v=4.3.0') format('woff2'),url('../fonts/fontawesome-webfont.woff?v=4.3.0') format('woff'),url('../fonts/fontawesome-webfont.ttf?v=4.3.0') format('truetype'),url('../fonts/fontawesome-webfont.svg?v=4.3.0#fontawesomeregular') format('svg');font-weight:normal;font-style:normal}.fa{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;transform:translate(0, 0)}.fa-lg{font-size:1.33333333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571429em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14285714em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14285714em;width:2.14285714em;top:.14285714em;text-align:center}.fa-li.fa-lg{left:-1.85714286em}.fa-border{padding:.2em .25em .15em;border:solid .08em #eee;border-radius:.1em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left{margin-right:.3em}.fa.pull-right{margin-left:.3em}.fa-spin{-webkit-animation:fa-spin 2s infinite linear;animation:fa-spin 2s infinite linear}.fa-pulse{-webkit-animation:fa-spin 1s infinite steps(8);animation:fa-spin 1s infinite steps(8)}@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}100%{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}@keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}100%{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}.fa-rotate-90{filter:progid:DXImageTransform.Microsoft.BasicImage(rotation=1);-webkit-transform:rotate(90deg);-ms-transform:rotate(90deg);transform:rotate(90deg)}.fa-rotate-180{filter:progid:DXImageTransform.Microsoft.BasicImage(rotation=2);-webkit-transform:rotate(180deg);-ms-transform:rotate(180deg);transform:rotate(180deg)}.fa-rotate-270{filter:progid:DXImageTransform.Microsoft.BasicImage(rotation=3);-webkit-transform:rotate(270deg);-ms-transform:rotate(270deg);transform:rotate(270deg)}.fa-flip-horizontal{filter:progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1);-webkit-transform:scale(-1, 1);-ms-transform:scale(-1, 1);transform:scale(-1, 1)}.fa-flip-vertical{filter:progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1);-webkit-transform:scale(1, -1);-ms-transform:scale(1, -1);transform:scale(1, -1)}:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270,:root .fa-flip-horizontal,:root .fa-flip-vertical{filter:none}.fa-stack{position:relative;display:inline-block;width:2em;height:2em;line-height:2em;vertical-align:middle}.fa-stack-1x,.fa-stack-2x{position:absolute;left:0;width:100%;text-align:center}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-glass:before{content:"\f000"}.fa-music:before{content:"\f001"}.fa-search:before{content:"\f002"}.fa-envelope-o:before{content:"\f003"}.fa-heart:before{content:"\f004"}.fa-star:before{content:"\f005"}.fa-star-o:before{content:"\f006"}.fa-user:before{content:"\f007"}.fa-film:before{content:"\f008"}.fa-th-large:before{content:"\f009"}.fa-th:before{content:"\f00a"}.fa-th-list:before{content:"\f00b"}.fa-check:before{content:"\f00c"}.fa-remove:before,.fa-close:before,.fa-times:before{content:"\f00d"}.fa-search-plus:before{content:"\f00e"}.fa-search-minus:before{content:"\f010"}.fa-power-off:before{content:"\f011"}.fa-signal:before{content:"\f012"}.fa-gear:before,.fa-cog:before{content:"\f013"}.fa-trash-o:before{content:"\f014"}.fa-home:before{content:"\f015"}.fa-file-o:before{content:"\f016"}.fa-clock-o:before{content:"\f017"}.fa-road:before{content:"\f018"}.fa-download:before{content:"\f019"}.fa-arrow-circle-o-down:before{content:"\f01a"}.fa-arrow-circle-o-up:before{content:"\f01b"}.fa-inbox:before{content:"\f01c"}.fa-play-circle-o:before{content:"\f01d"}.fa-rotate-right:before,.fa-repeat:before{content:"\f01e"}.fa-refresh:before{content:"\f021"}.fa-list-alt:before{content:"\f022"}.fa-lock:before{content:"\f023"}.fa-flag:before{content:"\f024"}.fa-headphones:before{content:"\f025"}.fa-volume-off:before{content:"\f026"}.fa-volume-down:before{content:"\f027"}.fa-volume-up:before{content:"\f028"}.fa-qrcode:before{content:"\f029"}.fa-barcode:before{content:"\f02a"}.fa-tag:before{content:"\f02b"}.fa-tags:before{content:"\f02c"}.fa-book:before{content:"\f02d"}.fa-bookmark:before{content:"\f02e"}.fa-print:before{content:"\f02f"}.fa-camera:before{content:"\f030"}.fa-font:before{content:"\f031"}.fa-bold:before{content:"\f032"}.fa-italic:before{content:"\f033"}.fa-text-height:before{content:"\f034"}.fa-text-width:before{content:"\f035"}.fa-align-left:before{content:"\f036"}.fa-align-center:before{content:"\f037"}.fa-align-right:before{content:"\f038"}.fa-align-justify:before{content:"\f039"}.fa-list:before{content:"\f03a"}.fa-dedent:before,.fa-outdent:before{content:"\f03b"}.fa-indent:before{content:"\f03c"}.fa-video-camera:before{content:"\f03d"}.fa-photo:before,.fa-image:before,.fa-picture-o:before{content:"\f03e"}.fa-pencil:before{content:"\f040"}.fa-map-marker:before{content:"\f041"}.fa-adjust:before{content:"\f042"}.fa-tint:before{content:"\f043"}.fa-edit:before,.fa-pencil-square-o:before{content:"\f044"}.fa-share-square-o:before{content:"\f045"}.fa-check-square-o:before{content:"\f046"}.fa-arrows:before{content:"\f047"}.fa-step-backward:before{content:"\f048"}.fa-fast-backward:before{content:"\f049"}.fa-backward:before{content:"\f04a"}.fa-play:before{content:"\f04b"}.fa-pause:before{content:"\f04c"}.fa-stop:before{content:"\f04d"}.fa-forward:before{content:"\f04e"}.fa-fast-forward:before{content:"\f050"}.fa-step-forward:before{content:"\f051"}.fa-eject:before{content:"\f052"}.fa-chevron-left:before{content:"\f053"}.fa-chevron-right:before{content:"\f054"}.fa-plus-circle:before{content:"\f055"}.fa-minus-circle:before{content:"\f056"}.fa-times-circle:before{content:"\f057"}.fa-check-circle:before{content:"\f058"}.fa-question-circle:before{content:"\f059"}.fa-info-circle:before{content:"\f05a"}.fa-crosshairs:before{content:"\f05b"}.fa-times-circle-o:before{content:"\f05c"}.fa-check-circle-o:before{content:"\f05d"}.fa-ban:before{content:"\f05e"}.fa-arrow-left:before{content:"\f060"}.fa-arrow-right:before{content:"\f061"}.fa-arrow-up:before{content:"\f062"}.fa-arrow-down:before{content:"\f063"}.fa-mail-forward:before,.fa-share:before{content:"\f064"}.fa-expand:before{content:"\f065"}.fa-compress:before{content:"\f066"}.fa-plus:before{content:"\f067"}.fa-minus:before{content:"\f068"}.fa-asterisk:before{content:"\f069"}.fa-exclamation-circle:before{content:"\f06a"}.fa-gift:before{content:"\f06b"}.fa-leaf:before{content:"\f06c"}.fa-fire:before{content:"\f06d"}.fa-eye:before{content:"\f06e"}.fa-eye-slash:before{content:"\f070"}.fa-warning:before,.fa-exclamation-triangle:before{content:"\f071"}.fa-plane:before{content:"\f072"}.fa-calendar:before{content:"\f073"}.fa-random:before{content:"\f074"}.fa-comment:before{content:"\f075"}.fa-magnet:before{content:"\f076"}.fa-chevron-up:before{content:"\f077"}.fa-chevron-down:before{content:"\f078"}.fa-retweet:before{content:"\f079"}.fa-shopping-cart:before{content:"\f07a"}.fa-folder:before{content:"\f07b"}.fa-folder-open:before{content:"\f07c"}.fa-arrows-v:before{content:"\f07d"}.fa-arrows-h:before{content:"\f07e"}.fa-bar-chart-o:before,.fa-bar-chart:before{content:"\f080"}.fa-twitter-square:before{content:"\f081"}.fa-facebook-square:before{content:"\f082"}.fa-camera-retro:before{content:"\f083"}.fa-key:before{content:"\f084"}.fa-gears:before,.fa-cogs:before{content:"\f085"}.fa-comments:before{content:"\f086"}.fa-thumbs-o-up:before{content:"\f087"}.fa-thumbs-o-down:before{content:"\f088"}.fa-star-half:before{content:"\f089"}.fa-heart-o:before{content:"\f08a"}.fa-sign-out:before{content:"\f08b"}.fa-linkedin-square:before{content:"\f08c"}.fa-thumb-tack:before{content:"\f08d"}.fa-external-link:before{content:"\f08e"}.fa-sign-in:before{content:"\f090"}.fa-trophy:before{content:"\f091"}.fa-github-square:before{content:"\f092"}.fa-upload:before{content:"\f093"}.fa-lemon-o:before{content:"\f094"}.fa-phone:before{content:"\f095"}.fa-square-o:before{content:"\f096"}.fa-bookmark-o:before{content:"\f097"}.fa-phone-square:before{content:"\f098"}.fa-twitter:before{content:"\f099"}.fa-facebook-f:before,.fa-facebook:before{content:"\f09a"}.fa-github:before{content:"\f09b"}.fa-unlock:before{content:"\f09c"}.fa-credit-card:before{content:"\f09d"}.fa-rss:before{content:"\f09e"}.fa-hdd-o:before{content:"\f0a0"}.fa-bullhorn:before{content:"\f0a1"}.fa-bell:before{content:"\f0f3"}.fa-certificate:before{content:"\f0a3"}.fa-hand-o-right:before{content:"\f0a4"}.fa-hand-o-left:before{content:"\f0a5"}.fa-hand-o-up:before{content:"\f0a6"}.fa-hand-o-down:before{content:"\f0a7"}.fa-arrow-circle-left:before{content:"\f0a8"}.fa-arrow-circle-right:before{content:"\f0a9"}.fa-arrow-circle-up:before{content:"\f0aa"}.fa-arrow-circle-down:before{content:"\f0ab"}.fa-globe:before{content:"\f0ac"}.fa-wrench:before{content:"\f0ad"}.fa-tasks:before{content:"\f0ae"}.fa-filter:before{content:"\f0b0"}.fa-briefcase:before{content:"\f0b1"}.fa-arrows-alt:before{content:"\f0b2"}.fa-group:before,.fa-users:before{content:"\f0c0"}.fa-chain:before,.fa-link:before{content:"\f0c1"}.fa-cloud:before{content:"\f0c2"}.fa-flask:before{content:"\f0c3"}.fa-cut:before,.fa-scissors:before{content:"\f0c4"}.fa-copy:before,.fa-files-o:before{content:"\f0c5"}.fa-paperclip:before{content:"\f0c6"}.fa-save:before,.fa-floppy-o:before{content:"\f0c7"}.fa-square:before{content:"\f0c8"}.fa-navicon:before,.fa-reorder:before,.fa-bars:before{content:"\f0c9"}.fa-list-ul:before{content:"\f0ca"}.fa-list-ol:before{content:"\f0cb"}.fa-strikethrough:before{content:"\f0cc"}.fa-underline:before{content:"\f0cd"}.fa-table:before{content:"\f0ce"}.fa-magic:before{content:"\f0d0"}.fa-truck:before{content:"\f0d1"}.fa-pinterest:before{content:"\f0d2"}.fa-pinterest-square:before{content:"\f0d3"}.fa-google-plus-square:before{content:"\f0d4"}.fa-google-plus:before{content:"\f0d5"}.fa-money:before{content:"\f0d6"}.fa-caret-down:before{content:"\f0d7"}.fa-caret-up:before{content:"\f0d8"}.fa-caret-left:before{content:"\f0d9"}.fa-caret-right:before{content:"\f0da"}.fa-columns:before{content:"\f0db"}.fa-unsorted:before,.fa-sort:before{content:"\f0dc"}.fa-sort-down:before,.fa-sort-desc:before{content:"\f0dd"}.fa-sort-up:before,.fa-sort-asc:before{content:"\f0de"}.fa-envelope:before{content:"\f0e0"}.fa-linkedin:before{content:"\f0e1"}.fa-rotate-left:before,.fa-undo:before{content:"\f0e2"}.fa-legal:before,.fa-gavel:before{content:"\f0e3"}.fa-dashboard:before,.fa-tachometer:before{content:"\f0e4"}.fa-comment-o:before{content:"\f0e5"}.fa-comments-o:before{content:"\f0e6"}.fa-flash:before,.fa-bolt:before{content:"\f0e7"}.fa-sitemap:before{content:"\f0e8"}.fa-umbrella:before{content:"\f0e9"}.fa-paste:before,.fa-clipboard:before{content:"\f0ea"}.fa-lightbulb-o:before{content:"\f0eb"}.fa-exchange:before{content:"\f0ec"}.fa-cloud-download:before{content:"\f0ed"}.fa-cloud-upload:before{content:"\f0ee"}.fa-user-md:before{content:"\f0f0"}.fa-stethoscope:before{content:"\f0f1"}.fa-suitcase:before{content:"\f0f2"}.fa-bell-o:before{content:"\f0a2"}.fa-coffee:before{content:"\f0f4"}.fa-cutlery:before{content:"\f0f5"}.fa-file-text-o:before{content:"\f0f6"}.fa-building-o:before{content:"\f0f7"}.fa-hospital-o:before{content:"\f0f8"}.fa-ambulance:before{content:"\f0f9"}.fa-medkit:before{content:"\f0fa"}.fa-fighter-jet:before{content:"\f0fb"}.fa-beer:before{content:"\f0fc"}.fa-h-square:before{content:"\f0fd"}.fa-plus-square:before{content:"\f0fe"}.fa-angle-double-left:before{content:"\f100"}.fa-angle-double-right:before{content:"\f101"}.fa-angle-double-up:before{content:"\f102"}.fa-angle-double-down:before{content:"\f103"}.fa-angle-left:before{content:"\f104"}.fa-angle-right:before{content:"\f105"}.fa-angle-up:before{content:"\f106"}.fa-angle-down:before{content:"\f107"}.fa-desktop:before{content:"\f108"}.fa-laptop:before{content:"\f109"}.fa-tablet:before{content:"\f10a"}.fa-mobile-phone:before,.fa-mobile:before{content:"\f10b"}.fa-circle-o:before{content:"\f10c"}.fa-quote-left:before{content:"\f10d"}.fa-quote-right:before{content:"\f10e"}.fa-spinner:before{content:"\f110"}.fa-circle:before{content:"\f111"}.fa-mail-reply:before,.fa-reply:before{content:"\f112"}.fa-github-alt:before{content:"\f113"}.fa-folder-o:before{content:"\f114"}.fa-folder-open-o:before{content:"\f115"}.fa-smile-o:before{content:"\f118"}.fa-frown-o:before{content:"\f119"}.fa-meh-o:before{content:"\f11a"}.fa-gamepad:before{content:"\f11b"}.fa-keyboard-o:before{content:"\f11c"}.fa-flag-o:before{content:"\f11d"}.fa-flag-checkered:before{content:"\f11e"}.fa-terminal:before{content:"\f120"}.fa-code:before{content:"\f121"}.fa-mail-reply-all:before,.fa-reply-all:before{content:"\f122"}.fa-star-half-empty:before,.fa-star-half-full:before,.fa-star-half-o:before{content:"\f123"}.fa-location-arrow:before{content:"\f124"}.fa-crop:before{content:"\f125"}.fa-code-fork:before{content:"\f126"}.fa-unlink:before,.fa-chain-broken:before{content:"\f127"}.fa-question:before{content:"\f128"}.fa-info:before{content:"\f129"}.fa-exclamation:before{content:"\f12a"}.fa-superscript:before{content:"\f12b"}.fa-subscript:before{content:"\f12c"}.fa-eraser:before{content:"\f12d"}.fa-puzzle-piece:before{content:"\f12e"}.fa-microphone:before{content:"\f130"}.fa-microphone-slash:before{content:"\f131"}.fa-shield:before{content:"\f132"}.fa-calendar-o:before{content:"\f133"}.fa-fire-extinguisher:before{content:"\f134"}.fa-rocket:before{content:"\f135"}.fa-maxcdn:before{content:"\f136"}.fa-chevron-circle-left:before{content:"\f137"}.fa-chevron-circle-right:before{content:"\f138"}.fa-chevron-circle-up:before{content:"\f139"}.fa-chevron-circle-down:before{content:"\f13a"}.fa-html5:before{content:"\f13b"}.fa-css3:before{content:"\f13c"}.fa-anchor:before{content:"\f13d"}.fa-unlock-alt:before{content:"\f13e"}.fa-bullseye:before{content:"\f140"}.fa-ellipsis-h:before{content:"\f141"}.fa-ellipsis-v:before{content:"\f142"}.fa-rss-square:before{content:"\f143"}.fa-play-circle:before{content:"\f144"}.fa-ticket:before{content:"\f145"}.fa-minus-square:before{content:"\f146"}.fa-minus-square-o:before{content:"\f147"}.fa-level-up:before{content:"\f148"}.fa-level-down:before{content:"\f149"}.fa-check-square:before{content:"\f14a"}.fa-pencil-square:before{content:"\f14b"}.fa-external-link-square:before{content:"\f14c"}.fa-share-square:before{content:"\f14d"}.fa-compass:before{content:"\f14e"}.fa-toggle-down:before,.fa-caret-square-o-down:before{content:"\f150"}.fa-toggle-up:before,.fa-caret-square-o-up:before{content:"\f151"}.fa-toggle-right:before,.fa-caret-square-o-right:before{content:"\f152"}.fa-euro:before,.fa-eur:before{content:"\f153"}.fa-gbp:before{content:"\f154"}.fa-dollar:before,.fa-usd:before{content:"\f155"}.fa-rupee:before,.fa-inr:before{content:"\f156"}.fa-cny:before,.fa-rmb:before,.fa-yen:before,.fa-jpy:before{content:"\f157"}.fa-ruble:before,.fa-rouble:before,.fa-rub:before{content:"\f158"}.fa-won:before,.fa-krw:before{content:"\f159"}.fa-bitcoin:before,.fa-btc:before{content:"\f15a"}.fa-file:before{content:"\f15b"}.fa-file-text:before{content:"\f15c"}.fa-sort-alpha-asc:before{content:"\f15d"}.fa-sort-alpha-desc:before{content:"\f15e"}.fa-sort-amount-asc:before{content:"\f160"}.fa-sort-amount-desc:before{content:"\f161"}.fa-sort-numeric-asc:before{content:"\f162"}.fa-sort-numeric-desc:before{content:"\f163"}.fa-thumbs-up:before{content:"\f164"}.fa-thumbs-down:before{content:"\f165"}.fa-youtube-square:before{content:"\f166"}.fa-youtube:before{content:"\f167"}.fa-xing:before{content:"\f168"}.fa-xing-square:before{content:"\f169"}.fa-youtube-play:before{content:"\f16a"}.fa-dropbox:before{content:"\f16b"}.fa-stack-overflow:before{content:"\f16c"}.fa-instagram:before{content:"\f16d"}.fa-flickr:before{content:"\f16e"}.fa-adn:before{content:"\f170"}.fa-bitbucket:before{content:"\f171"}.fa-bitbucket-square:before{content:"\f172"}.fa-tumblr:before{content:"\f173"}.fa-tumblr-square:before{content:"\f174"}.fa-long-arrow-down:before{content:"\f175"}.fa-long-arrow-up:before{content:"\f176"}.fa-long-arrow-left:before{content:"\f177"}.fa-long-arrow-right:before{content:"\f178"}.fa-apple:before{content:"\f179"}.fa-windows:before{content:"\f17a"}.fa-android:before{content:"\f17b"}.fa-linux:before{content:"\f17c"}.fa-dribbble:before{content:"\f17d"}.fa-skype:before{content:"\f17e"}.fa-foursquare:before{content:"\f180"}.fa-trello:before{content:"\f181"}.fa-female:before{content:"\f182"}.fa-male:before{content:"\f183"}.fa-gittip:before,.fa-gratipay:before{content:"\f184"}.fa-sun-o:before{content:"\f185"}.fa-moon-o:before{content:"\f186"}.fa-archive:before{content:"\f187"}.fa-bug:before{content:"\f188"}.fa-vk:before{content:"\f189"}.fa-weibo:before{content:"\f18a"}.fa-renren:before{content:"\f18b"}.fa-pagelines:before{content:"\f18c"}.fa-stack-exchange:before{content:"\f18d"}.fa-arrow-circle-o-right:before{content:"\f18e"}.fa-arrow-circle-o-left:before{content:"\f190"}.fa-toggle-left:before,.fa-caret-square-o-left:before{content:"\f191"}.fa-dot-circle-o:before{content:"\f192"}.fa-wheelchair:before{content:"\f193"}.fa-vimeo-square:before{content:"\f194"}.fa-turkish-lira:before,.fa-try:before{content:"\f195"}.fa-plus-square-o:before{content:"\f196"}.fa-space-shuttle:before{content:"\f197"}.fa-slack:before{content:"\f198"}.fa-envelope-square:before{content:"\f199"}.fa-wordpress:before{content:"\f19a"}.fa-openid:before{content:"\f19b"}.fa-institution:before,.fa-bank:before,.fa-university:before{content:"\f19c"}.fa-mortar-board:before,.fa-graduation-cap:before{content:"\f19d"}.fa-yahoo:before{content:"\f19e"}.fa-google:before{content:"\f1a0"}.fa-reddit:before{content:"\f1a1"}.fa-reddit-square:before{content:"\f1a2"}.fa-stumbleupon-circle:before{content:"\f1a3"}.fa-stumbleupon:before{content:"\f1a4"}.fa-delicious:before{content:"\f1a5"}.fa-digg:before{content:"\f1a6"}.fa-pied-piper:before{content:"\f1a7"}.fa-pied-piper-alt:before{content:"\f1a8"}.fa-drupal:before{content:"\f1a9"}.fa-joomla:before{content:"\f1aa"}.fa-language:before{content:"\f1ab"}.fa-fax:before{content:"\f1ac"}.fa-building:before{content:"\f1ad"}.fa-child:before{content:"\f1ae"}.fa-paw:before{content:"\f1b0"}.fa-spoon:before{content:"\f1b1"}.fa-cube:before{content:"\f1b2"}.fa-cubes:before{content:"\f1b3"}.fa-behance:before{content:"\f1b4"}.fa-behance-square:before{content:"\f1b5"}.fa-steam:before{content:"\f1b6"}.fa-steam-square:before{content:"\f1b7"}.fa-recycle:before{content:"\f1b8"}.fa-automobile:before,.fa-car:before{content:"\f1b9"}.fa-cab:before,.fa-taxi:before{content:"\f1ba"}.fa-tree:before{content:"\f1bb"}.fa-spotify:before{content:"\f1bc"}.fa-deviantart:before{content:"\f1bd"}.fa-soundcloud:before{content:"\f1be"}.fa-database:before{content:"\f1c0"}.fa-file-pdf-o:before{content:"\f1c1"}.fa-file-word-o:before{content:"\f1c2"}.fa-file-excel-o:before{content:"\f1c3"}.fa-file-powerpoint-o:before{content:"\f1c4"}.fa-file-photo-o:before,.fa-file-picture-o:before,.fa-file-image-o:before{content:"\f1c5"}.fa-file-zip-o:before,.fa-file-archive-o:before{content:"\f1c6"}.fa-file-sound-o:before,.fa-file-audio-o:before{content:"\f1c7"}.fa-file-movie-o:before,.fa-file-video-o:before{content:"\f1c8"}.fa-file-code-o:before{content:"\f1c9"}.fa-vine:before{content:"\f1ca"}.fa-codepen:before{content:"\f1cb"}.fa-jsfiddle:before{content:"\f1cc"}.fa-life-bouy:before,.fa-life-buoy:before,.fa-life-saver:before,.fa-support:before,.fa-life-ring:before{content:"\f1cd"}.fa-circle-o-notch:before{content:"\f1ce"}.fa-ra:before,.fa-rebel:before{content:"\f1d0"}.fa-ge:before,.fa-empire:before{content:"\f1d1"}.fa-git-square:before{content:"\f1d2"}.fa-git:before{content:"\f1d3"}.fa-hacker-news:before{content:"\f1d4"}.fa-tencent-weibo:before{content:"\f1d5"}.fa-qq:before{content:"\f1d6"}.fa-wechat:before,.fa-weixin:before{content:"\f1d7"}.fa-send:before,.fa-paper-plane:before{content:"\f1d8"}.fa-send-o:before,.fa-paper-plane-o:before{content:"\f1d9"}.fa-history:before{content:"\f1da"}.fa-genderless:before,.fa-circle-thin:before{content:"\f1db"}.fa-header:before{content:"\f1dc"}.fa-paragraph:before{content:"\f1dd"}.fa-sliders:before{content:"\f1de"}.fa-share-alt:before{content:"\f1e0"}.fa-share-alt-square:before{content:"\f1e1"}.fa-bomb:before{content:"\f1e2"}.fa-soccer-ball-o:before,.fa-futbol-o:before{content:"\f1e3"}.fa-tty:before{content:"\f1e4"}.fa-binoculars:before{content:"\f1e5"}.fa-plug:before{content:"\f1e6"}.fa-slideshare:before{content:"\f1e7"}.fa-twitch:before{content:"\f1e8"}.fa-yelp:before{content:"\f1e9"}.fa-newspaper-o:before{content:"\f1ea"}.fa-wifi:before{content:"\f1eb"}.fa-calculator:before{content:"\f1ec"}.fa-paypal:before{content:"\f1ed"}.fa-google-wallet:before{content:"\f1ee"}.fa-cc-visa:before{content:"\f1f0"}.fa-cc-mastercard:before{content:"\f1f1"}.fa-cc-discover:before{content:"\f1f2"}.fa-cc-amex:before{content:"\f1f3"}.fa-cc-paypal:before{content:"\f1f4"}.fa-cc-stripe:before{content:"\f1f5"}.fa-bell-slash:before{content:"\f1f6"}.fa-bell-slash-o:before{content:"\f1f7"}.fa-trash:before{content:"\f1f8"}.fa-copyright:before{content:"\f1f9"}.fa-at:before{content:"\f1fa"}.fa-eyedropper:before{content:"\f1fb"}.fa-paint-brush:before{content:"\f1fc"}.fa-birthday-cake:before{content:"\f1fd"}.fa-area-chart:before{content:"\f1fe"}.fa-pie-chart:before{content:"\f200"}.fa-line-chart:before{content:"\f201"}.fa-lastfm:before{content:"\f202"}.fa-lastfm-square:before{content:"\f203"}.fa-toggle-off:before{content:"\f204"}.fa-toggle-on:before{content:"\f205"}.fa-bicycle:before{content:"\f206"}.fa-bus:before{content:"\f207"}.fa-ioxhost:before{content:"\f208"}.fa-angellist:before{content:"\f209"}.fa-cc:before{content:"\f20a"}.fa-shekel:before,.fa-sheqel:before,.fa-ils:before{content:"\f20b"}.fa-meanpath:before{content:"\f20c"}.fa-buysellads:before{content:"\f20d"}.fa-connectdevelop:before{content:"\f20e"}.fa-dashcube:before{content:"\f210"}.fa-forumbee:before{content:"\f211"}.fa-leanpub:before{content:"\f212"}.fa-sellsy:before{content:"\f213"}.fa-shirtsinbulk:before{content:"\f214"}.fa-simplybuilt:before{content:"\f215"}.fa-skyatlas:before{content:"\f216"}.fa-cart-plus:before{content:"\f217"}.fa-cart-arrow-down:before{content:"\f218"}.fa-diamond:before{content:"\f219"}.fa-ship:before{content:"\f21a"}.fa-user-secret:before{content:"\f21b"}.fa-motorcycle:before{content:"\f21c"}.fa-street-view:before{content:"\f21d"}.fa-heartbeat:before{content:"\f21e"}.fa-venus:before{content:"\f221"}.fa-mars:before{content:"\f222"}.fa-mercury:before{content:"\f223"}.fa-transgender:before{content:"\f224"}.fa-transgender-alt:before{content:"\f225"}.fa-venus-double:before{content:"\f226"}.fa-mars-double:before{content:"\f227"}.fa-venus-mars:before{content:"\f228"}.fa-mars-stroke:before{content:"\f229"}.fa-mars-stroke-v:before{content:"\f22a"}.fa-mars-stroke-h:before{content:"\f22b"}.fa-neuter:before{content:"\f22c"}.fa-facebook-official:before{content:"\f230"}.fa-pinterest-p:before{content:"\f231"}.fa-whatsapp:before{content:"\f232"}.fa-server:before{content:"\f233"}.fa-user-plus:before{content:"\f234"}.fa-user-times:before{content:"\f235"}.fa-hotel:before,.fa-bed:before{content:"\f236"}.fa-viacoin:before{content:"\f237"}.fa-train:before{content:"\f238"}.fa-subway:before{content:"\f239"}.fa-medium:before{content:"\f23a"}
\ No newline at end of file
diff --git a/doc/sphinx/_static/headers.js b/doc/sphinx/_static/headers.js
new file mode 100644
index 0000000000000000000000000000000000000000..ac5cd6a0f63ebe0cacb6724ae3605c2ca12be20d
--- /dev/null
+++ b/doc/sphinx/_static/headers.js
@@ -0,0 +1,29 @@
+$(document).ready(function () {
+ $("div>h1").remove();
+ $("h2, h3, h4, h5, h6").each(
+ function(i, el) {
+ var icon = '<i class="fa fa-link"></i>';
+ var hlink = $(el).find(".headerlink");
+ var hlink_id = hlink.attr("href");
+ if (typeof(hlink_id) != 'undefined') {
+ $(hlink).remove();
+ $(el).prepend($("<a />").addClass("headerlink").attr("href", hlink_id).html(icon));
+ }
+ }
+ );
+ $(".admonition.note p.first.admonition-title").each(
+ function(i, el) {
+ var icon = '<i class="fa fa-comments-o"></i>';
+ $(el).html(icon + $(el).html());
+ }
+ );
+ $(".admonition.warning p.first.admonition-title").each(
+ function(i, el) {
+ var icon = '<i class="fa fa-exclamation-triangle"></i>';
+ $(el).html(icon + $(el).html());
+ }
+ );
+
+});
+
+// vim: syntax=javascript ts=2 sts=2 sw=2 expandtab
diff --git a/doc/sphinx/_static/sphinx_design.css b/doc/sphinx/_static/sphinx_design.css
new file mode 100644
index 0000000000000000000000000000000000000000..be522ef3bd74ea5bfe06497c921afdd17e6228ab
--- /dev/null
+++ b/doc/sphinx/_static/sphinx_design.css
@@ -0,0 +1,321 @@
+.b-tcontents .b-block-wrapper {
+ padding-top:35px;
+}
+.toctree-wrapper>ul,
+.toctree-l1>ul {
+ list-style:none;
+}
+.toctree-wrapper>ul {
+ margin:0 0 0 70px;
+}
+.toctree-l1 {
+ margin:0 0 20px 0;
+}
+li.toctree-l1>a {
+ color:#168de2;
+ font-size:20px;
+ margin:0;
+ text-decoration:none;
+}
+li.toctree-l1>a:hover {
+ text-decoration:underline;
+}
+.toctree-l1>ul {
+ padding:6px 0 0 18px;
+}
+.toctree-l2 {
+ font-size:16px;
+ color:#797979;
+ line-height:1.2em;
+ padding:0 0 8px 0;
+}
+.toctree-l2 a {
+ color:inherit;
+}
+.toctree-l2:before {
+ content:'-';
+ display:inline-block;
+ float:left;
+ margin:0 0 0 -11px;
+}
+.b-tcontents_full-list,
+.b-tcontents_full-sublist {
+ margin:0;
+ padding:0;
+ display:block;
+ list-style:none;
+}
+.b-tcontents_full-list,
+.b-tcontents_full-sublist {
+ list-style:none;
+}
+.b-tcontents_full-list {
+
+}
+.b-tcontents_full-list-item {
+ margin:0 0 28px 0;
+}
+.b-tcontents_full-list-item-title {
+ color:#404040;
+ font-size:16px;
+ margin:0;
+}
+.b-tcontents_full-list-item-title a {
+ color:inherit;
+ text-decoration:none;
+}
+.b-tcontents_full-list-item.p-active .b-tcontents_full-list-item-title a {
+ color:#168de2;
+ text-decoration:underline;
+}
+.b-tcontents_full-list-item-desc {
+ color:#767676;
+ font-size:12px;
+ padding:0;
+}
+.b-tcontents_full-sublist {
+ padding:14px 0 0 18px;
+}
+.b-tcontents_full-sublist-item {
+ font-size:12px;
+ color:#404040;
+ line-height:1.2em;
+ padding:0 0 8px 0;
+}
+.b-tcontents_full-sublist-item a {
+ color:#168de2;
+}
+
+.toctree-wrapper>ul {
+ margin:0;
+ padding:0;
+ display:block;
+ list-style:none;
+}
+
+.toctree-l2:before {
+ content:'-';
+ display:inline-block;
+ float:left;
+ margin:0 0 0 -11px;
+}
+
+article>div.section>h1 {
+ visibility: hidden;
+ margin: 0;
+ font-size: 0;
+}
+
+.b-article p {
+ padding: 0 0 10px 0;
+}
+.b-article {
+ line-height: 1.3em;
+}
+.b-article h2 {
+ font-size: 23px;
+ margin: 16px 0;
+}
+a.headerlink {
+ margin: 5px;
+ font-size: 16px;
+}
+.b-documentation_top.p-documentation_in .b-section-title {
+ margin:0 0 17px 0;
+}
+.b-documentation_top.p-documentation_in .b-block-wrapper {
+ padding: 20px 0 21px 0;
+}
+
+.faq tr.field-even td {
+ padding-bottom: 20px;
+}
+
+.b-prev,
+.b-next {
+ display:inline-block;
+ background:#ececec;
+ color:#404040;
+ font-size:14px;
+ text-decoration:none;
+ padding:3px 11px 4px 11px;
+ -webkit-border-radius: 4px;
+ -moz-border-radius: 4px;
+ border-radius: 4px;
+}
+.b-prev:hover,
+.b-next:hover {
+ text-decoration:none;
+ color:#404040;
+}
+.b-prev:before,
+.b-next:after {
+ vertical-align:middle;
+ margin:0 9px 0 0;
+ content:'';
+ display:inline-block;
+ width: 5px;
+ height: 10px;
+ background: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAKBAMAAACOF4kDAAAAIVBMVEUAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABt0UjBAAAAC3RSTlMAs62OCIV8cj80DyOnhogAAAAlSURBVAjXY2DgMmBgcBZgYAlUYGATmsBQKMEAwiA2SAwkB1IDAFc2BGddDNbMAAAAAElFTkSuQmCC') -0px -0px no-repeat;
+}
+
+.b-next:after {
+ -ms-transform: rotate(180deg); /* IE 9 */
+ -webkit-transform: rotate(180deg); /* Chrome, Safari, Opera */
+ transform: rotate(180deg);
+ margin:0 0 0 9px;
+}
+.b-next {
+ float: right;
+}
+.b-page_over-head {
+ margin: -13px 0 0 0;
+}
+.b-page_over-tail {
+ margin: 25px 0 -50px 0;
+}
+
+.b-article ul {
+ padding: 0 0 0 13px;
+}
+
+.b-article p {
+ padding: 7px 0 7px 0;
+}
+
+.b-article h2,
+.b-article h3,
+.b-article h4,
+.b-article h5 {
+ margin: 16px 0 16px -25px;
+ font-weight: bold;
+}
+
+.b-article ol {
+ padding-left: 30px;
+}
+
+.b-page_header {
+ margin-bottom: 10px;
+}
+
+.headerlink {
+/* position: absolute;*/
+ left: -0.5em;
+ opacity: 0;
+
+ -webkit-transition: opacity 0.2s ease-in-out 0.1s;
+ -moz-transition: opacity 0.2s ease-in-out 0.1s;
+ -ms-transition: opacity 0.2s ease-in-out 0.1s;
+}
+
+h2:hover .headerlink,
+h3:hover .headerlink,
+h4:hover .headerlink,
+h5:hover .headerlink,
+h6:hover .headerlink {
+ opacity: 1;
+}
+
+table.docutils.footnote {
+ font-size: 14px;
+}
+
+tr.field td p {
+ padding: 0px;
+}
+
+.b-cols_content {
+ width:960px;
+ margin:0 auto;
+ padding:0 0 30px 0;
+}
+.b-cols_content_left {
+ position:relative;
+ float:left;
+ width:295px;
+ padding:30px 0 0 0;
+}
+.b-cols_content_right {
+ float:right;
+ width:100%;
+ margin:0 0 0 -295px;
+}
+.b-cols_content_right-slot {
+ margin:0 0 0 340px;
+ padding:18px 0 0 0;
+}
+
+.p-cols_design .b-wrapper {
+ background: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAEAAAAAARAQMAAABnOfukAAAABlBMVEUAAAD19fWydBufAAAAAXRSTlMAQObYZgAAADZJREFUaN7t0gEBAAAIAiD/n7YBTRA2kO4InwDruiMIgAAIgAAIgAAIsK47ggAIgAAIgAAIwAHksoxHlAvP9AAAAABJRU5ErkJggg==') 50% -0px repeat-y;
+}
+
+div.toctree-wrapper.compound {
+ padding: 20px 0px 0px 0px;
+}
+
+div.highlight {
+ text-align: left;
+ -webkit-border-radius: 7px;
+ -moz-border-radius: 7px;
+ border-radius: 7px;
+ overflow-x: auto;
+ margin: 5px 0px;
+ font-size: 13px;
+}
+
+div.admonition {
+ -webkit-border-radius: 10px;
+ -moz-border-radius: 10px;
+ border-radius: 10px;
+ padding: 10px;
+ margin: 5px 0;
+}
+
+div.admonition.note {
+ background: rgb(223,223,223);
+}
+
+div.admonition.warning {
+ background: rgb(255,228,228);
+}
+
+p.admonition-title {
+ font-size: 16px;
+ font-weight: bold;
+}
+
+p.admonition-title .fa {
+ margin: 0 10px 0 0;
+}
+
+.descname {
+ font-weight: 600;
+}
+
+dd table.field-list {
+ margin-top: 10px;
+}
+
+td.field-body {
+ padding-left: 10px;
+ padding-bottom: 10px;
+}
+
+th.field-name {
+ text-align: left;
+ font-weight: normal;
+}
+
+table.docutils.field-list {
+ font-size: 13px;
+}
+
+div.table tbody {
+ vertical-align: middle;
+ text-align: center;
+}
+
+div.table td {
+ padding: 5px 15px;
+}
diff --git a/doc/sphinx/_templates/base b/doc/sphinx/_templates/base
new file mode 100644
index 0000000000000000000000000000000000000000..4be6540f6f928a2bbab388489402b908979f40cb
--- /dev/null
+++ b/doc/sphinx/_templates/base
@@ -0,0 +1,62 @@
+{% import "menu" as menu %}
+{% include "custom_sphinx" with context %}
+
+<!doctype html>
+
+<html>
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+ <meta http-equiv="content-type" content="text/html; charset=utf-8" />
+ <title>{{ title | cleantitle }}</title>
+ <link rel="shortcut icon" href="/theme/favicon.ico" />
+ <link rel="stylesheet" href="/theme/design.css" />
+ <link rel="stylesheet" href="/theme/pygmentize.css" />
+ <script src="http://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
+ <script src="/js/select.js"></script>
+ <!--[if lt IE 9]>
+ <script src="scripts/ie8.js"></script>
+ <link rel="stylesheet" href="/theme/new/ie8.css" />
+ <![endif]-->
+ {% block header_scripts %}
+ {% endblock header_scripts %}
+ {% include "script" ignore missing %}
+ </head>
+ {% if render_sidebar %}
+ <body class="p-cols_design">
+ {% else %}
+ <body class="b-main">
+ {% endif%}
+ <div class="b-wrapper">
+ <!-- HEADER > -->
+ <header class="b-header">
+ <div class="b-header-wrapper">
+ <nav class="b-header_menu">
+ {{ menu.i_menu({slug:'documentation'}) }}
+ </nav>
+ </div>
+ </header>
+ <!-- < HEADER -->
+
+ <div class="b-content b-clearbox">
+ {% block content %}
+ {% endblock content %}
+ </div>
+ </div>
+
+ <!-- FOOTER > -->
+ <footer class="b-footer">
+ <div class="b-footer-wrapper">
+ <nav class="b-footer_menu">
+ <div class="b-footer-copyright">© 2015 - Tarantool. All right reserved.</div>
+ {{ menu.i_menu({slug:'documentation'}) }}
+ <div class="b-footer-other">
+ <a href="http://stable.tarantool.org">1.5 web site and downloads</a>
+ </div>
+ </nav>
+ </div>
+ </footer>
+ <!-- < FOOTER -->
+ </body>
+</html>
+
+{# vim: syntax=htmldjango ts=2 sts=2 sw=2 expandtab #}
diff --git a/doc/sphinx/_templates/breadcrumbs b/doc/sphinx/_templates/breadcrumbs
new file mode 100644
index 0000000000000000000000000000000000000000..8017833d2f1a4d6076bcf26037d699450a9c3855
--- /dev/null
+++ b/doc/sphinx/_templates/breadcrumbs
@@ -0,0 +1,19 @@
+{% macro breadcrumbs() %}
+{% if title != 'Documentation' %}
+<div class="b-page_header">
+ <ul class="b-path-list">
+ <li class="b-path-list-item">
+ <a href="/doc/" class="b-path-list-item-url">Documentation</a>
+ </li>
+ {% for elem in parents %}
+ <li class="b-path-list-item">
+ <a href="{{ elem.link|e }}" class="b-path-list-item-url">{{ elem.title }}</a>
+ </li>
+ {% endfor %}
+ <li class="b-path-list-item"><span class="b-path_current">{{ title }}</span></li>
+ </ul>
+</div>
+{% endif %}
+{% endmacro %}
+
+{# vim: syntax=htmldjango ts=2 sts=2 sw=2 expandtab #}
diff --git a/doc/sphinx/_templates/custom_sphinx b/doc/sphinx/_templates/custom_sphinx
new file mode 100644
index 0000000000000000000000000000000000000000..5cdd90711dbabcd13768c3112988fcbccd72229f
--- /dev/null
+++ b/doc/sphinx/_templates/custom_sphinx
@@ -0,0 +1,30 @@
+{% if sphinx_version is defined %}
+ {%- macro script() %}
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '{{ url_root }}',
+ VERSION: '{{ release|e }}',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '{{ '' if no_search_suffix else file_suffix }}',
+ HAS_SOURCE: {{ has_source|lower }}
+ };
+ </script>
+ {%- for scriptfile in script_files %}
+ <script type="text/javascript" src="{{ pathto(scriptfile, 1) }}"></script>
+ {%- endfor %}
+ {%- endmacro %}
+ {%- set render_sidebar = (not embedded) and (not theme_nosidebar|tobool) and
+ (sidebars != []) %}
+
+ {% block header_script %}
+ {{ script() }}
+ {% endblock header_script %}
+
+ {%- macro sidebar() %}
+ {%- endmacro %}
+{% else %}
+ {%- macro script() %}
+ {%- endmacro %}
+{% endif %}
+
+{# vim: syntax=htmldjango ts=2 sts=2 sw=2 expandtab #}
diff --git a/doc/sphinx/_templates/layout.html b/doc/sphinx/_templates/layout.html
new file mode 100644
index 0000000000000000000000000000000000000000..de498dff756ead256a5491ab37b8d27054b3d400
--- /dev/null
+++ b/doc/sphinx/_templates/layout.html
@@ -0,0 +1,58 @@
+{% extends "base" %}
+{% import "breadcrumbs" as breadcrumbs with context %}
+{% import "navbar" as navbar with context %}
+
+{% block header_scripts %}
+ <link rel="stylesheet" href="/doc/_static/sphinx_design.css" />
+ <link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
+ <script type="text/javascript" src="/doc/_static/headers.js"></script>
+ {{ super() }}
+{% endblock header_scripts %}
+
+
+{% if title != 'Documentation' %}
+{% set render_sidebar = true %}
+{% endif %}
+
+{% block content %}
+{% if render_sidebar %}
+<section class="b-lightgray_block b-documentation_top b-clearbox p-documentation_in">
+{% else %}
+<section class="b-lightgray_block b-documentation_top b-clearbox">
+{% endif %}
+ <div class="b-block-wrapper">
+ <h2 class="b-section-title">{{ title }}</h2>
+ <!--div class="b-search">
+ <input class="b-search-text" data-placeholder="Search in documentation" />
+ <input class="b-search-but" type="submit" />
+ </div-->
+ </div>
+</section>
+{% if render_sidebar %}
+<div class="b-cols_content b-clearbox">
+ <div class="b-cols_content_left">
+ {{ toctree(maxdepth=2) }}
+ {% block sidebar %} {% endblock %}
+ </div>
+ <div class="b-cols_content_right">
+ <div class="b-cols_content_right-slot">
+{% else %}
+<section class="b-block b-documentation">
+ <div class="b-block-wrapper">
+{% endif %}
+ {{ breadcrumbs.breadcrumbs() }}
+ <article class="b-article">
+ {% block body %} {% endblock %}
+ </article>
+ {{ navbar.navbar(False) }}
+{% if render_sidebar %}
+ </div>
+ </div>
+</div>
+{% else %}
+ </div>
+</section>
+{% endif %}
+{% endblock content%}
+
+{# vim: syntax=htmldjango ts=2 sts=2 sw=2 expandtab #}
diff --git a/doc/sphinx/_templates/menu b/doc/sphinx/_templates/menu
new file mode 100644
index 0000000000000000000000000000000000000000..a475b471f6367b29d06dea4f1a13e875108ff588
--- /dev/null
+++ b/doc/sphinx/_templates/menu
@@ -0,0 +1,31 @@
+
+{# Modify i_links to add records to site #}
+{% set i_links = [
+ ("Overview", "http://tarantool.org"),
+ ("Try", "http://try.tarantool.org"),
+ ("Documentation", "http://tarantool.org/doc/"),
+ ("Download", "http://tarantool.org/download.html"),
+ ("Rocks", "http://rocks.tarantool.org")
+] %}
+
+{% macro i_menu(page) %}
+ <ul class="b-menu">
+ {% for item in i_links %}
+ <li class="b-menu-item">
+ {% if
+ (item[0] == "Overview" and page.slug == "index") or
+ (item[0] == "Documentation" and page.slug == "documentation") or
+ (item[0] == "Download" and page.slug == "download") or
+ (item[0] == "Try" and page.slug == "try") or
+ (item[0] == "Rocks" and page.slug == "rocks")
+ %}
+ <a href="{{ item[1] }}" class="b-menu-item-url p-active">{{ item[0] }}</a>
+ {% else %}
+ <a href="{{ item[1] }}" class="b-menu-item-url">{{ item[0] }}</a>
+ {% endif %}
+ </li>
+ {% endfor %}
+ </ul>
+{% endmacro %}
+
+{# vim: syntax=htmldjango ts=2 sts=2 sw=2 expandtab #}
diff --git a/doc/sphinx/_templates/navbar b/doc/sphinx/_templates/navbar
new file mode 100644
index 0000000000000000000000000000000000000000..97e17fd2923bd55f921d3ef224d9827844b17c1a
--- /dev/null
+++ b/doc/sphinx/_templates/navbar
@@ -0,0 +1,17 @@
+{% macro navbar(head=True) %}
+{% if next and prev %}
+{% if head %}
+<div class="b-page_over-head">
+{% else %}
+<div class="b-page_over-tail">
+{% endif %}
+ {% if prev %}
+ <a href="{{ prev.link|e }}" class="b-prev">{{ prev.title }}</a>
+ {% endif %}
+ {% if next %}
+ <a href="{{ next.link|e }}" class="b-next">{{ next.title }}</a>
+ {% endif %}
+</div>
+{% endif %}
+{% endmacro %}
+
diff --git a/doc/sphinx/_templates/page.html b/doc/sphinx/_templates/page.html
new file mode 100644
index 0000000000000000000000000000000000000000..b4544a26eb1f7153d2a74d389eb5dfb1ad645d7b
--- /dev/null
+++ b/doc/sphinx/_templates/page.html
@@ -0,0 +1,13 @@
+{#
+ basic/page.html
+ ~~~~~~~~~~~~~~~
+
+ Master template for simple pages.
+
+ :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
+ :license: BSD, see LICENSE for details.
+#}
+{%- extends "layout.html" %}
+{% block body %}
+ {{ body }}
+{% endblock %}
diff --git a/doc/sphinx/_templates/script b/doc/sphinx/_templates/script
new file mode 100644
index 0000000000000000000000000000000000000000..c6122411a418c01be5ca4fc78e2b1573037e54ce
--- /dev/null
+++ b/doc/sphinx/_templates/script
@@ -0,0 +1,30 @@
+<script type="text/javascript">
+ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+ })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+ ga('create', 'UA-22120502-1', 'auto');
+ ga('send', 'pageview');
+</script>
+
+<!-- Rating@Mail.ru counter -->
+<script type="text/javascript">
+ var _tmr = _tmr || [];
+ _tmr.push({id: "2284916", type: "pageView", start: (new Date()).getTime()});
+ (function (d, w) {
+ var ts = d.createElement("script"); ts.type = "text/javascript"; ts.async = true;
+ ts.src = (d.location.protocol == "https:" ? "https:" : "http:") + "//top-fwz1.mail.ru/js/code.js";
+ var f = function () {var s = d.getElementsByTagName("script")[0]; s.parentNode.insertBefore(ts, s);};
+ if (w.opera == "[object Opera]") { d.addEventListener("DOMContentLoaded", f, false); } else { f(); }
+ })(document, window);
+</script>
+<noscript>
+ <div style="position:absolute;left:-10000px;">
+ <img src="//top-fwz1.mail.ru/counter?id=2284916;js=na" style="border:0;"
+ height="1" width="1" alt="Рейтинг@Mail.ru" />
+ </div>
+</noscript>
+<!-- //Rating@Mail.ru counter -->
+
+{# vim: syntax=htmldjango ts=2 sts=2 sw=2 expandtab #}
diff --git a/doc/sphinx/_templates/theme.conf b/doc/sphinx/_templates/theme.conf
new file mode 100644
index 0000000000000000000000000000000000000000..f7283730b54c0dd6d347a117be3cc19614b52d87
--- /dev/null
+++ b/doc/sphinx/_templates/theme.conf
@@ -0,0 +1,8 @@
+[theme]
+inherit = none
+stylesheet = basic.css
+pygments_style = none
+
+[options]
+nosidebar = false
+sidebarwidth = 230
\ No newline at end of file
diff --git a/doc/sphinx/book/administration.rst b/doc/sphinx/book/administration.rst
new file mode 100644
index 0000000000000000000000000000000000000000..3364011fac09ba67d9bd71c0691dc97124719e85
--- /dev/null
+++ b/doc/sphinx/book/administration.rst
@@ -0,0 +1,499 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Server administration
+-------------------------------------------------------------------------------
+
+Typical server administration tasks include starting and stopping the server,
+reloading configuration, taking snapshots, log rotation.
+
+=====================================================================
+ Server signal handling
+=====================================================================
+
+The server is configured to shut down gracefully on SIGTERM and SIGINT
+(keyboard interrupt) or SIGHUP. SIGUSR1 can be used to save a snapshot. All
+other signals are blocked or ignored. The signals are processed in the main
+thread event loop. Thus, if the control flow never reaches the event loop
+(thanks to a runaway stored procedure), the server stops responding to any
+signal, and can only be killed with SIGKILL (this signal can not be ignored).
+
+=====================================================================
+ Using ``tarantool`` as a client
+=====================================================================
+
+.. program:: tarantool
+
+If ``tarantool`` is started without a Lua script to run, it automatically
+enters interactive mode. There will be a prompt ("``tarantool>``") and it will
+be possible to enter requests. When used this way, ``tarantool`` can be
+a client for a remote server.
+
+This section shows all legal syntax for the tarantool program, with short notes
+and examples. Other client programs may have similar options and request
+syntaxes. Some of the information in this section is duplicated in the
+:doc:`/book/configuration` chapter.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Conventions used in this section
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Tokens are character sequences which are treated as syntactic units within
+requests. Square brackets [ and ] enclose optional syntax. Three dots in a
+row ... mean the preceding tokens may be repeated. A vertical bar | means
+the preceding and following tokens are mutually exclusive alternatives.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Options when starting client from the command line
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+General form:
+
+.. code-block:: bash
+
+ $ tarantool
+ OR
+ $ tarantool <options>
+ OR
+ $ tarantool <lua-initialization-file> [arguments]
+
+<lua-initialization-file> can be any script containing code for initializing.
+Effect: The code in the file is executed during startup. Example: ``init.lua``.
+Notes: If a script is used, there will be no prompt. The script should contain
+configuration information including "``box.cfg{...listen=...}``" or
+"``box.listen(...)``" so that a separate program can connect to the server via
+one of the ports.
+
+Option is one of the following (in alphabetical order by the long form of the
+option):
+
+.. option:: -?, -h, --help
+
+ Client displays a help message including a list of options.
+
+ .. code-block:: bash
+
+ tarantool --help
+
+ The program stops after displaying the help.
+
+.. option:: -V, --version
+
+ .. code-block:: bash
+
+ tarantool --version
+
+ The program stops after displaying the version.
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Tokens, requests, and special key combinations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Procedure identifiers are: Any sequence of letters, digits, or underscores
+which is legal according to the rules for Lua identifiers. Procedure
+identifiers are also called function names. Notes: function names are case
+insensitive so ``insert`` and ``Insert`` are not the same thing.
+
+String literals are: Any sequence of zero or more characters enclosed in
+single quotes. Double quotes are legal but single quotes are preferred.
+Enclosing in double square brackets is good for multi-line strings as
+described in `Lua documentation`_.
+
+.. _Lua documentation: http://www.lua.org/pil/2.4.html
+
+Example:
+
+.. code-block:: lua
+
+ 'Hello, world', 'A', [[A\B!]].
+
+Numeric literals are: Character sequences containing only digits, optionally
+preceded by + or -. Examples: 55, -. Notes: Tarantool NUM data type is
+unsigned, so -1 is understood as a large unsigned number.
+
+Single-byte tokens are: * or , or ( or ). Examples: * , ( ).
+
+Tokens must be separated from each other by one or more spaces, except that
+spaces are not necessary around single-byte tokens or string literals.
+
+.. _setting delimiter:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Requests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Generally requests are entered following the prompt in interactive mode while
+``tarantool`` is running. (A prompt will be the word tarantool and a
+greater-than sign, for example ``tarantool>``). The end-of-request marker is by
+default a newline (line feed).
+
+For multi-line requests, it is possible to change the end-of-request marker.
+Syntax: ``console = require('console'); console.delimiter(string-literal)``.
+The string-literal must be a value in single quotes. Effect: string becomes
+end-of-request delimiter, so newline alone is not treated as end of request.
+To go back to normal mode: ``console.delimiter('')string-literal``. Example:
+
+.. code-block:: lua
+
+ console = require('console'); console.delimiter('!')
+ function f ()
+ statement_1 = 'a'
+ statement_2 = 'b'
+ end!
+ console.delimiter('')!
+
+In *interactive* mode, one types requests and gets results. Typically the
+requests are typed in by the user following prompts. Here is an example of
+an interactive-mode tarantool client session:
+
+.. code-block:: bash
+
+ $ tarantool
+ [ tarantool will display an introductory message
+ including version number here ]
+ tarantool> box.cfg{listen=3301}
+ [ tarantool will display configuration information
+ here ]
+ tarantool> s = box.schema.space.create('tester')
+ [ tarantool may display an in-progress message here ]
+ ---
+ ...
+ tarantool> s:create_index('primary', {type = 'hash', parts = {1, 'NUM'}})
+ ---
+ ...
+ tarantool> box.space.tester:insert{1,'My first tuple'}
+ ---
+ - [1, 'My first tuple']
+ ...
+ tarantool> box.space.tester:select(1)
+ ---
+ - - [1, 'My first tuple']
+ ...
+ tarantool> box.space.tester:drop()
+ ---
+ ...
+ tarantool> os.exit()
+ 2014-04-30 10:28:00.886 [20436] main/101/spawner I> Exiting: master shutdown
+ $
+
+Explanatory notes about what tarantool displayed in the above example:
+
+* Many requests return typed objects. In the case of "``box.cfg{listen=3301}``",
+ this result is displayed on the screen. If the request had assigned the result
+ to a variable, for example "``c = box.cfg{listen=3301}``", then the result
+ would not have been displayed on the screen.
+* A display of an object always begins with "``---``" and ends with "``...``".
+* The insert request returns an object of type = tuple, so the object display line begins with a single dash ('``-``'). However, the select request returns an object of type = table of tuples, so the object display line begins with two dashes ('``- -``').
+
+=====================================================================
+ Utility ``tarantoolctl``
+=====================================================================
+
+.. program:: tarantoolctl
+
+With ``tarantoolctl`` one can say: "start an instance of the Tarantool server
+which runs a single user-written Lua program, allocating disk resources
+specifically for that program, via a standardized deployment method."
+If Tarantool was downloaded from source, then the script is in
+:file:`~/extra/dist/tarantoolctl`. If Tarantool was installed with Debian or
+Red Hat installation packages, the script is renamed :program:`tarantoolctl`
+and is in :file:`/usr/bin/tarantoolctl`. The script handles such things as:
+starting, stopping, rotating logs, logging in to the application's console,
+and checking status.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ configuring for tarantoolctl
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :program:`tarantoolctl` script will read a configuration file named
+:file:`/etc/sysconfig/tarantool`, or :file:`/etc/default/tarantool`. Most
+of the settings are similar to the settings used by ``box.cfg{...};``
+however, tarantoolctl adjusts some of them by adding an application name.
+A copy of :file:`/etc/sysconfig/tarantool`, with defaults for all settings,
+would look like this:
+
+.. code-block:: lua
+
+ default_cfg = {
+ pid_file = "/var/run/tarantool",
+ wal_dir = "/var/lib/tarantool",
+ snap_dir = "/var/lib/tarantool",
+ sophia_dir = "/var/lib/tarantool",
+ logger = "/var/log/tarantool",
+ username = "tarantool",
+ }
+ instance_dir = "/etc/tarantool/instances.enabled"
+
+The settings in the above script are:
+
+``pid_file``
+ The directory for the pid file and control-socket file. The
+ script will add ":file:`/instance-name`" to the directory name.
+
+``wal_dir``
+ The directory for the write-ahead :file:`*.xlog` files. The
+ script will add ":file:`/instance-name`" to the directory-name.
+
+``snap_dir``
+ The directory for the snapshot :file:`*.snap` files. The script
+ will add ":file:`/instance-name`" to the directory-name.
+
+``sophia_dir``
+ The directory for the sophia-storage-engine files. The script
+ will add ":file:`/sophia/instance-name`" to the directory-name.
+
+``logger``
+ The place where the application log will go. The script will
+ add ":file:`/instance-name.log`" to the name.
+
+``username``
+ the user that runs the tarantool server. This is the operating-system
+ user name rather than the Tarantool-client user name.
+
+``instance_dir``
+ the directory where all applications for this host are stored. The user
+ who writes an application for :program:`tarantoolctl` must put the
+ application's source code in this directory, or a symbolic link. For
+ examples in this section the application name my_app will be used, and
+ its source will have to be in :file:`instance_dir/my_app.lua`.
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ commands for tarantoolctl
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The command format is ``tarantoolctl operation application-name``, where
+operation is one of: start, stop, status, logrotate, enter. Thus ...
+
+.. option:: start <app_name>
+
+ starts application <app_name>
+
+.. option:: stop <app_name>
+
+ stops <app_name>
+
+.. option:: enter <app_name>
+
+ show <app_name>'s admin console, if it has one
+
+.. option:: logrotate <app_name>
+
+ rotate <app_name>'s log files (make new, remove old)
+
+.. option:: status <app_name>
+
+ check <app_name>'s status
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ typical code snippets for tarantoolctl
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A user can check whether my_app is running with these lines:
+
+.. code-block:: bash
+
+ if tarantoolctl status my_app; then
+ ...
+ fi
+
+A user can initiate, for boot time, an init.d set of instructions:
+
+.. code-block:: bash
+
+ for (each file mentioned in the instance_dir directory):
+ tarantoolctl start `basename $ file .lua`
+
+A user can set up a further configuration file for log rotation, like this:
+
+.. code-block:: lua
+
+ /path/to/tarantool/*.log {
+ daily
+ size 512k
+ missingok
+ rotate 10
+ compress
+ delaycompress
+ create 0640 tarantool adm
+ postrotate
+ /path/to/tarantoolctl logrotate `basename $ 1 .log`
+ endscript
+ }
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ A detailed example for tarantoolctl
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The example's objective is: make a temporary directory where tarantoolctl
+can start a long-running application and monitor it.
+
+The assumptions are: the root password is known, the computer is only being used
+for tests, the Tarantool server is ready to run but is not currently running,
+and there currently is no directory named :file:`tarantool_test`.
+
+Create a directory named /tarantool_test:
+
+.. code-block:: bash
+
+ sudo mkdir /tarantool_test
+
+Copy tarantoolctl to /tarantool_test. If you made a source
+download to ~/tarantool-master, then
+
+.. code-block:: bash
+
+ sudo cp ~/tarantool-master/extra/dist/tarantoolctl /tarantool_test/tarantoolctl
+
+If the file was named tarantoolctl and placed on /usr/bin/tarantoolctl, then
+
+.. code-block:: bash
+
+ sudo cp /usr/bin/tarantoolctl /tarantool_test/tarantoolctl
+
+Check and possibly change the first line of /tarantool_test/tarantoolctl.
+Initially it says
+
+.. code-block:: bash
+
+ #!/usr/bin/env tarantool
+
+If that is not correct, edit tarantoolctl and change the line. For example,
+if the Tarantool server is actually on /home/user/tarantool-master/src/tarantool,
+change the line to
+
+.. code-block:: bash
+
+ #!/usr/bin/env /home/user/tarantool-master/src/tarantool
+
+Save a copy of /etc/sysconfig/tarantool, if it exists.
+
+Edit /etc/sysconfig/tarantool. It might be necessary to say sudo mkdir /etc/sysconfig first. Let the new file contents be:
+
+.. code-block:: lua
+
+ default_cfg = {
+ pid_file = "/tarantool_test/my_app.pid",
+ wal_dir = "/tarantool_test",
+ snap_dir = "/tarantool_test",
+ sophia_dir = "/tarantool_test",
+ logger = "/tarantool_test/log",
+ username = "tarantool",
+ }
+ instance_dir = "/tarantool_test"
+
+Make the my_app application file, that is, /tarantool_test/my_app.lua. Let the file contents be:
+
+.. code-block:: lua
+
+ box.cfg{listen = 3301}
+ box.schema.user.passwd('Gx5!')
+ box.schema.user.grant('guest','read,write,execute','universe')
+ fiber = require('fiber')
+ box.schema.space.create('tester')
+ box.space.tester:create_index('primary',{})
+ i = 0
+ while 0 == 0 do
+ fiber.sleep(5)
+ i = i + 1
+ print('insert ' .. i)
+ box.space.tester:insert{i, 'my_app tuple'}
+ end
+
+Tell tarantoolctl to start the application ...
+
+.. code-block:: bash
+
+ cd /tarantool_test
+ sudo ./tarantoolctl start my_app
+
+... expect to see messages indicating that the instance has started. Then ...
+
+.. code-block:: bash
+
+ ls -l /tarantool_test/my_app
+
+... expect to see the .snap file, .xlog file, and sophia directory. Then ...
+
+.. code-block:: bash
+
+ less /tarantool_test/log/my_app.log
+
+... expect to see the contents of my_app's log, including error messages, if any. Then ...
+
+.. code-block:: bash
+
+ cd /tarantool_test
+ #assume that 'tarantool' invokes the tarantool server
+ sudo tarantool
+ box.cfg{}
+ console = require('console')
+ console.connect('localhost:3301')
+ box.space.tester:select({0},{iterator='GE'})
+
+... expect to see several tuples that my_app has created.
+
+Stop. The only clean way to stop my_app is with tarantoolctl, thus:
+
+
+.. code-block:: bash
+
+ sudo ./tarantoolctl stop my_app
+
+Clean up. Restore the original contents of /etc/sysconfig/tarantool, and ...
+
+.. code-block:: bash
+
+ cd /
+ sudo rm -R tarantool_test
+
+=====================================================================
+ System-specific administration notes
+=====================================================================
+
+This section will contain information about issue or features which exist
+on some platforms but not others - for example, on certain versions of a
+particular Linux distribution.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Administrating with Debian GNU/Linux and Ubuntu
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Setting up an instance:
+``ln -s /etc/tarantool/instances.available/instance-name.cfg /etc/tarantool/instances.enabled/``
+
+Starting all instances:
+``service tarantool start``
+
+Stopping all instances:
+``service tarantool stop``
+
+Starting/stopping one instance:
+``service tarantool-instance-name start/stop``
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Fedora, RHEL, CentOS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are no known permanent issues. For transient issues, go to
+http://github.com/tarantool/tarantool/issues and enter "RHEL" or
+"CentOS" or "Fedora" or "Red Hat" in the search box.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ FreeBSD
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are no known permanent issues. For transient issues, go to
+http://github.com/tarantool/tarantool/issues and enter "FreeBSD"
+in the search box.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Mac OS X
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are no known permanent issues. For transient issues, go to
+http://github.com/tarantool/tarantool/issues and enter "OS X" in
+the search box.
diff --git a/doc/sphinx/book/app_a_errcodes.rst b/doc/sphinx/book/app_a_errcodes.rst
new file mode 100644
index 0000000000000000000000000000000000000000..e89a7c33ea6171344e1a4bd689bfb93ae6d84596
--- /dev/null
+++ b/doc/sphinx/book/app_a_errcodes.rst
@@ -0,0 +1,59 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Appendix A. List of error codes
+-------------------------------------------------------------------------------
+
+In the current version of the binary protocol, error message, which is normally
+more descriptive than error code, is not present in server response. The actual
+message may contain a file name, a detailed reason or operating system error code.
+All such messages, however, are logged in the error log. Below follow only general
+descriptions of some popular codes. A complete list of errors can be found in file
+`errcode.h`_ in the source tree.
+
+.. _errcode.h: https://github.com/tarantool/tarantool/blob/master/src/box/errcode.h
+
+.. _ER_MEMORY_ISSUE:
+
+===========================================================
+ List of error codes
+===========================================================
+
+ER_NONMASTER
+ Can't modify data on a replication slave.
+
+ER_ILLEGAL_PARAMS
+ Illegal parameters. Malformed protocol message.
+
+ER_MEMORY_ISSUE
+ Out of memory: :ref:`slab_alloc_arena` limit is 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
+ Attempt to access a space that does not exist.
+
+ER_NO_SUCH_INDEX
+ The specified index does not exist for the specified space.
+
+ER_PROC_LUA
+ An error inside a Lua procedure.
+
+ER_FIBER_STACK
+ Recursion limit reached when creating a new fiber. This is usually an
+ indicator of a bug in a stored procedure, recursively invoking itself
+ ad infinitum.
+
+ER_UPDATE_FIELD
+ An error occurred during update of a field.
+
+ER_TUPLE_FOUND
+ Duplicate key exists in unique index ...
+
+
diff --git a/doc/sphinx/book/app_b_proctitle.rst b/doc/sphinx/book/app_b_proctitle.rst
new file mode 100644
index 0000000000000000000000000000000000000000..16586b6586aaf8da95874974918f4c343f30e260
--- /dev/null
+++ b/doc/sphinx/book/app_b_proctitle.rst
@@ -0,0 +1,29 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Appendix B. Process title
+-------------------------------------------------------------------------------
+
+Linux and FreeBSD operating systems allow a running process to modify its title,
+which otherwise contains the program name. Tarantool uses this feature to help
+meet the needs of system administration, such as figuring out what services are
+running on a host, their status, and so on.
+
+A Tarantool server process title follows the following naming scheme:
+**program_name: role[@`custom_proc_title`_]**
+
+**program_name** is typically **tarantool**. The role can be one of the following:
+
+* **running** -- ordinary node "ready to accept requests",
+* **loading** -- ordinary node recovering from old snap and wal files,
+* **orphan** -- not in a cluster,
+* **hot_standby** -- see section :ref:`local_hot_standby`,
+* **dumper + process-id** -- saving a snapshot,
+
+For example:
+
+.. code-block:: bash
+
+ $ ps -A -f | grep tarantool
+ 1000 17701 2778 0 08:27 pts/0 00:00:00 tarantool: running
diff --git a/doc/sphinx/book/app_c_lua_tutorial.rst b/doc/sphinx/book/app_c_lua_tutorial.rst
new file mode 100644
index 0000000000000000000000000000000000000000..9714dcdc25315b4b211beadfb94e062c8f1f0ce3
--- /dev/null
+++ b/doc/sphinx/book/app_c_lua_tutorial.rst
@@ -0,0 +1,610 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Appendix C. Lua tutorial
+-------------------------------------------------------------------------------
+
+=====================================================================
+ Insert one million tuples with a Lua stored procedure
+=====================================================================
+
+This is an exercise assignment: “Insert one million tuples. Each tuple should
+have a constantly-increasing numeric primary-key field and a random alphabetic
+10-character string field.â€
+
+The purpose of the exercise is to show what Lua functions look like inside
+Tarantool. It will be necessary to employ the Lua math library, the Lua string
+library, the Tarantool box library, the Tarantool box.tuple library, loops, and
+concatenations. It should be easy to follow even for a person who has not used
+either Lua or Tarantool before. The only requirement is a knowledge of how other
+programming languages work and a memory of the first two chapters of this manual.
+But for better understanding, follow the comments and the links, which point to
+the Lua manual or to elsewhere in this Tarantool manual. To further enhance
+learning, type the statements in with the tarantool client while reading along.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Configure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We are going to use the "tarantool_sandbox" that was created in section
+:ref:`first database`. So there is a single space, and a numeric primary key,
+and a running tarantool server which also serves as a client.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Delimiter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We'll be making functions which go over one line. We don't want the client to
+send to the server after every line. So we :ref:`declare a delimter <setting delimiter>`.
+This means “Do not send to the server until you see an exclamation mark.â€
+
+.. code-block:: lua
+
+ tarantool> console = require('console'); console.delimiter('!')
+
+From now on it will be possible to use multiple-line statements, but it will be
+necessary to end all statements with exclamation marks.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Create a function that returns string
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We will start by making a function that returns a fixed string, “Hello worldâ€.
+
+.. code-block:: lua
+
+ function string_function()
+ return "hello world"
+ end!
+
+The word "``function``" is a Lua keyword -- we're about to go into Lua. The
+function name is string_function. The function has one executable statement,
+``return "hello world"``. The string "hello world" is enclosed in double quotes
+here, although Lua doesn't care -- one could use single quotes instead. The
+word "``end``" means “this is the end of the Lua function declaration.†The
+word "``end``" is followed by "``!``" because "``!``" happens to be the
+delimiter that we chose in the previous step. To confirm that the function works,
+we can say
+
+.. code-block:: lua
+
+ string_function()!
+
+Sending ``function-name()`` means “invoke the Lua function.†The effect is
+that the string which the function returns will end up on the screen.
+
+For more about Lua strings see Lua manual `chapter 2.4 "Strings"`_ . For more
+about functions see Lua manual `chapter 5 "Functions"`_.
+
+.. _chapter 2.4 "Strings": http://www.lua.org/pil/2.4.html
+.. _chapter 5 "Functions": http://www.lua.org/pil/5.html
+
+The screen now looks like this:
+
+.. code-block:: lua
+
+ tarantool> function string_function()
+ -> return "hello world"
+ -> end!
+ ---
+ ...
+ tarantool> string_function()!
+ ---
+ - hello world
+ ...
+ tarantool>
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Create a function that calls another function and sets a variable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now that ``string_function`` exists, we can invoke it from another
+function.
+
+.. code-block:: lua
+
+ function main_function()
+ local string_value
+ string_value = string_function()
+ return string_value
+ end!
+
+We begin by declaring a variable "``string_value``". The word "``local``"
+means that string_value appears only in ``main_function``. If we didn't use
+"``local``" then ``string_value`` would be visible everywhere - even by other
+users using other clients connected to this server! Sometimes that's a very
+desirable feature for inter-client communication, but not this time.
+
+Then we assign a value to ``string_value``, namely, the result of
+``string_function()``. Soon we will invoke ``main_function()`` to check that it
+got the value.
+
+For more about Lua variables see Lua manual `chapter 4.2 "Local Variables and Blocks"`_ .
+
+.. _chapter 4.2 "Local Variables and Blocks": http://www.lua.org/pil/4.2.html
+
+The screen now looks like this:
+
+.. code-block:: lua
+
+ tarantool> function main_function()
+ -> local string_value
+ -> string_value = string_function()
+ -> return string_value
+ -> end!
+ ---
+ ...
+ tarantool> main_function()!
+ ---
+ - hello world
+ ...
+ tarantool>
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Modify the function so it returns a one-letter random string
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now that it's a bit clearer how to make a variable, we can change
+``string_function()`` so that, instead of returning a fixed literal
+'Hello world", it returns a random letter between 'A' and 'Z'.
+
+.. code-block:: lua
+
+ function string_function()
+ local random_number
+ local random_string
+ random_number = math.random(65, 90)
+ random_string = string.char(random_number)
+ return random_string
+ end!
+
+It is not necessary to destroy the old ``string_function()`` contents, they're
+simply overwritten. The first assignment invokes a random-number function
+in Lua's math library; the parameters mean “the number must be an integer
+between 65 and 90.†The second assignment invokes an integer-to-character
+function in Lua's string library; the parameter is the code point of the
+character. Luckily the ASCII value of 'A' is 65 and the ASCII value of 'Z'
+is 90 so the result will always be a letter between A and Z.
+
+For more about Lua math-library functions see Lua users "`Math Library Tutorial`_".
+For more about Lua string-library functions see Lua users "`String Library Tutorial`_" .
+
+.. _Math Library Tutorial: http://lua-users.org/wiki/MathLibraryTutorial
+.. _String Library Tutorial: http://lua-users.org/wiki/StringLibraryTutorial
+
+Once again the ``string_function()`` can be invoked from main_function() which
+can be invoked with ``main_function()!``
+
+The screen now looks like this:
+
+.. code-block:: lua
+
+ tarantool> function string_function()
+ -> local random_number
+ -> local random_string
+ -> random_number = math.random(65, 90)
+ -> random_string = string.char(random_number)
+ -> return random_string
+ -> end!
+ ---
+ ...
+ tarantool> main_function()!
+ ---
+ - C
+ ...
+ tarantool>
+
+... Well, actually it won't always look like this because ``math.random()``
+produces random numbers. But for the illustration purposes it won't matter
+what the random string values are.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Modify the function so it returns a ten-letter random string
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now that it's clear how to produce one-letter random strings, we can reach our
+goal of producing a ten-letter string by concatenating ten one-letter strings,
+in a loop.
+
+.. code-block:: lua
+
+ function string_function()
+ local random_number
+ local random_string
+ random_string = ""
+ for x = 1,10,1 do
+ random_number = math.random(65, 90)
+ random_string = random_string .. string.char(random_number)
+ end
+ return random_string
+ end!
+
+The words "for x = 1,10,1" mean “start with x equals 1, loop until x equals 10,
+increment x by 1 for each iteration.†The symbol ".." means "concatenate", that
+is, add the string on the right of the ".." sign to the string on the left of
+the ".." sign. Since we start by saying that random_string is "" (a blank
+string), the end result is that random_string has 10 random letters. Once
+again the ``string_function()`` can be invoked from ``main_function()`` which
+can be invoked with ``main_function()!``
+
+For more about Lua loops see Lua manual `chapter 4.3.4 "Numeric for"`_.
+
+.. _chapter 4.3.4 "Numeric for": http://www.lua.org/pil/4.3.4.html
+
+The screen now looks like this:
+
+.. code-block:: lua
+
+ tarantool> function string_function()
+ -> local random_number
+ -> local random_string
+ -> random_string = ""
+ -> for x = 1,10,1 do
+ -> random_number = math.random(65, 90)
+ -> random_string = random_string .. string.char(random_number)
+ -> end
+ -> return random_string
+ -> end!
+ ---
+ ...
+ tarantool> main_function()!
+ ---
+ - 'ZUDJBHKEFM'
+ ...
+ tarantool>
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Make a tuple out of a number and a string
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now that it's clear how to make a 10-letter random string, it's possible to
+make a tuple that contains a number and a 10-letter random string, by invoking
+a function in Tarantool's library of Lua functions.
+
+.. code-block:: lua
+
+ function main_function()
+ local string_value
+ string_value = string_function()
+ t = box.tuple.new({1, string_value})
+ return t
+ end!
+
+Once this is done, t will be the value of a new tuple which has two fields.
+The first field is numeric: 1. The second field is a random string. Once again
+the ``string_function()`` can be invoked from ``main_function()`` which can be
+invoked with ``main_function()!``
+
+For more about Tarantool tuples see Tarantool manual section Package :mod:`box.tuple`.
+
+The screen now looks like this:
+
+.. code-block:: lua
+
+ tarantool> function main_function()
+ -> local string_value
+ -> string_value = string_function()
+ -> t = box.tuple.new({1, string_value})
+ -> return t
+ -> end!
+ ---
+ ...
+ tarantool> main_function()!
+ ---
+ - [1, 'PNPZPCOOKA']
+ ...
+ tarantool>
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Modify main_function to insert a tuple into the database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now that it's clear how to make a tuple that contains a number and a 10-letter
+random string, the only trick remaining is putting that tuple into tester.
+Remember that tester is the first space that was defined in the sandbox, so
+it's like a database table.
+
+.. code-block:: lua
+
+ function main_function()
+ local string_value
+ string_value = string_function()
+ t = box.tuple.new({1,string_value})
+ box.space.tester:replace(t)
+ end!
+
+The new line here is ``box.space.tester:replace(t)``. The name contains
+'tester' because the insertion is going to be to tester. The second parameter
+is the tuple value. To be perfectly correct we could have said
+``box.space.tester:insert(t)`` here, rather than ``box.space.tester:replace(t)``,
+but "replace" means “insert even if there is already a tuple whose primary-key
+value is a duplicateâ€, and that makes it easier to re-run the exercise even if
+the sandbox database isn't empty. Once this is done, tester will contain a tuple
+with two fields. The first field will be 1. The second field will be a random
+10-letter string. Once again the ``string_function(``) can be invoked from
+``main_function()`` which can be invoked with ``main_function()!``. But
+``main_function()`` won't tell the whole story, because it does not return t, it
+nly puts t into the database. To confirm that something got inserted, we'll use
+a SELECT request.
+
+.. code-block:: lua
+
+ main_function()!
+ box.space.tester:select{1}!
+
+For more about Tarantool insert and replace calls, see Tarantool manual section
+:mod:`box.space`
+
+The screen now looks like this:
+
+.. code-block:: lua
+
+ tarantool> function main_function()
+ -> local string_value
+ -> string_value = string_function()
+ -> t = box.tuple.new({1,string_value})
+ -> box.space.tester:replace(t)
+ -> end!
+ ---
+ ...
+ tarantool> main_function()!
+ ---
+ ...
+ tarantool> box.space.tester:select{1}!
+ ---
+ - - [1, 'EUJYVEECIL']
+ ...
+ tarantool>
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Modify main_function to insert a million tuples into the database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now that it's clear how to insert one tuple into the database, it's no big deal
+to figure out how to scale up: instead of inserting with a literal value = 1
+for the primary key, insert with a variable value = between 1 and 1 million, in
+a loop. Since we already saw how to loop, that's a simple thing. The only extra
+wrinkle that we add here is a timing function.
+
+.. code-block:: lua
+
+ function main_function()
+ local string_value
+ start_time = os.clock()
+ for i = 1,1000000,1 do
+ string_value = string_function()
+ t = box.tuple.new({i,string_value})
+ box.space.tester:replace(t)
+ end
+ end_time = os.clock()
+ end!
+ main_function()!
+ 'insert done in ' .. end_time - start_time .. ' seconds'!
+
+The Lua ``os.clock()`` function will return the number of seconds since the
+start. Therefore, by getting start_time = number of seconds just before the
+inserting, and then getting end_time = number of seconds just after the
+inserting, we can calculate (end_time - start_time) = elapsed time in seconds.
+We will display that value by putting it in a request without any assignments,
+which causes Tarantool to send the value to the client, which prints it. (Lua's
+answer to the C ``printf()`` function, which is ``print()``, will also work.)
+
+For more on Lua ``os.clock()`` see Lua manual `chapter 22.1 "Date and Time"`_ . For more on Lua print() see Lua manual `chapter 5 "Functions"`_.
+
+.. _chapter 22.1 "Date and Time": http://www.lua.org/pil/22.1.html
+.. _chapter 5 "Functions": http://www.lua.org/pil/5.html
+
+Since this is the grand finale, we will redo the final versions of all the
+necessary requests: the ``console.delimiter('!')`` request, the request that
+created ``string_function()``, the request that created ``main_function()``,
+and the request that invokes ``main_function()``.
+
+.. code-block:: lua
+
+ -- Skip the following statement if you have already said "console.delimiter('!')"
+ console = require('console'); console.delimiter('!')
+
+ function string_function()
+ local random_number
+ local random_string
+ random_string = ""
+ for x = 1,10,1 do
+ random_number = math.random(65, 90)
+ random_string = random_string .. string.char(random_number)
+ end
+ return random_string
+ end!
+
+ function main_function()
+ local string_value
+ start_time = os.clock()
+ for i = 1,1000000,1 do
+ string_value = string_function()
+ t = box.tuple.new({i,string_value})
+ box.space.tester:replace(t)
+ end
+ end_time = os.clock()
+ end!
+ main_function()!
+ 'insert done in ' .. end_time - start_time .. ' seconds'!
+
+The screen now looks like this:
+
+.. code-block:: lua
+
+ tarantool> console = require('console'); console.delimiter('!')
+ tarantool> function string_function()
+ -> local random_number
+ -> local random_string
+ -> random_string = ""
+ -> for x = 1,10,1 do
+ -> random_number = math.random(65, 90)
+ -> random_string = random_string .. string.char(random_number)
+ -> end
+ -> return random_string
+ -> end!
+ ---
+ ...
+ tarantool> function main_function()
+ -> local string_value
+ -> start_time = os.clock()
+ -> for i = 1,1000000,1 do
+ -> string_value = string_function()
+ -> t = box.tuple.new({i,string_value})
+ -> box.space.tester:replace(t)
+ -> end
+ -> end_time = os.clock()
+ -> end!
+ ---
+ ...
+ tarantool> main_function()!
+ ---
+ ...
+ tarantool> 'insert done in ' .. end_time - start_time .. ' seconds'!
+ ---
+ - insert done in 60.62 seconds
+ ...
+ tarantool>
+
+What has been shown is that Lua functions are quite expressive (in fact one can
+do more with Tarantool's Lua stored procedures than one can do with stored
+procedures in some SQL DBMSs), and that it's straightforward to combine
+Lua-library functions and Tarantool-library functions.
+
+What has also been shown is that inserting a million tuples took 60 seconds. The
+host computer was a Toshiba laptop with a 2.2-GHz Intel Core Duo CPU.
+
+
+=====================================================================
+ Sum a JSON field for all tuples
+=====================================================================
+
+This is an exercise assignment: “Assume that inside every tuple there is a
+string formatted as JSON. Inside that string there is a JSON numeric field.
+For each tuple, find the numeric field's value and add it to a 'sum' variable.
+At end, return the 'sum' variable.†The purpose of the exercise is to get
+experience in one way to read and process tuples.
+
+.. code-block:: lua
+
+ console = require('console'); console.delimiter('!')
+ function sum_json_field(field_name)
+ json = require('json')
+ local v, t, sum, field_value, is_valid_json, lua_table --[[1]]
+ sum = 0 --[[2]]
+ for v, t in box.space.tester:pairs() do --[[3]]
+ is_valid_json, lua_table = pcall(json.decode, t[2]) --[[4]]
+ if is_valid_json then --[[5]]
+ field_value = lua_table[field_name] --[[6]]
+ if type(field_value) == "number" then sum = sum + field_value end --[[7]]
+ end --[[8]]
+ end --[[9]]
+ return sum --[[10]]
+ end!
+ console.delimiter('')!
+
+LINE 1: WHY "LOCAL". This line declares all the variables that will be used in
+the function. Actually it's not necessary to declare all variables at the start,
+and in a long function it would be better to declare variables just before using
+them. In fact it's not even necessary to declare variables at all, but an
+undeclared variable is "global". That's not desirable for any of the variables
+that are declared in line 1, because all of them are for use only within the function.
+
+LINE 3: WHY "PAIRS()". Our job is to go through all the rows and there are two
+ways to do it: with ``box.space.space-name:pairs()`` or with
+:func:`index.iterator <box.space.space-name.index[.index-name]:pairs>`.
+We preferred ``pairs()`` because it is simpler.
+
+LINE 4: WHY "PCALL". If we simply said "``lua_table = json.decode(t[2]))``", then
+the function would abort with an error if it encountered something wrong with the
+JSON string - a missing colon, for example. By putting the function inside "``pcall``"
+(`protected call`_), we're saying: we want to intercept that sort of error, so if
+there's a problem just set ``is_valid_json = false`` and we will know what to do
+about it later.
+
+LINE 4: MEANING. The function is :func:`json.decode` which means decode a JSON
+string, and the parameter is t[2] which is a reference to a JSON string. There's
+a bit of hard coding here, we're assuming that the second field in the tuple is
+where the JSON string was inserted. For example, we're assuming a tuple looks like
+
+.. _protected call: http://www.lua.org/pil/8.4.html
+
+.. code-block:: json
+
+ field[1]: 444
+ field[2]: '{"Hello": "world", "Quantity": 15}'
+
+meaning that the tuple's first field, the primary key field, is a number while
+the tuple's second field, the JSON string, is a string. Thus the entire statement
+means "decode ``t[2]`` (the tuple's second field) as a JSON string; if there's an
+error set ``is_valid_json = false``; if there's no error set ``is_valid_json = true`` and
+set ``lua_table =`` a Lua table which has the decoded string".
+
+LINE 6. At last we are ready to get the JSON field value from the Lua table that
+came from the JSON string. The value in field_name, which is the parameter for the
+whole function, must be a name of a JSON field. For example, inside the JSON string
+``'{"Hello": "world", "Quantity": 15}'``, there are two JSON fields: "Hello" and
+"Quantity". If the whole function is invoked with ``sum_json_field("Quantity")``,
+then ``field_value = lua_table[field_name]`` is effectively the same as
+``field_value = lua_table["Quantity"]`` or even ``field_value = lua_table.Quantity``.
+Those are just three different ways of saying: for the Quantity field in the Lua table,
+get the value and put it in variable field_value.
+
+LINE 7: WHY "IF". Suppose that the JSON string is well formed but the JSON field
+is not a number, or is missing. In that case, the function would be aborted when
+there was an attempt to add it to the sum. By first checking
+``type(field_value) == "number"``, we avoid that abortion. Anyone who knows that
+the database is in perfect shape can skip this kind of thing.
+
+And the function is complete. Time to test it. Starting with an empty database,
+defined the same way as the sandbox database that was introduced in
+“ :ref:`first database` â€,
+
+.. code-block:: lua
+
+ -- if tester is left over from some previous test, destroy it
+ box.space.tester:drop()
+ box.schema.space.create('tester')
+ box.space.tester:create_index('primary', {parts = {1, 'NUM'}})
+
+then add some tuples where the first field is a number and the second
+field is a string.
+
+.. code-block:: lua
+
+ box.space.tester:insert{444, '{"Item": "widget", "Quantity": 15}'}
+ box.space.tester:insert{445, '{"Item": "widget", "Quantity": 7}'}
+ box.space.tester:insert{446, '{"Item": "golf club", "Quantity": "sunshine"}'}
+ box.space.tester:insert{447, '{"Item": "waffle iron", "Quantit": 3}'}
+
+Since this is a test, there are deliberate errors. The "golf club" and the
+"waffle iron" do not have numeric Quantity fields, so must be ignored.
+Therefore the real sum of the Quantity field in the JSON strings should be:
+15 + 7 = 22.
+
+Invoke the function with ``sum_json_field("Quantity")``.
+
+.. code-block:: lua
+
+ tarantool> sum_json_field("Quantity")
+ ---
+ - 22
+ ...
+
+It works. We'll just leave, as exercises for future improvement, the possibility
+that the "hard coding" assumptions could be removed, that there might have to be
+an overflow check if some field values are huge, and that the function should
+contain a "yield" instruction if the count of tuples is huge.
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/sphinx/book/app_d_plugins.rst b/doc/sphinx/book/app_d_plugins.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8fc5f0ce5248a23e6d9495321ac37233ada65201
--- /dev/null
+++ b/doc/sphinx/book/app_d_plugins.rst
@@ -0,0 +1,301 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+.. _dbms-plugins:
+
+-------------------------------------------------------------------------------
+ Appendix D. Plugins
+-------------------------------------------------------------------------------
+
+A plugin is an optional library which enhances Tarantool functionality.
+
+The details of creating one's own plugin are described on the `Tarantool Plugin API wiki page`_.
+
+The discussion here in the user guide is about incorporating and using two
+plugins that have already been created: the "SQL DBMS plugins" for
+MySQL and PostgreSQL.
+
+===========================================================
+ SQL DBMS Plugins
+===========================================================
+
+To call another DBMS from Tarantool, the essential requirements are: another
+DBMS, and Tarantool.
+
+It will be necessary to build Tarantool from source, as described in
+“ :ref:`building-from-source` â€
+
+.. _Tarantool Plugin API wiki page: https://github.com/tarantool/tarantool/wiki/Plugin-API
+
+The Tarantool plugins allow for connecting to an SQL server and executing SQL
+statements the same way that a MySQL or PostgreSQL client does. The SQL
+statements are visible as Lua methods. Thus Tarantool can serve as a "MySQL Lua
+Connector" or "PostgreSQL Lua Connector", which would be useful even if that was
+all Tarantool could do. But of course Tarantool is also a DBMS, so the plugin
+also is useful for any operations, such as database copying and accelerating,
+which work best when the application can work on both SQL and Tarantool inside
+the same Lua routine.
+
+The connection method is
+``box.net.sql.connect('mysql'|'pg', host, port, user, password, database)``.
+The methods for select/insert/etc. are the same as the ones in the net.box package.
+
+
+===========================================================
+ MySQL Example
+===========================================================
+
+This example assumes that MySQL 5.5 or MySQL 5.6 has been installed (recent
+MariaDB versions should also work).
+
+The example was run on a Linux machine where the base directory had a copy of
+he Tarantool source on ~/tarantool, and a copy of MySQL on ~/mysql-5.5. The
+mysqld server is already running on the local host 127.0.0.1.
+
+::
+
+ # Check that the include subdirectory exists by looking for .../include/mysql.h.
+ # (If this fails, there's a chance that it's in .../include/mysql/mysql.h instead.)
+ $ [ -f ~/mysql-5.5/include/mysql.h ] && echo "OK" || echo "Error"
+ OK
+
+ # Check that the library subdirectory exists and has the necessary .so file.
+ $ [ -f ~/mysql-5.5/lib/libmysqlclient.so ] && echo "OK" || echo "Error"
+ OK
+
+ # Check that the mysql client can connect using some factory defaults:
+ # port = 3306, user = 'root', user password = '', database = 'test'.
+ # These can be changed, provided one uses the changed values in
+ # all places.
+ $ ~/mysql-5.5/bin/mysql --port=3306 -h 127.0.0.1 --user=root --password= --database=test
+ Welcome to the MySQL monitor. Commands end with ; or \g.
+ Your MySQL connection id is 25
+ Server version: 5.5.35 MySQL Community Server (GPL)
+ ...
+ Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
+
+ mysql>
+
+ # Insert a row in database test, and quit.
+ mysql> CREATE TABLE IF NOT EXISTS test (s1 INT, s2 VARCHAR(50));
+ Query OK, 0 rows affected (0.13 sec)
+ mysql> INSERT INTO test.test VALUES (1,'MySQL row');
+ Query OK, 1 row affected (0.02 sec)
+ mysql> QUIT
+ Bye
+
+ # Build the Tarantool server. Make certain that "cmake" gets the right
+ # paths for the MySQL include directory and the MySQL libmysqlclient
+ # library which were checked earlier.
+ $ cd ~/tarantool
+ $ make clean
+ $ rm CMakeCache.txt
+ $ cmake . -DWITH_MYSQL=on -DMYSQL_INCLUDE_DIR=~/mysql-5.5/include\
+ > -DMYSQL_LIBRARIES=~/mysql-5.5/lib/libmysqlclient.so
+ ...
+ -- Found MySQL includes: ~/mysql-5.5/include/mysql.h
+ -- Found MySQL library: ~/mysql-5.5/lib/libmysqlclient.so
+ ...
+ -- Configuring done
+ -- Generating done
+ -- Build files have been written to: ~/tarantool
+ $ make
+ ...
+ Scanning dependencies of target mysql
+ [ 79%] Building CXX object src/module/mysql/CMakeFiles/mysql.dir/mysql.cc.o
+ Linking CXX shared library libmysql.so
+ [ 79%] Built target mysql
+ ...
+ [100%] Built target man
+ $
+
+ # The MySQL module should now be in ./src/module/mysql/mysql.so.
+ # If a "make install" had been done, then mysql.so would be in a
+ # different place, for example
+ # /usr/local/lib/x86_64-linux-gnu/tarantool/box/net/mysql.so.
+ # In that case there should be additional cmake options such as
+ # -DCMAKE_INSTALL_LIBDIR and -DCMAKE_INSTALL_PREFIX.
+ # For this example we assume that "make install" is not done.
+
+ # Change directory to a directory which can be used for temporary tests.
+ # For this example we assume that the name of this directory is
+ # /home/pgulutzan/tarantool_sandbox. (Change "/home/pgulutzan" to whatever
+ # is the actual base directory for the machine that's used for this test.)
+ # Now, to help tarantool find the essential mysql.so file, execute these lines:
+ cd /home/pgulutzan/tarantool_sandbox
+ mkdir box
+ mkdir box/net
+ cp ~/tarantool/src/module/mysql/mysql.so ./box/net/mysql.so
+
+ # Start the Tarantool server. Do not use a Lua initialization file.
+
+ $ ~/tarantool/src/tarantool
+ ~/tarantool/src/tarantool: version 1.6.3-439-g7e1011b
+ type 'help' for interactive help
+ tarantool> box.cfg{}
+ ...
+ # Enter the following lines on the prompt (again, change "/home/pgulutzan"
+ # to whatever the real directory is that contains tarantool):
+ package.path = "/home/pgulutzan/tarantool/src/module/sql/?.lua;"..package.path
+ require("sql")
+ if type(box.net.sql) ~= "table" then error("net.sql load failed") end
+ require("box.net.mysql")
+ # ... Make sure that tarantool replies "true" for both calls to "require()".
+
+ # Create a Lua function that will connect to the MySQL server,
+ # (using some factory default values for the port and user and password),
+ # retrieve one row, and display the row.
+ # For explanations of the statement types used here, read the
+ # Lua tutorial earlier in the Tarantool user manual.
+ tarantool> console = require('console'); console.delimiter('!')
+ tarantool> function mysql_select ()
+ -> local dbh = box.net.sql.connect(
+ -> 'mysql', '127.0.0.1', 3306, 'root', '', 'test')
+ -> local test = dbh:select('SELECT * FROM test WHERE s1 = 1')
+ -> local row = ''
+ -> for i, card in pairs(test) do
+ -> row = row .. card.s2 .. ' '
+ -> end
+ -> return row
+ -> end!
+ ---
+ ...
+ tarantool> console.delimiter('')!
+ tarantool>
+
+ # Execute the Lua function.
+ tarantool> mysql_select()
+ ---
+ - 'MySQL row '
+ ...
+ # Observe the result. It contains "MySQL row".
+ # So this is the row that was inserted into the MySQL database.
+ # And now it's been selected with the Tarantool client.
+
+===========================================================
+ PostgreSQL Example
+===========================================================
+
+This example assumes that a recent version of PostgreSQL has been installed.
+The PostgreSQL library and include files are also necessary. On Ubuntu they
+can be installed with
+
+.. code-block:: bash
+
+ $ sudo apt-get install libpq-dev
+
+If that works, then cmake will find the necessary files without requiring any
+special user input. However, because not all platforms are alike, for this
+example the assumption is that the user must check that the appropriate
+PostgreSQL files are present and must explicitly state where they are when
+building Tarantool from source.
+
+The example was run on a Linux machine where the base directory had a copy of
+the Tarantool source on ~/tarantool, and a copy of PostgreSQL on /usr. The
+postgres server is already running on the local host 127.0.0.1.
+
+::
+
+ # Check that the include subdirectory exists
+ # by looking for /usr/include/postgresql/libpq-fe-h.
+ $ [ -f /usr/include/postgresql/libpq-fe.h ] && echo "OK" || echo "Error"
+ OK
+
+ # Check that the library subdirectory exists and has the necessary .so file.
+ $ [ -f /usr/lib/libpq.so ] && echo "OK" || echo "Error"
+ OK
+
+ # Check that the psql client can connect using some factory defaults:
+ # port = 5432, user = 'postgres', user password = 'postgres', database = 'postgres'.
+ # These can be changed, provided one changes them in all places.
+ # Insert a row in database postgres, and quit.
+ $ psql -h 127.0.0.1 -p 5432 -U postgres -d postgres
+ Password for user postgres:
+ psql (9.3.0, server 9.3.2)
+ SSL connection (cipher: DHE-RSA-AES256-SHA, bits: 256)
+ Type "help" for help.
+
+ postgres=# CREATE TABLE test (s1 INT, s2 VARCHAR(50));
+ CREATE TABLE
+ postgres=# INSERT INTO test VALUES (1,'PostgreSQL row');
+ INSERT 0 1
+ postgres=# \q
+ $
+
+ # Build the Tarantool server. Make certain that "cmake" gets the right
+ # paths for the PostgreSQL include directory and the PostgreSQL libpq
+ # library which were checked earlier.
+ $ cd ~/tarantool
+ $ make clean
+ $ rm CMakeCache.txt
+ $ cmake . -DWITH_POSTGRESQL=on -DPostgreSQL_LIBRARY=/usr/lib/libpq.so\
+ > -DPostgreSQL_INCLUDE_DIR=/usr/include/postgresql
+ ...
+ -- Found PostgreSQL: /usr/lib/libpq.so (found version "9.3.2")
+ ...
+ -- Configuring done
+ -- Generating done
+ -- Build files have been written to: ~/tarantool
+ $ make
+ ...
+ [ 79%] Building CXX object src/plugin/pg/CMakeFiles/pg.dir/pg.cc.o
+ Linking CXX shared library libpg.so
+ [ 79%] Built target pg
+ ...
+ [100%] Built target man
+ $
+
+ # Change directory to a directory which can be used for temporary tests.
+ # For this example we assume that the name of this directory is
+ # /home/pgulutzan/tarantool_sandbox. (Change "/home/pgulutzan" to whatever
+ # is the actual base directory for the machine that's used for this test.)
+ # Now, to help tarantool find the essential mysql.so file, execute these lines:
+ cd /home/pgulutzan/tarantool_sandbox
+ mkdir box
+ mkdir box/net
+ cp ~/tarantool/src/module/pg/pg.so ./box/net/pg.so
+
+ # Start the Tarantool server. Do not use a Lua initialization file.
+
+ $ ~/tarantool/src/tarantool
+ ~/tarantool/src/tarantool: version 1.6.3-439-g7e1011b
+ type 'help' for interactive help
+ tarantool> box.cfg{}
+
+ # Enter the following lines on the prompt (again, change "/home/pgulutzan"
+ # to whatever the real directory is that contains tarantool):
+ package.path = "/home/pgulutzan/tarantool/src/module/sql/?.lua;"..package.path
+ require("sql")
+ if type(box.net.sql) ~= "table" then error("net.sql load failed") end
+ require("box.net.pg")
+ # ... Make sure that tarantool replies "true" for the calls to "require()".
+
+ # Create a Lua function that will connect to the PostgreSQL server,
+ # retrieve one row, and display the row.
+ # For explanations of the statement types used here, read the
+ # Lua tutorial in the Tarantool user manual.
+ tarantool> console = require('console'); console.delimiter('!')
+ tarantool> function postgresql_select ()
+ -> local dbh = box.net.sql.connect(
+ -> 'pg', '127.0.0.1', 5432, 'postgres', 'postgres', 'postgres')
+ -> local test = dbh:select('SELECT * FROM test WHERE s1 = 1')
+ -> local row = ''
+ -> for i, card in pairs(test) do
+ -> row = row .. card.s2 .. ' '
+ -> end
+ > return row
+ -> end!
+ ---
+ ...
+ tarantool> console.delimiter('')!
+ tarantool>
+
+ # Execute the Lua function.
+ tarantool> postgresql_select()
+ ---
+ - 'PostgreSQL row '
+ ...
+
+ # Observe the result. It contains "PostgreSQL row".
+ # So this is the row that was inserted into the PostgreSQL database.
+ # And now it's been selected with the Tarantool client.
diff --git a/doc/sphinx/book/box/admin.rst b/doc/sphinx/book/box/admin.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f3f0ea30a5a9ffc1d611612c1061d97747d3c1a3
--- /dev/null
+++ b/doc/sphinx/book/box/admin.rst
@@ -0,0 +1,66 @@
+.. include:: ../../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Administrative requests
+-------------------------------------------------------------------------------
+
+To learn which functions are considered to be administrative, type ``help()``.
+A reference description also follows below:
+
+.. function:: box.snapshot()
+
+ Take a snapshot of all data and store it in :ref:`snap_dir <snap_dir>`/<latest-lsn>.snap.
+ To take a snapshot, Tarantool first enters the delayed garbage collection
+ mode for all data. In this mode, tuples which were allocated before the
+ snapshot has started are not freed until the snapshot has finished. To
+ preserve consistency of the primary key, used to iterate over tuples, a
+ copy-on-write technique is employed. If the master process changes part
+ of a primary key, the corresponding process page is split, and the snapshot
+ process obtains an old copy of the page. Since a snapshot is written
+ sequentially, one can expect a very high write performance (averaging to
+ 80MB/second on modern disks), which means an average database instance gets
+ saved in a matter of minutes. Note, that as long as there are any changes to
+ the parent index memory through concurrent updates, there are going to be
+ page splits, and therefore one needs to have some extra free memory to run
+ this command. 10% of :ref:`slab_alloc_arena <slab_alloc_arena>` is, on average,
+ sufficient. This statement waits until a snapshot is taken and returns operation result.
+
+ .. code-block:: lua
+
+ tarantool> box.info.version
+ ---
+ - 1.6.3-439-g7e1011b
+ ...
+ tarantool> box.snapshot()
+ ---
+ - ok
+ ...
+ tarantool> box.snapshot()
+ ---
+ error: can't save snapshot, errno 17 (File exists)
+ ...
+
+
+ Taking a snapshot does not cause the server to start a new write-ahead log.
+ Once a snapshot is taken, old WALs can be deleted as long as all replicas
+ are up to date. But the WAL which was current at the time **box.snapshot()**
+ started must be kept for recovery, since it still contains log records
+ written after the start of **box.snapshot()**.
+
+ An alternative way to save a snapshot is to send the server SIGUSR1 UNIX
+ signal. While this approach could be handy, it is not recommended for use
+ in automation: a signal provides no way to find out whether the snapshot
+ was taken successfully or not.
+
+.. function:: coredump()
+
+ Fork and dump a core. Since Tarantool stores all tuples in memory, it can
+ take some time. Mainly useful for debugging.
+
+.. function:: require('fiber').info()
+
+ Show all running fibers, with their stack. Mainly useful for debugging.
+
+.. _snap_dir: :ref:`snap_dir`
+.. _slab_alloc_arena: :ref:`slab_alloc_arena`
diff --git a/doc/sphinx/book/box/atomic.rst b/doc/sphinx/book/box/atomic.rst
new file mode 100644
index 0000000000000000000000000000000000000000..fad312d47518435be20db1a70d56333ef7463625
--- /dev/null
+++ b/doc/sphinx/book/box/atomic.rst
@@ -0,0 +1,90 @@
+.. include:: ../../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Atomic execution
+-------------------------------------------------------------------------------
+
+In several places it's been noted that Lua processes occur in fibers on a
+single thread. That is why there can be a guarantee of execution atomicity.
+That requires emphasis.
+
+===========================================================
+ Cooperative multitasking environment
+===========================================================
+
+Tarantool core is built around a cooperative multi-tasking paradigm: unless a
+running fiber deliberately yields control to some other fiber, it is not
+preempted. “Yield points†are built into all calls from Tarantool core to the
+operating system. Any system call which can block is performed in an
+asynchronous manner and the fiber waiting on the system call is preempted with
+a fiber ready to run. This model makes all programmatic locks unnecessary:
+cooperative multitasking ensures that there is no concurrency around a resource,
+no race conditions and no memory consistency issues.
+
+When requests are small, e.g. simple UPDATE, INSERT, DELETE, SELECT, fiber
+scheduling is fair: it takes only a little time to process the request, schedule
+a disk write, and yield to a fiber serving the next client.
+
+A function, however, can perform complex computations, or be written in such a
+way that control is not given away for a long time. This can lead to unfair
+scheduling, when a single client throttles the rest of the system, or to
+apparent stalls in request processing. Avoiding this situation is the
+responsibility of the function's author. Most of the box calls, such as
+``box.space...insert``, ``box.space...update``, ``box.space...delete`` are yield
+points; ``box.space...select``, however, is not.
+
+It should also be noted that, in the absence of transactions, any yield in a
+function is a potential change in the database state. Effectively, it's only
+possible to have CAS (compare-and-swap) -like atomic stored procedures: i.e.
+functions which select and then modify a record. Multiple data change requests
+always run through a built-in yield point.
+
+At this point an objection could arise: "It's good that a single data-change
+request will commit and yield, but surely there are times when multiple
+data-change requests must happen without yielding." The standard example is the
+money-transfer, where $1 is withdrawn from account #1 and deposited into
+account #2. If something interrupted after the withdrawal, then the institution
+would be out of balance. For such cases, the ``begin ... commit|rollback`` block
+was designed.
+
+.. function:: box.begin()
+
+ From this point, implicit yields are suspended. In effect the fiber which
+ executes ``box.begin()`` is starting an "active multi-request transaction",
+ blocking all other fibers until the transaction ends. All operations within
+ this transaction should use the same storage engine.
+
+.. function:: box.commit()
+
+ End the currently active transaction, and make all its data-change
+ operations permanent.
+
+.. function:: box.rollback()
+
+ End the currently active transaction, but cancel all its data-change
+ operations. An explicit call to functions outside ``box.space`` that always
+ yield, such as ``fiber.yield`` or ``fiber.sleep``, will have the same effect.
+
+The *requests in a transaction must be sent to the server as a single block*.
+It is not enough to enclose them between ``begin`` and ``commit`` or ``rollback``.
+To ensure they are sent as a single block: put them in a function, or put them all
+on one line, or use a delimiter so that multi-line requests are handled together.
+
+===========================================================
+ Example
+===========================================================
+
+Assuming that in tuple set 'tester' there are tuples in which the third
+field represents a positive dollar amount ... Start a transaction, withdraw from
+tuple#1, deposit in tuple#2, and end the transaction, making its effects permanent.
+
+.. code-block:: lua
+
+ console = require('console'); console.delimiter('!')
+ box.begin()
+ amount_of_money = 1.00
+ box.space.tester:update({999}, {{'-', 3, amount_of_money}})
+ box.space.tester:update({1000}, {{'+', 3, amount_of_money}})
+ box.commit()
+ console.delimiter('')!
diff --git a/doc/sphinx/book/box/authentication.rst b/doc/sphinx/book/box/authentication.rst
new file mode 100644
index 0000000000000000000000000000000000000000..7919395d224af659c41a7d650be9dccbca562600
--- /dev/null
+++ b/doc/sphinx/book/box/authentication.rst
@@ -0,0 +1,354 @@
+.. include:: ../../directives.rst
+.. highlight:: lua
+
+.. _box-authentication:
+
+-------------------------------------------------------------------------------
+ Authentication and authorization
+-------------------------------------------------------------------------------
+
+Understanding the details of security is primarily an issue for administrators,
+but ordinary users should at least skim this section so that they will have an
+idea of how Tarantool makes it possible for administrators to prevent
+unauthorized access to the database and to certain functions.
+
+Briefly: there is a method to guarantee with password checks that users really
+are who they say they are ("authentication"). There is a _user space where user
+names and password-hashes are stored. There are functions for saying that
+certain users are allowed to do certain things ("privileges"). There is a _priv
+space where privileges are stored. Whenever a user tries to do an operation,
+there is a check whether the user has the privilege to do the operation
+("access control").
+
+===========================================================
+ Passwords
+===========================================================
+
+Each user may have a password. The password is any alphanumeric string.
+Administrators should advise users to choose long unobvious passwords, but it
+is ultimately up to the users to choose or change their own passwords.
+
+Tarantool passwords are stored in the ``_user`` space with a `Cryptographic hash function`_
+so that, if the password is 'x', the stored hashed-password is a long string
+like '``lL3OvhkIPOKh+Vn9Avlkx69M/Ck=``'. When a client connects to a Tarantool
+server, the server sends a random `Salt Value`_ which the client must mix with the
+hashed-password before sending to the server. Thus the original value 'x' is
+never stored anywhere except in the user's head, and the hashed value is never
+passed down a network wire except when mixed with a random salt. This system
+prevents malicious onlookers from finding passwords by snooping in the log
+files or snooping on the wire. It is the same system that `MySQL introduced
+several years ago`_ which has proved adequate for medium-security installations.
+Nevertheless administrators should warn users that no system is foolproof against
+determined long-term attacks, so passwords should be guarded and changed occasionally.
+
+.. NOTE:
+
+ To get the hash-password of a string '``X``', say ``box.schema.user.password('X')``.
+ To see more about the details of the algorithm for the purpose of writing a new
+ client application, read the `scramble.h`_ header file.
+
+.. _Cryptographic hash function: https://en.wikipedia.org/wiki/Cryptographic_hash
+.. _Salt Value: https://en.wikipedia.org/wiki/Salt_%28cryptography%29
+.. _MySQL introduced several years ago: http://dev.mysql.com/doc/refman/4.1/en/password-hashing.html
+.. _scramble.h: https://github.com/tarantool/tarantool/blob/master/src/scramble.h
+
+===========================================================
+ Users and the _user space
+===========================================================
+
+The fields in the ``_user`` space are: the numeric id of the tuple, the numeric
+id of the tuple's creator, the user name, the type, and the optional password.
+
+There are three special tuples in the _user space: 'guest', 'admin', and 'public'.
+
+.. container:: table
+
+ +--------+----+------+--------------------------------------------------------+
+ | Name | ID | Type | Description |
+ +========+====+======+========================================================+
+ | guest | 0 | user | Default when connecting remotely. Usually an untrusted |
+ | | | | user with few privileges. |
+ +--------+----+------+--------------------------------------------------------+
+ | admin | 1 | user | Default when using ``tarantool`` as a console. Usually |
+ | | | | an administrative user with all privileges. |
+ +--------+----+------+--------------------------------------------------------+
+ | public | 2 | role | Not a user in the usual sense. Described later in |
+ | | | | section `Roles`_. |
+ +--------+----+------+--------------------------------------------------------+
+
+To select a row from the ``_user`` space, use ``box.space._user:select``. For
+example, here is what happens with a select for user id = 0, which is the
+'guest' user, which by default has no password:
+
+.. code-block:: lua
+
+ tarantool> box.space._user:select{0}
+ ---
+ - - [0, 1, 'guest', 'user']
+ ...
+
+To change tuples in the ``_user`` space, do not use ordinary ``box.space``
+functions for insert or update or delete - the _user space is special so
+there are special functions which have appropriate error checking.
+
+To create a new user, say ``box.schema.user.create(user-name)`` or
+``box.schema.user.create(user-name, {password=password})``. The form
+``box.schema.user.create(user-name, {password=password})`` is better because
+in a :ref:`URI` (Uniform Resource Identifier) it is usually illegal to include a
+user-name without a password.
+
+To change the current user's password, say ``box.schema.user.passwd(password)``.
+
+To change a different user's password, say ``box.schema.user.passwd(user-name, password)``.
+(Only the admin user can perform this function.)
+
+To drop a user, say ``box.schema.user.drop(user-name)``.
+
+To check whether a user exists, say ``box.schema.user.exists(user-name)``,
+which returns true or false.
+
+For example, here is a session which creates a new user with a strong password,
+selects a tuple in the ``_user`` space, and then drops the user.
+
+.. code-block:: lua
+
+ tarantool> box.schema.user.create('JeanMartin', {password = 'Iwtso_6_os$$'})
+ ---
+ ...
+
+ tarantool> box.space._user.index.name:select{'JeanMartin'}
+ ---
+ - - [17, 1, 'JeanMartin', 'user', {'chap-sha1': 't3xjUpQdrt857O+YRvGbMY5py8Q='}]
+ ...
+
+ tarantool> box.schema.user.drop('JeanMartin')
+ ---
+ ...
+
+.. NOTE::
+
+ The maximum number of users is 32.
+
+===========================================================
+ Priveleges and _priv space
+===========================================================
+
+The fields in the ``_priv`` space are: the numeric id of the user who gave the
+privilege ("grantor_id"), the numeric id of the user who received the
+privilege ("grantee_id"), the id of the object, the type of object - "space"
+or "function" or "universe", the type of operation - "read" or "write" or
+"execute" or a combination such as "read,write,execute".
+
+The function for granting a privilege is:
+``box.schema.user.grant(user-name-of-grantee, operation-type, object-type, object-name)`` or
+``box.schema.user.grant(user-name-of-grantee, operation-type, 'universe')``.
+
+The function for revoking a privilege is:
+``box.schema.user.revoke(user-name-of-grantee, operation-type, object-type, object-name)`` or
+``box.schema.user.revoke(user-name-of-grantee, operation-type, 'universe')``.
+
+For example, here is a session where the admin user gave the guest user the
+privilege to read from a space named space55, and then took the privilege away:
+
+.. code-block:: lua
+
+ tarantool> box.schema.user.grant('guest', 'read', 'space', 'space55')
+ ---
+ ...
+ tarantool> box.schema.user.revoke('guest', 'read', 'space', 'space55')
+ ---
+ ...
+
+.. NOTE::
+
+ Generally privileges are granted or revoked by the owner of the object (the
+ user who created it), or by the 'admin' user. Before dropping any objects
+ or users, steps should be taken to ensure that all their associated
+ privileges have been revoked. Only the 'admin' user can grant privileges
+ for the 'universe'.
+
+
+===========================================================
+ Functions and _func space
+===========================================================
+
+The fields in the ``_func`` space are: the numeric function id, a number,
+and the function name.
+
+The ``_func`` space does not include the function's body. One continues to
+create Lua functions in the usual way, by saying
+"``function function_name () ... end``", without adding anything in the
+``_func`` space. The _func space only exists for storing function tuples so
+that their names can be used within grant/revoke functions.
+
+The function for creating a ``_func`` tuple is:
+``box.schema.func.create(function-name)``.
+
+The function for dropping a ``_func`` tuple is:
+``box.schema.func.drop(function-name)``.
+
+The function for checking whether a ``_func`` tuple exists is:
+``box.schema.func.exists(function-name)``.
+
+In the following example, a function named 'f7' is created, then it is put in
+the ``_func`` space, then it is used in a ``box.schema.user.grant`` function,
+then it is dropped:
+
+.. code-block:: lua
+
+ tarantool> function f7() box.session.uid() end
+ ---
+ ...
+ tarantool> box.schema.func.create('f7')
+ ---
+ ...
+ tarantool> box.schema.user.grant('guest', 'execute', 'function', 'f7')
+ ---
+ ...
+ tarantool> box.schema.user.revoke('guest', 'execute', 'function', 'f7')
+ ---
+ ...
+ tarantool> box.schema.func.drop('f7')
+ ---
+ ...
+
+===========================================================
+ ``box.session`` and security
+===========================================================
+
+After a connection has taken place, the user has access to a "session" object
+which has several functions. The ones which are of interest for security
+purposes are:
+
+.. code-block:: lua
+
+ box.session.uid() -- returns the id of the current user
+ box.session.user() -- returns the name of the current user
+ box.session.su(user-name) -- allows changing current user to 'user-name'
+
+If a user types requests directly on the Tarantool server in its interactive
+mode, or if a user connects via telnet to the administrative port (using :ref:`admin <admin_port>`
+instead of listen), then the user by default is 'admin' and has many privileges.
+If a user connects from an application program via one of the :ref:`connectors <box-connectors>`, then
+the user by default is 'guest' and has few privileges. Typically an admin user
+will set up and configure objects, then grant privileges to appropriate non-admin
+users. Typically a guest user will use ``box.session.su()`` to change into a non-generic
+user to whom admin has granted more than the default privileges. For example,
+admin might say:
+
+.. _connectors: :doc:`../connectors/index`
+
+.. code-block:: lua
+
+ box.space._user:insert{123456,0,'manager'}
+ box.schema.user.grant('manager', 'read', 'space', '_space')
+ box.schema.user.grant('manager', 'read', 'space', 'payroll')
+
+and later a guest user, who wishes to see the payroll, might say:
+
+.. code-block:: lua
+
+ box.session.su('manager')
+ box.space.payroll:select{'Jones'}
+
+===========================================================
+ Roles
+===========================================================
+
+A role is a container for privileges which can be granted to regular users.
+Instead of granting and revoking individual privileges, one can put all the
+privileges in a role and then grant or revoke the role. Role information is
+in the ``_user`` space but the third field - the type field - is 'role' rather
+than 'user'.
+
+If a role R1 is granted a privilege X, and user U1 is granted a privilege
+"role R1", then user U1 in effect has privilege X. Then if a role R2 is
+granted a privilege Y, and role R1 is granted a privilege "role R2",
+then user U1 in effect has both privilege X and privilege Y. In other words,
+a user gets all the privileges that are granted to a user's roles, directly
+or indirectly.
+
+.. module:: box.schema.role
+
+.. function:: create(role-name)
+
+ Create a new role.
+
+.. function:: grant(role-name, privilege)
+
+ Put a privilege in a role.
+
+.. function:: revoke(role-name, privilege)
+
+ Take a privilege out of a role.
+
+.. function:: drop(role-name)
+
+ Drop a role.
+
+.. function:: info()
+
+ Get information about a role.
+
+.. function:: grant(role-name, 'execute', 'role', role-name)
+
+ Grant a role to a role.
+
+.. function:: revoke(role-name, 'execute', 'role', role-name)
+
+ Revoke a role from a role.
+
+.. function:: exists(role-name)
+
+ Check whether a role exists.
+ :return: true if role-name identifies a role, otherwise false.
+ :rtype: boolean
+
+.. module:: box.schema.user
+
+.. function:: grant(user-name, 'execute', 'role', role-name)
+
+ Grant a role to a user.
+
+.. function:: revoke(user-name, 'execute', 'role', role-name)
+
+ Revoke a role from a user.
+
+There is one predefined role, named 'public', which is automatically assigned
+to new users when they are created with ``box.schema.user.create(user-name)``.
+Therefore a convenient way to grant 'read' on space '``t``' to every user that
+will ever exist is:
+
+.. code-block:: lua
+
+ box.schema.role.grant('public','read','space','t').
+
+===========================================================
+ Example
+===========================================================
+
+In this example, a new user named U1 will insert a new tuple into a new space
+named T, and will succeed even though user U1 has no direct privilege to do
+such an insert -- that privilege is inherited from role R1, which in turn
+inherits from role R2.
+
+.. code-block:: lua
+
+ -- This example will work for a user with many privileges, such as 'admin'
+ box.schema.space.create('T')
+ box.space.T:create_index('primary',{})
+ -- Create a user U1 so that later it's possible to say box.session.su('U1')
+ box.schema.user.create('U1')
+ -- Create two roles, R1 and R2
+ box.schema.role.create('R1')
+ box.schema.role.create('R2')
+ -- Grant role R2 to role R1 and role R1 to U1 (order doesn't matter)
+ box.schema.role.grant('R1','execute','role','R2')
+ box.schema.role.grant('U1','execute','role','R1')
+ -- Grant read and execute privileges to R2 (but not to R1 and not to U1)
+ box.schema.role.grant('R2','read,write','space','T')
+ box.schema.role.grant('R2','execute','universe')
+ -- Use box.session.su to say "now become user U1"
+ box.session.su('U1')
+ -- The following insert succeeds because U1 in effect has write privilege on T
+ box.space.T:insert{1}
diff --git a/doc/sphinx/book/box/box_error.rst b/doc/sphinx/book/box/box_error.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f900b5c7ecf54421d651f446ad488267dd2f8852
--- /dev/null
+++ b/doc/sphinx/book/box/box_error.rst
@@ -0,0 +1,61 @@
+.. include:: ../../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `box.error`
+-------------------------------------------------------------------------------
+
+The ``box.error`` function is for raising an error. The difference between this
+function and 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 ``ER_PROC_LUA``.
+
+.. module:: box.error
+
+.. function:: box.error{reason=string [, code=number]}
+
+ When called with a Lua-table argument, the code and reason have any
+ user-desired values. The result will be those values.
+
+ :param integer code:
+ :param string reason:
+
+.. function:: box.error()
+
+ When called without arguments, ``box.error()`` re-throws whatever the last
+ error was.
+
+.. function:: box.error(code, errtext [, errtext ...])
+
+ Emulate 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``.
+
+ :param number code: number of a pre-defined error
+ :param string errtext(s): part of the message which will accompany the error
+
+ For example:
+
+ 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``".
+
+ :except: whatever is specified in errcode-number.
+
+ .. code-block:: lua
+
+ 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'
+ ...
diff --git a/doc/sphinx/book/box/box_index.rst b/doc/sphinx/book/box/box_index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8efeecd0c6a313358e282171201220f981838b77
--- /dev/null
+++ b/doc/sphinx/book/box/box_index.rst
@@ -0,0 +1,638 @@
+.. include:: ../../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `box.index`
+-------------------------------------------------------------------------------
+
+The ``box.index`` package provides read-only access for index definitions and
+index keys. Indexes are contained in ``box.space.space-name.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 of type
+``box.index`` in the storage engine.
+
+.. module:: box.index
+
+.. data:: box.space.space-name.index.index-name.unique
+
+ true if the index is unique.
+
+ :rtype: boolean
+
+.. data:: box.space.space-name.index.index-name.type
+
+ Index type, 'TREE' or 'HASH' or 'BITSET' or 'RTREE'.
+
+ :rtype: string
+
+.. data:: box.space.space-name.index.index-name.parts
+
+ An array describing index key fields.
+
+ :rtype: table
+
+ .. code-block:: lua
+
+ tarantool> box.space.tester.index.primary
+ ---
+ unique: true
+ parts:
+ 0:
+ type: NUM
+ fieldno: 1
+ id: 0
+ space_id: 513
+ name: primary
+ type: TREE
+ ...
+
+.. function:: box.space.space-name.index[.index-name]:pairs(bitset-value | field-value..., 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, a 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": by causing a write to disk, network, or by an
+ explicit call to :func:`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.
+
+ :param type: iteration strategy as defined in tables below
+ :return: this method returns an iterator closure, i.e. a function which can
+ be used to get the next value on each invocation
+ :rtype: function, tuple
+
+ :except: Selected iteration type is not supported in the subject index type,
+ or supplied parameters do not match iteration type.
+
+ Complexity Factors: Index size, Index type, Number of tuples accessed.
+
+ .. container:: table
+
+ **TREE iterator types**
+
+ +---------------+-----------+---------------------------------------------+
+ | Type | Arguments | Description |
+ +===============+===========+=============================================+
+ | box.index.ALL | none | Iterate over all tuples in an index. Tuples |
+ | or 'ALL' | | are returned in ascending order of the key. |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.EQ | field | Equality iterator: iterate over all tuples |
+ | or 'EQ' | values | where field values = key values. Parts of a |
+ | | | multi-part key need to be separated by |
+ | | | commas. |
+ | | | |
+ | | | If the number of field values is less than |
+ | | | the number of parts of a multi-part key, |
+ | | | the missing field values are considered to |
+ | | | be matching. |
+ | | | |
+ | | | If there are multiple matches, then tuples |
+ | | | are returned in ascending order by key. |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.GT | field | Keys match if key values are greater than |
+ | or 'GT' | values | field values. If the number of field values |
+ | | | is less than the number of parts of a |
+ | | | multi-part key, the missing field values |
+ | | | are considered to be matching. If the field |
+ | | | value is ``nil``, iteration starts from the |
+ | | | smallest key in the index. Tuples are |
+ | | | returned in ascending order by key. |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.REQ | field | Reverse equality iterator. Matching is |
+ | or 'REQ' | values | determined in the same way as for |
+ | | | ``box.index.EQ``, but, if there are multiple|
+ | | | matches, then tuples are returned in |
+ | | | descending order by key, |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.GE | field | Keys match if key values are greater than |
+ | or 'GE' | values | or equal to field values. Tuples are |
+ | | | returned in ascending order by key. If the |
+ | | | field value is ``nil``, iteration starts |
+ | | | from the first key in the index. |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.LT | field | Keys match if key values are less than |
+ | or 'LT' | values | field values. Tuples are returned in |
+ | | | descending order by key. If the field value |
+ | | | is ``nil``, iteration starts from the last |
+ | | | key in the index. |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.LE | field | Keys match if key values are less than or |
+ | or 'LE' | values | equal to field values. Tuples are returned |
+ | | | in descending order by key. If the field |
+ | | | value is ``nil``, iteration starts from |
+ | | | the last key in the index. |
+ +---------------+-----------+---------------------------------------------+
+
+ **HASH iterator types**
+
+ +---------------+-----------+---------------------------------------------+
+ | Type | Arguments | Description |
+ +===============+===========+=============================================+
+ | box.index.ALL | none | Iterate over all tuples in an index. Tuples |
+ | or 'ALL' | | are returned in ascending order of the key. |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.EQ | field | Equality iterator: iterate over all tuples |
+ | or 'EQ' | values | matching the key. Parts of a multi-part |
+ | | | key need to be separated by commas. |
+ | | | |
+ | | | A HASH index only supports exact match: |
+ | | | all parts of a key participating in the |
+ | | | index must be provided. |
+ | | | |
+ | | | HASH indexes are always unique. |
+ +---------------+-----------+---------------------------------------------+
+ | box.index.GT | field | Keys match if hashed key values are greater |
+ | or 'GT' | values | than hashed field values. If the number of |
+ | | | field values is less than the number of |
+ | | | parts of a multi-part key, the result is an |
+ | | | error. Tuples are returned in ascending |
+ | | | order by hashed key, so the order will |
+ | | | appear to be random. Provided that the |
+ | | | space is not being updated, the 'GT' |
+ | | | iterator can be used to retrieve all |
+ | | | tuples piece by piece, by supplying the |
+ | | | last returned value from the previous |
+ | | | range as the start field value for an |
+ | | | iterator over the next range. |
+ +---------------+-----------+---------------------------------------------+
+
+ **BITSET iterator types**
+
+ +----------------------------+-----------+---------------------------------------------+
+ | Type | Arguments | Description |
+ +============================+===========+=============================================+
+ | box.index.ALL | none | Iterate over all tuples in an index. Tuples |
+ | or 'ALL' | | are returned in ascending order of the |
+ | | | key's bitset, and so will appear to be |
+ | | | unordered. |
+ +----------------------------+-----------+---------------------------------------------+
+ | box.index.EQ | field | Equality iterator: iterate over all tuples |
+ | or 'EQ' | values | matching the field values. If there are |
+ | | | multiple field values, they need to be |
+ | | | separated by commas. |
+ | | | |
+ | | | BITSET indexes are always unique. |
+ +----------------------------+-----------+---------------------------------------------+
+ | box.index.BITS_ALL_SET | field | Keys match if all of the bits specified in |
+ | | values | 'bit mask' are set. |
+ +----------------------------+-----------+---------------------------------------------+
+ | box.index.BITS_ANY_SET | field | Keys match if any of the bits specified in |
+ | | values | 'bit mask' is set. |
+ +----------------------------+-----------+---------------------------------------------+
+ | box.index.BITS_ALL_NOT_SET | field | Keys match if none of the bits specified in |
+ | | values | 'bit mask' is set. |
+ +----------------------------+-----------+---------------------------------------------+
+
+ .. _rtree-iterator:
+
+ **RTREE iterator types**
+
+ +--------------------+-----------+---------------------------------------------+
+ | Type | Arguments | Description |
+ +====================+===========+=============================================+
+ | box.index.ALL | none | All keys match. Tuples are returned in |
+ | or 'ALL' | | ascending order of the primary key. |
+ +--------------------+-----------+---------------------------------------------+
+ | box.index.EQ | field | Keys match if the rectangle defined by the |
+ | or 'EQ' | values | field values is the same as the rectangle |
+ | | | defined by the key -- where "key" means |
+ | | | "the key in the RTREE index" and |
+ | | | "rectangle" means "rectangle as explained |
+ | | | in section RTREE_. |
+ +--------------------+-----------+---------------------------------------------+
+ | box.index.GT | field | Keys match if all points of the rectangle |
+ | or 'GT' | values | defined by the field values are within the |
+ | | | rectangle defined by the key. |
+ +--------------------+-----------+---------------------------------------------+
+ | box.index.GE | field | Keys match if all points of the rectangle |
+ | or 'GE' | values | defined by the field values are within, or |
+ | | | at the side of, the rectangle defined by |
+ | | | the key. |
+ +--------------------+-----------+---------------------------------------------+
+ | box.index.LT | field | Keys match if all points of the rectangle |
+ | or 'LT' | values | defined by the key are within the rectangle |
+ | | | defined by the field values. |
+ +--------------------+-----------+---------------------------------------------+
+ | box.index.LE | field | Keys match if all points of the rectangle |
+ | or 'LE' | values | defined by the key are within, or at the |
+ | | | side of, the rectangle defined by the field |
+ | | | values. |
+ +--------------------+-----------+---------------------------------------------+
+ | box.index.OVERLAPS | field | Keys match if all points of the rectangle |
+ | or 'OVERLAPS' | values | defined by the key are within, or at the |
+ | | | side of, the rectangle defined by the field |
+ | | | values. |
+ +--------------------+-----------+---------------------------------------------+
+ | box.index.NEIGHBOR | field | Keys match if all points of the rectangle |
+ | or 'NEIGHBOR' | values | defined by the key are within, or at the |
+ | | | side of, the rectangle defined by the field |
+ | | | values. |
+ +--------------------+-----------+---------------------------------------------+
+
+ .. code-block:: lua
+
+ tarantool> s = box.schema.space.create('space17')
+ ---
+ ...
+ tarantool> s:create_index('primary', {parts = {1, 'STR', 2, 'STR'}})
+ ---
+ ...
+ tarantool> s:insert{'C', 'C'}
+ ---
+ - ['C', 'C']
+ ...
+ tarantool> s:insert{'B', 'A'}
+ ---
+ - ['B', 'A']
+ ...
+ tarantool> s:insert{'C', '!'}
+ ---
+ - ['C', '!']
+ ...
+ tarantool> s:insert{'A', 'C'}
+ ---
+ - ['A', 'C']
+ ...
+ tarantool> console = require('console'); console.delimiter('!')
+ ---
+ ...
+ tarantool> function example()
+ > for _, tuple in
+ > s.index.primary:pairs(nil, {iterator = box.index.ALL}) do
+ > print(tuple)
+ > end
+ > end!
+ ---
+ ...
+ tarantool> console.delimiter('')!
+ ---
+ ...
+ tarantool> example()
+ ['A', 'C']
+ ['B', 'A']
+ ['C', '!']
+ ['C', 'C']
+ ---
+ ...
+ tarantool> s:drop()
+ ---
+ ...
+
+.. function:: box.space.space-name[.index.index-name]:select({[field-value [, field-value ...]]}, {[option [, option ...]]})
+
+ This is is an alternative to box.space...select() which goes via a
+ particular index and can make use of additional parameters that specify the
+ iterator type, and the limit (that is, the maximum number of tuples to
+ return) and the offset (that is, which tuple to start with in the list).
+
+ :param lua-value field-value(s): values to be matched against the index key.
+ :param lua-value option(s): any or all of iterator=iterator-type
+ limit=maximum-number-of-tuples,
+ offset=start-tuple-number.
+
+ :return: the tuple or tuples that match the field values.
+ :rtype: tuple set as a Lua table
+
+ .. code-block:: lua
+
+ -- Create a space named tester.
+ -- Create a unique index 'primary', which won't be needed for this example.
+ -- Create a non-unique index 'secondary' with an index on the second field.
+ -- Insert three tuples, values in field[2] equal to 'X', 'Y', and 'Z'.
+ -- Select all tuples where the secondary index keys are greater than 'X'.
+ box.schema.space.create('tester')
+ box.space.tester:create_index('primary', {parts = {1, 'NUM' }})
+ box.space.tester:create_index('secondary', {type = 'tree', unique = false, parts = {2, 'STR'}})
+ box.space.tester:insert{1,'X','Row with field[2]=X'}
+ box.space.tester:insert{2,'Y','Row with field[2]=Y'}
+ box.space.tester:insert{3,'Z','Row with field[2]=Z'}
+ box.space.tester.index.secondary:select({'X'}, {iterator = 'GT', limit = 1000})
+
+ The result will be a table of tuple and will look like this:
+
+ .. code-block:: yaml
+
+ ---
+ - - [2, 'Y', 'Row with field[2]=Y']
+ - [3, 'Z', 'Row with field[2]=Z']
+ ...
+
+ .. NOTE::
+
+ [.index.index-name] is optional. If it is omitted, then the assumed
+ index is the first (primary-key) index. Therefore, for the example
+ above, ``box.space.tester:select({1}, {iterator = 'GT'})`` would have
+ returned the same two rows, via the 'primary' index.
+
+ .. NOTE::
+
+ ``iterator = iterator type`` is optional. If it is omitted, then
+ ``iterator = 'EQ'`` is assumed.
+
+ .. NOTE::
+
+ ``field-value [, field-value ...]`` is optional. If it is omitted,
+ then every key in the index is considered to be a match, regardless of
+ iterator type. Therefore, for the example above,
+ ``box.space.tester:select{}`` will select every tuple in the tester
+ space via the first (primary-key) index.
+
+ .. NOTE::
+
+ ``box.space.space-name.index.index-name:select(...)[1]``. can be
+ replaced by ``box.space.space-name.index.index-name:get(...)``.
+ That is, get can be used as a convenient shorthand to get the first
+ tuple in the tuple set that would be returned by select. However,
+ if there is more than one tuple in the tuple set, then get returns
+ an error.
+
+.. function:: box.space.space-name.index.index-name:min([key-value])
+
+ Find the minimum value in the specified index.
+
+ :return: the tuple for the first key in the index. If optional
+ ``key-value`` is supplied, returns the first key which
+ is greater than or equal to ``key-value``.
+ :rtype: tuple
+ :except: index is not of type 'TREE'.
+
+ Complexity Factors: Index size, Index type.
+
+ .. code-block:: lua
+
+ tarantool> box.space.tester.index.primary:min()
+ ---
+ - ['Alpha!', 55, 'This is the first tuple!']
+ ...
+
+.. function:: box.space.space-name.index.index-name:max([key-value])
+
+ Find the maximum value in the specified index.
+
+ :return: the tuple for the last key in the index. If optional ``key-value``
+ is supplied, returns the last key which is less than or equal to
+ ``key-value``.
+ :rtype: tuple
+ :except: index is not of type 'TREE'.
+
+ Complexity Factors: Index size, Index type.
+
+ .. code-block:: lua
+
+ tarantool> box.space.tester.index.primary:max()
+ ---
+ - ['Gamma!', 55, 'This is the third tuple!']
+ ...
+
+
+.. function:: box.space.space-name.index.index-name:random(random-value)
+
+ Find a random value in the specified index. 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.
+
+ :param integer random-value: an arbitrary non-negative integer.
+ :return: the tuple for the random key in the index.
+ :rtype: tuple
+
+ Complexity Factors: Index size, Index type.
+
+ .. code-block:: lua
+
+ tarantool> box.space.tester.index.secondary:random(1)
+ ---
+ - ['Beta!', 66, 'This is the second tuple!']
+ ...
+
+.. function:: box.space.space-name.index.index-name:count(key-value, options)
+
+ Iterate over an index, counting the number of
+ tuples which equal the provided search criteria.
+
+ :param lua-value key-value: the value which must match the key(s) in the
+ specified index. The type may be a list of
+ field-values, or a tuple containing only
+ the field-values.
+
+ :return: the number of matching index keys. The ``index`` function
+ is only applicable for the memtx storage engine.
+ :rtype: number
+
+ .. code-block:: lua
+
+ tarantool> box.space.tester.index.primary:count(999)
+ ---
+ - 0
+ ...
+ tarantool> box.space.tester.index.primary:count('Alpha!', { iterator = 'LE' })
+ ---
+ - 1
+ ...
+
+.. function:: box.space.space-name.index.index-name:alter{options}
+
+ Alter an index.
+
+ :param table options: options list for create_index().
+ :return: nil
+
+ :except: If index-name doesn't exist.
+ :except: The first index cannot be changed to {unique = false}.
+ :except: The alter function is only applicable for the memtx storage engine.
+
+ .. code-block:: lua
+
+ tarantool> box.space.space55.index.primary:alter({type = 'HASH'})
+ ---
+ ...
+
+.. function:: space-name.index.index-name:drop()
+
+ Drop an index. Dropping a primary-key index has
+ a side effect: all tuples are deleted.
+
+ :return: nil.
+ :except: If index-name doesn't exist.
+
+ .. code-block:: lua
+
+ tarantool> box.space.space55.index.primary:drop()
+ ---
+ ...
+
+.. function:: space-name.index.index-name:rename(index-name)
+
+ Rename an index.
+
+ :param string index-name: new name for index.
+ :return: nil
+ :except: If index-name doesn't exist.
+
+ .. code-block:: lua
+
+ tarantool> box.space.space55.index.primary:rename('secondary')
+ ---
+ ...
+
+ Complexity Factors: Index size, Index type, Number of tuples accessed.
+
+
+===========================================================
+ Example
+===========================================================
+
+This example will work with the sandbox configuration described in the preface.
+That is, there is a space named tester with a numeric primary key. The example
+function will:
+
+* select a tuple whose key value is 1000;
+* return an error if the tuple already exists and already has 3 fields;
+* Insert or replace the tuple with:
+ * field[1] = 1000
+ * field[2] = a uuid
+ * field[3] = number of seconds since 1970-01-01;
+* Get field[3] from what was replaced;
+* Format the value from field[3] as yyyy-mm-dd hh:mm:ss.ffff;
+* Return the formatted value.
+
+The function uses Tarantool box functions box.space...select,
+box.space...replace, fiber.time, uuid.str(). The function uses
+Lua functions os.date() and string.sub().
+
+.. code-block:: lua
+
+ console = require('console'); console.delimiter('!')
+ function example()
+ local a, b, c, table_of_selected_tuples, replaced_tuple, time_field
+ local formatted_time_field
+ local fiber = require('fiber')
+ table_of_selected_tuples = box.space.tester:select{1000}
+ if table_of_selected_tuples ~= nil then
+ if table_of_selected_tuples[1] ~= nil then
+ if #table_of_selected_tuples[1] == 3 then
+ box.error({code=1, reason='This tuple already has 3 fields'})
+ end
+ end
+ end
+ replaced_tuple = box.space.tester:replace
+ {1000, require('uuid').str(), tostring(fiber.time())}
+ time_field = tonumber(replaced_tuple[3])
+ formatted_time_field = os.date("%Y-%m-%d %H:%M:%S", time_field)
+ c = time_field % 1
+ d = string.sub(c, 3, 6)
+ formatted_time_field = formatted_time_field .. '.' .. d
+ return formatted_time_field
+ end!
+ console.delimiter('')!
+
+... And here is what happens when one invokes the function:
+
+.. code-block:: lua
+
+ tarantool> box.space.tester:delete(1000)
+ ---
+ - 1000: {'264ee2da03634f24972be76c43808254', '1391037015.6809'}
+ ...
+ tarantool> example(1000)
+ ---
+ - 2014-01-29 16:11:51.1582
+ ...
+ tarantool> example(1000)
+ ---
+ - error: 'This tuple already has 3 fields'
+ ...
+
+.. _RTREE:
+
+===========================================================
+ Package `box.index` for RTREE
+===========================================================
+
+The :mod:`box.index` package may be used for spatial searches if the index type
+is RTREE. There are operations for searching ``rectangles``. Rectangles are
+described according to their X-axis (horizontal axis) and Y-axis (vertical axis)
+coordinates in a grid of arbitrary size. Here is a picture of four rectangles on
+a grid with 11 horizontal points and 11 vertical points:
+
+::
+
+ X AXIS
+ 1 2 3 4 5 6 7 8 9 10 11
+ 1
+ 2 #-------+ <-Rectangle#1
+ Y AXIS 3 | |
+ 4 +-------#
+ 5 #-----------------------+ <-Rectangle#2
+ 6 | |
+ 7 | #---+ | <-Rectangle#3
+ 8 | | | |
+ 9 | +---# |
+ 10 +-----------------------#
+ 11 # <-Rectangle#4
+
+The rectangles are defined according to this scheme: {X-axis coordinate of top
+left, Y-axis coordinate of top left, X-axis coordinate of bottom right, Y-axis
+coordinate of bottom right} -- or more succinctly: {x1,y1,x2,y2}. So in the
+picture ... Rectangle#1 starts at position 1 on the X axis and position 2 on
+the Y axis, and ends at position 3 on the X axis and position 4 on the Y axis,
+so its coordinates are {1,2,3,4}. Rectangle#2's coordinates are {3,5,9,10}.
+Rectangle#3's coordinates are {4,7,5,9}. And finally Rectangle#4's coordinates
+are {10,11,10,11}. Rectangle#4 is actually a "point" since it has zero width
+and zero height, so it could have been described with only two digits: {10,11}.
+
+Some relationships between the rectangles are: "Rectangle#1's nearest neighbor
+is Rectangle#2", and "Rectangle#3 is entirely inside Rectangle#2".
+
+Now let us create a space and add an RTREE index.
+
+.. code-block:: lua
+
+ s = box.schema.create_space('rectangles')
+ i = s:create_index('primary',{type='HASH',parts={1,'NUM'}})
+ r = s:create_index('spatial',{type='RTREE',unique=false,parts={2,'ARRAY'}})
+
+Field#1 doesn't matter, we just make it because we need a primary-key index.
+(RTREE indexes cannot be unique and therefore cannot be primary-key indexes.)
+The second field must be an "array", which means its values must represent
+{x,y} points or {x1,y1,x2,y2} rectangles. Now let us populate the table by
+inserting two tuples, containing the coordinates of Rectangle#2 and Rectangle#4.
+
+.. code-block:: lua
+
+ s:insert{1, {3,5,9,10}}
+ s:insert{2, {10,11}}
+
+And now, following the description of `RTREE iterator types`_, we can search the
+rectangles with these requests:
+
+.. _RTREE iterator types: rtree-iterator_
+
+.. code-block:: lua
+
+ r:select({10,11,10,11},{iterator='EQ'}) -- Request#1 (returns 1 tuple)
+ r:select({4,7,5,9},{iterator='GT'}) -- Request#2 (returns 1 tuple)
+ r:select({1,2,3,4},{iterator='NEIGHBOR'}) -- Request#3 (returns 2 tuples)
+
+Request#1 returns 1 tuple because the point {10,11} is the same as the rectangle
+{10,11,10,11} ("Rectangle#4" in the picture). Request#2 returns 1 tuple because
+the rectangle {4,7,5,9}, which was "Rectangle#3" in the picture, is entirely
+within{3,5,9,10} which was Rectangle#2. Request#3 returns 2 tuples, because the
+NEIGHBOR iterator always returns all tuples, and the first returned tuple will
+be {3,5,9,10} ("Rectangle#2" in the picture) because it is the closest neighbor
+of {1,2,3,4} ("Rectangle#1" in the picture).
+
+More examples of spatial searching are online in the file `R tree index quick
+start and usage`_.
+
+.. _R tree index quick start and usage: https://github.com/tarantool/tarantool/wiki/R-tree-index-quick-start-and-usage
+
diff --git a/doc/sphinx/book/box/box_introspection.rst b/doc/sphinx/book/box/box_introspection.rst
new file mode 100644
index 0000000000000000000000000000000000000000..4f7c2e7b756089336d0f73290e769e70c06ccfbd
--- /dev/null
+++ b/doc/sphinx/book/box/box_introspection.rst
@@ -0,0 +1,220 @@
+.. include:: ../../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Server Introspection
+-------------------------------------------------------------------------------
+
+=====================================================================
+ Package `box.cfg`
+=====================================================================
+
+.. module:: box.cfg
+
+The ``box.cfg`` package is for administrators to specify all the server
+configuration parameters; the full description of the parameters is in
+section :ref:`box-configuration`. Use ``box.cfg`` without braces to get read-only
+access to those parameters.
+
+.. data:: box.cfg
+
+ .. code-block:: lua
+
+ tarantool> box.cfg
+ ---
+ - too_long_threshold: 0.5
+ slab_alloc_factor: 2
+ slab_alloc_minimal: 64
+ background: false
+ slab_alloc_arena: 1
+ log_level: 5
+ ...
+ ...
+
+=====================================================================
+ Package `box.info`
+=====================================================================
+
+.. module:: box.info
+
+The ``box.info`` package provides access to information about server variables
+-- ``pid``, ``uptime``, ``version`` and others.
+
+**recovery_lag** holds the difference (in seconds) between the current time on
+the machine (wall clock time) and the time stamp of the last applied record.
+In replication setup, this difference can indicate the delay taking place
+before a change is applied to a replica.
+
+**recovery_last_update** is the wall clock time of the last change recorded in
+the write-ahead log. To convert it to human-readable time,
+you can use **date -d@** 1306964594.980.
+
+**status** is either "primary" or "replica/<hostname>".
+
+.. function:: box.info()
+
+ Since ``box.info`` contents are dynamic, it's not possible to iterate over
+ keys with the Lua ``pairs()`` function. For this purpose, ``box.info()``
+ builds and returns a Lua table with all keys and values provided in the
+ package.
+
+ :return: keys and values in the package.
+ :rtype: table
+
+ .. code-block:: yaml
+
+ tarantool> box.info()
+ ---
+ - server:
+ lsn: 158
+ ro: false
+ uuid: 75967704-0115-47c2-9d03-bd2bdcc60d64
+ id: 1
+ pid: 32561
+ version: 1.6.4-411-gcff798b
+ snapshot_pid: 0
+ status: running
+ vclock: {1: 158}
+ replication:
+ status: off
+ uptime: 2778
+ ...
+
+.. data:: status
+ pid
+ version
+ ...
+
+ .. code-block:: lua
+
+ tarantool> box.info.pid
+ ---
+ - 1747
+ ...
+ tarantool> box.info.logger_pid
+ ---
+ - 1748
+ ...
+ tarantool> box.info.version
+ ---
+ - 1.6.4-411-gcff798b
+ ...
+ tarantool> box.info.uptime
+ ---
+ - 3672
+ ...
+ tarantool> box.info.status
+ ---
+ - running
+ ...
+ tarantool> box.info.recovery_lag
+ ---
+ - 0.000
+ ...
+ tarantool> box.info.recovery_last_update
+ ---
+ - 1306964594.980
+ ...
+ tarantool> box.info.snapshot_pid
+ ---
+ - 0
+ ...
+
+=====================================================================
+ Package `box.slab`
+=====================================================================
+
+.. module:: box.slab
+
+The ``box.slab`` package provides access to slab allocator statistics. The
+slab allocator is the main allocator used to store tuples. This can be used
+to monitor the total memory use and memory fragmentation.
+
+The display of slabs is broken down by the slab size -- 64-byte, 136-byte,
+and so on. The example omits the slabs which are empty. The example display
+is saying that: there are 16 items stored in the 64-byte slab (and 16*64=102
+so bytes_used = 1024); there is 1 item stored in the 136-byte slab
+(and 136*1=136 so bytes_used = 136); the arena_used value is the total of all
+the bytes_used values (1024+136 = 1160); the arena_size value is the arena_used
+value plus the total of all the bytes_free values (1160+4193200+4194088 = 8388448).
+The arena_size and arena_used values are the amount of the % of slab_alloc_arena
+that is already distributed to the slab allocator.
+
+.. data:: slab
+
+ .. code-block:: lua
+
+ tarantool> box.slab.info().arena_used
+ ---
+ - 4194304
+ ...
+ tarantool> box.slab.info().arena_size
+ ---
+ - 104857600
+ ...
+ tarantool> box.slab.info().slabs
+ ---
+ - - {mem_free: 9320, mem_used: 6976, 'item_count': 109,
+ 'item_size': 64, 'slab_count': 1, 'slab_size': 16384}
+ - {mem_free: 16224, mem_used: 72, 'item_count': 1,
+ 'item_size': 72, 'slab_count': 1,'slab_size': 16384}
+ etc.
+ ...
+ tarantool> box.slab.info().slabs[1]
+ ---
+ - {mem_free: 9320, mem_used: 6976, 'item_count': 109,
+ 'item_size': 64, 'slab_count': 1, 'slab_size': 16384}
+ ...
+
+=====================================================================
+ Package `box.stat`
+=====================================================================
+
+.. module:: box.stat
+
+The ``box.stat`` package provides access to request statistics. Show the
+average number of requests per second, and the total number of requests
+since startup, broken down by request type.
+
+.. data:: box.stat
+
+ .. code-block:: lua
+
+ tarantool> box.stat, type(box.stat) -- a virtual table
+ ---
+ - []
+ - table
+ ...
+ tarantool> box.stat() -- the full contents of the table
+ ---
+ - DELETE:
+ total: 48902544
+ rps: 147
+ EVAL:
+ total: 0
+ rps: 0
+ SELECT:
+ total: 388322317
+ rps: 1246
+ REPLACE:
+ total: 4
+ rps: 0
+ INSERT:
+ total: 48207694
+ rps: 139
+ AUTH:
+ total: 0
+ rps: 0
+ CALL:
+ total: 8
+ rps: 0
+ UPDATE:
+ total: 743350520
+ rps: 1874
+ ...
+ tarantool> box.stat().DELETE -- a selected item of the table
+ ---
+ - total: 48902544
+ rps: 0
+ ...
+
diff --git a/doc/sphinx/book/box/box_schema.rst b/doc/sphinx/book/box/box_schema.rst
new file mode 100644
index 0000000000000000000000000000000000000000..cc608a226a2e60902893733d580e67b1a9aa6d66
--- /dev/null
+++ b/doc/sphinx/book/box/box_schema.rst
@@ -0,0 +1,63 @@
+.. include:: ../../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `box.schema`
+-------------------------------------------------------------------------------
+
+.. module:: box.schema
+
+The ``box.schema`` package has one data-definition function: ``space.create()``.
+
+.. function:: space.create(space-name [, {options} ])
+
+ Create a space.
+
+ :param string space-name: name of space, which should not be a number and should not contain special characters
+ :param table options:
+
+ :return: space object
+ :rtype: userdata
+
+ .. container:: table
+
+ **Options for box.schema.space.create**
+
+ +---------------+--------------------+---------+---------------------+
+ | Name | Effect | Type | Default |
+ +===============+====================+=========+=====================+
+ | temporary | space is temporary | boolean | false |
+ +---------------+--------------------+---------+---------------------+
+ | id | unique identifier | number | last space's id, +1 |
+ +---------------+--------------------+---------+---------------------+
+ | field_count | fixed field count | number | 0 i.e. not fixed |
+ +---------------+--------------------+---------+---------------------+
+ | if_not_exists | no error if | boolean | false |
+ | | duplicate name | | |
+ +---------------+--------------------+---------+---------------------+
+ | engine | storage package | string | 'memtx' |
+ +---------------+--------------------+---------+---------------------+
+ | user | user name | string | current user's name |
+ +---------------+--------------------+---------+---------------------+
+
+=================================================
+ Example
+=================================================
+
+.. code-block:: lua
+
+ tarantool> s = box.schema.space.create('space55')
+ ---
+ ...
+ tarantool> s = box.schema.space.create('space55', {id = 555, temporary = false})
+ ---
+ - error: Space 'space55' already exists
+ ...
+ tarantool> s = box.schema.space.create('space55', {if_not_exists = true})
+ ---
+ ...
+
+After a space is created, usually the next step is to
+:func:`create an index <box.space.space-name.create_index>` for it,
+and then it is available for insert, select, and all the other :mod:`box.space`
+functions.
diff --git a/doc/sphinx/book/box/box_session.rst b/doc/sphinx/book/box/box_session.rst
new file mode 100644
index 0000000000000000000000000000000000000000..fc92f39da6abefbb4ddde050a7250911d76e789c
--- /dev/null
+++ b/doc/sphinx/book/box/box_session.rst
@@ -0,0 +1,73 @@
+.. include:: ../../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `box.session`
+-------------------------------------------------------------------------------
+
+The ``box.session`` package allows querying the session state, writing to a
+session-specific temporary Lua table, or setting up triggers which will fire
+when a session starts or ends. A *session* is an object associated with each
+client connection.
+
+.. module:: box.session
+
+.. function:: id()
+
+ :return: the unique identifier (ID) for the current session.
+ The result can be 0 meaning there is no session.
+ :rtype: number
+
+.. function:: exists(id)
+
+ :return: 1 if the session exists, 0 if the session does not exist.
+ :rtype: number
+
+.. function:: peer(id)
+
+ :return: If the specified session exists, the host address and port of
+ the session peer, for example "127.0.0.1:55457". If the
+ specified session does not exist, "0.0.0.0:0". The command is
+ executed on the server, so the "local name" is the server's host
+ and administrative port, and the "peer name" is the client's host
+ and port.
+ :rtype: string
+
+.. data:: storage
+
+ A Lua table that can hold arbitrary unordered session-specific
+ names and values, which will last until the session ends.
+
+=================================================
+ Example
+=================================================
+
+.. code-block:: lua
+
+ tarantool> box.session.peer(session.id())
+ ---
+ - 127.0.0.1:45129
+ ...
+ tarantool> box.session.storage.random_memorandum = "Don't forget the eggs."
+ ---
+ ...
+ tarantool> box.session.storage.radius_of_mars = 3396
+ ---
+ ...
+ tarantool> m = ''
+ ---
+ ...
+ tarantool> for k, v in pairs(box.session.storage) do m=m..k..'='..v..' ' end
+ ---
+ ...
+ tarantool> m
+ ---
+ - 'radius_of_mars=3396 random_memorandum=Don''t forget the eggs. '
+ ...
+
+See the section :ref:`Triggers on connect and disconnect <box-triggers>`
+for instructions about defining triggers for connect and disconnect
+events with ``box.session.on_connect()`` and ``box.session.on_disconnect()``.
+See the section :ref:`Authentication and access control <box-authentication>`
+for instructions about ``box.session`` functions that affect user
+identification and security.
diff --git a/doc/sphinx/book/box/box_space.rst b/doc/sphinx/book/box/box_space.rst
new file mode 100644
index 0000000000000000000000000000000000000000..6e4d4e9b38ad6dee4f0a12d30edc22fb43d34e60
--- /dev/null
+++ b/doc/sphinx/book/box/box_space.rst
@@ -0,0 +1,785 @@
+.. include:: ../../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `box.space`
+-------------------------------------------------------------------------------
+
+.. module:: box.space
+
+The ``box.space`` package has the data-manipulation functions ``select``,
+``insert``, ``replace``, ``update``, ``delete``, ``get``, ``put``. It also has
+members, such as id, and whether or not a space is enabled. Package source code
+is available in file
+`src/box/lua/box.lua <https://github.com/tarantool/tarantool/blob/master/src/box/lua/box.lua>`_.
+
+A list of all ``box.space`` functions follows, then comes a list of all
+``box.space`` members.
+
+.. function:: box.space.space-name:create_index(index-name [, {options} ])
+
+ Create an index. It is **mandatory** to create an index for a tuple set
+ before trying to insert tuples into it, or select tuples from it. The
+ first created index, which will be used as the primary-key index, must be
+ **unique**.
+
+ :param string index-name: name of index, which should not be a number and
+ should not contain special characters;
+ :param table options:
+
+ :return: index object
+ :rtype: userdata
+
+ .. container:: table
+
+ **Options for box.space...create_index**
+
+ +---------------+--------------------+-----------------------------+---------------------+
+ | Name | Effect | Type | Default |
+ +===============+====================+=============================+=====================+
+ | type | type of index | string | 'TREE' |
+ | | | ('HASH', 'TREE', | |
+ | | | 'BITSET', 'RTREE') | |
+ | | | | |
+ | | | | |
+ | | | | |
+ +---------------+--------------------+-----------------------------+---------------------+
+ | id | unique identifier | number | last index's id, +1 |
+ +---------------+--------------------+-----------------------------+---------------------+
+ | unique | index is unique | boolean | true |
+ +---------------+--------------------+-----------------------------+---------------------+
+ | if_not_exists | no error if | boolean | false |
+ | | duplicate name | | |
+ +---------------+--------------------+-----------------------------+---------------------+
+ | parts | field-numbers + | ``{field_no, 'NUM'|'STR'}`` | ``{1, 'NUM'}`` |
+ | | types | | |
+ +---------------+--------------------+-----------------------------+---------------------+
+
+ Possible errors: too many parts. A type options other than TREE, or a
+ unique option other than unique, or a parts option with more than one
+ field component, is only applicable for the memtx storage engine.
+
+ .. code-block:: lua
+
+ tarantool> s = box.space.space55
+ ---
+ ...
+ tarantool> s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})
+ ---
+ ...
+
+.. function:: box.space.space-name:insert{field-value [, field-value ...]}
+
+ Insert a tuple into a space.
+
+ :param userdata space-name:
+ :param lua-value field-value(s): fields of the new tuple.
+ :return: the inserted tuple
+ :rtype: tuple
+
+ :except: If a tuple with the same unique-key value already exists,
+ returns ``ER_TUPLE_FOUND``.
+
+ .. code-block:: lua
+
+ box.space.tester:insert{5000,'tuple number five thousand'}
+
+.. function:: box.space.space-name:select{field-value [, field-value ...]}
+
+ Search for a tuple or a set of tuples in the given space.
+
+ :param userdata space-name:
+ :param lua-value field-value(s): values to be matched against the index
+ key, which may be multi-part.
+
+ :return: the tuples whose primary-key fields are equal to the passed
+ field-values. If the number of passed field-values is less
+ than the number of fields in the primary key, then only the
+ passed field-values are compared, so ``select{1,2}`` will match
+ a tuple whose primary key is ``{1,2,3}``.
+ :rtype: tuple
+
+ :except: No such space; wrong type.
+
+ Complexity Factors: Index size, Index type.
+
+ .. code-block:: lua
+
+ tarantool> s = box.schema.space.create('tmp', {temporary=true})
+ ---
+ ...
+ tarantool> s:create_index('primary',{parts = {1,'NUM', 2, 'STR'}})
+ ---
+ ...
+ tarantool> s:insert{1,'A'}
+ ---
+ - [1, 'A']
+ ...
+ tarantool> s:insert{1,'B'}
+ ---
+ - [1, 'B']
+ ...
+ tarantool> s:insert{1,'C'}
+ ---
+ - [1, 'C']
+ ...
+ tarantool> s:insert{2,'D'}
+ ---
+ - [2, 'D']
+ ...
+ tarantool> -- must equal both primary-key fields
+ tarantool> s:select{1,'B'}
+ ---
+ - - [1, 'B']
+ ...
+ tarantool> -- must equal only one primary-key field
+ tarantool> s:select{1}
+ ---
+ - - [1, 'A']
+ - [1, 'B']
+ - [1, 'C']
+ ...
+ tarantool> -- must equal 0 fields, so returns all tuples
+ tarantool> s:select{}
+ ---
+ - - [1, 'A']
+ - [1, 'B']
+ - [1, 'C']
+ - [2, 'D']
+ ...
+
+ For examples of complex ``select``s, where one can specify which index to
+ search and what condition to use (for example "greater than" instead of
+ "equal to") and how many tuples to return, see the later section
+ ``box.space.space-name[.index.index-name]:select``.
+
+.. function:: box.space.space-name:get{field-value [, field-value ...]}
+
+ Search for a tuple in the given space.
+
+ :param userdata space-name:
+ :param lua-value field-value(s): values to be matched against the index
+ key, which may be multi-part.
+ :return: the selected tuple.
+ :rtype: tuple
+
+ :except: If space-name does not exist.
+
+ Complexity Factors: Index size, Index type,
+ Number of indexes accessed, WAL settings.
+
+ .. code-block:: lua
+
+ tarantool> box.space.tester:get{1}
+
+.. function:: box.space.space-name:drop()
+
+ Drop a space.
+
+ :return: nil
+ :except: If space-name does not exist.
+
+ Complexity Factors: Index size, Index type,
+ Number of indexes accessed, WAL settings.
+
+ .. code-block:: lua
+
+ tarantool> box.space.space_that_does_not_exist:drop()
+
+.. function:: box.space.space-name:rename(space-name)
+
+ Rename a space.
+
+ :param string space-name: new name for space.
+
+ :return: nil
+ :except: If space-name does not exist.
+
+ .. code-block:: lua
+
+ tarantool> box.space.space55:rename('space56')
+ ---
+ ...
+ tarantool> box.space.space56:rename('space55')
+ ---
+ ...
+
+.. function:: box.space.space-name:replace{field-value [, field-value ...]}
+ box.space.space-name:put{field-value [, field-value ...]}
+
+ Insert a tuple into a space. If a tuple with the same primary key already
+ exists, ``box.space...:replace()`` replaces the existing tuple with a new
+ one. The syntax variants ``box.space...:replace()`` and
+ ``box.space...:put()`` have the same effect; the latter is sometimes used
+ to show that the effect is the converse of ``box.space...:get()``.
+
+ :param userdata space-name:
+ :param lua-value field-value(s): fields of the new tuple.
+
+ :return: the inserted tuple.
+ :rtype: tuple
+
+ :except: If a different tuple with the same unique-key
+ value already exists, returns ``ER_TUPLE_FOUND``.
+ (This would only happen if there was a secondary
+ index. By default secondary indexes are unique.)
+
+ Complexity Factors: Index size, Index type,
+ Number of indexes accessed, WAL settings.
+
+ .. code-block:: lua
+
+ tarantool> box.space.tester:replace{5000, 'New value'}
+
+.. function:: box.space.space-name:update(key, {{operator, field_no, value}, ...})
+
+ Update a tuple.
+
+ The ``update`` function supports operations on fields — assignment,
+ arithmetic (if the field is unsigned numeric), cutting and pasting
+ fragments of a field, deleting or inserting a field. Multiple
+ operations can be combined in a single update request, and in this
+ case they are performed atomically and sequentially. Each operation
+ requires specification of a field number. When multiple operations
+ are present, the field number for each operation is assumed to be
+ relative to the most recent state of the tuple, that is, as if all
+ previous operations in a multi-operation update have already been
+ applied. In other words, it is always safe to merge multiple update
+ invocations into a single invocation, with no change in semantics.
+
+ :param userdata space-name:
+ :param lua-value key: primary-key field values, must be passed as a Lua
+ table if key is multi-part
+ :param table {operator, field_no, value}: a group of arguments for each
+ operation, indicating what the operation is, what field the
+ operation will apply to, and what value will be applied. For
+ some operations the field number can be -1, meaning the last
+ field in the tuple. Possible operators are: “+†for addition,
+ “-†for subtraction, “&†for bitwise AND, “|†for bitwise OR,
+ “^†for bitwise exclusive OR (XOR), “:†for string splice, “!â€
+ for insert, “#†for delete. Thus in the instruction
+ ``s:update(44, {{'+',1,55},{'=',3,'x'}})`` the primary-key
+ value is 44, the operators are '+' and '=' meaning "add a value
+ to a field and then assign a value to a field", the first
+ affected field is field 1 and the value which will be added to
+ it is 55, the second affected field is field 3 and the value
+ which will be assigned to it is 'x'.
+
+ :return: the updated tuple.
+ :rtype: tuple
+
+ :except: it is illegal to modify a primary-key field.
+
+ Complexity Factors: Index size, Index type, number of indexes accessed, WAL
+ settings.
+
+ .. code-block:: lua
+
+ -- Assume that the initial state of the database is ...
+ -- tester has one tuple set and one primary key whose type is 'NUM'.
+ -- There is one tuple, with field[1] = 999 and field[2] = 'A'.
+
+ -- In the following update ...
+ -- The first argument is tester, that is, the affected space is tester
+ -- The second argument is 999, that is, the affected tuple is identified by
+ -- primary key value = 999
+ -- The third argument is '=', that is, there is one operation, assignment
+ -- to a field
+ -- The fourth argument is 2, that is, the affected field is field[2]
+ -- The fifth argument is 'B', that is, field[2] contents change to 'B'
+ -- Therefore, after the following update, field[1] = 999 and field[2] = 'B'.
+ box.space.tester:update(999, {{'=', 2, 'B'}})
+
+ -- In the following update, the arguments are the same, except that ...
+ -- the key is passed as a Lua table (inside braces). This is unnecessary
+ -- when the primary key has only one field, but would be necessary if the
+ -- primary key had more than one field.
+ -- Therefore, after the following update, field[1] = 999 and field[2] = 'B'
+ -- (no change).
+ box.space.tester:update({999}, {{'=', 2, 'B'}})
+
+ -- In the following update, the arguments are the same, except that ...
+ -- The fourth argument is 3, that is, the affected field is field[3].
+ -- It is okay that, until now, field[3] has not existed. It gets added.
+ -- Therefore, after the following update, field[1] = 999, field[2] = 'B',
+ -- field[3] = 1.
+ box.space.tester:update({999}, {{'=', 3, 1}})
+
+ -- In the following update, the arguments are the same, except that ...
+ -- The third argument is '+', that is, the operation is addition rather
+ -- than assignment.
+ -- Since field[3] previously contained 1, this means we're adding 1 to 1.
+ -- Therefore, after the following update, field[1] = 999, field[2] = 'B',
+ -- field[3] = 2.
+ box.space.tester:update({999}, {{'+', 3, 1}})
+
+ -- In the following update ...
+ -- The idea is to modify two fields at once.
+ -- The formats are '|' and '=', that is, there are two operations, OR and
+ -- assignment.
+ -- The fourth and fifth arguments mean that field[3] gets ORed with 1.
+ -- The seventh and eighth arguments mean that field[2] gets assigned 'C'.
+ -- Therefore, after the following update, field[1] = 999, field[2] = 'C',
+ -- field[3] = 3.
+ box.space.tester:update({999}, {{'|', 3, 1}, {'=', 2, 'C'}})
+
+ -- In the following update ...
+ -- The idea is to delete field[2], then subtract 3 from field[3], but ...
+ -- after the delete, there is a renumbering -- so field[3] becomes field[2]
+ -- before we subtract 3 from it, and that's why the seventh argument is 2 not 3.
+ -- Therefore, after the following update, field[1] = 999, field[2] = 0.
+ box.space.tester:update({999}, {{'-- ', 2, 1}, {'-', 2, 3}})
+
+ -- In the following update ...
+ -- We're making a long string so that splice will work in the next example.
+ -- Therefore, after the following update, field[1] = 999, field[2] = 'XYZ'.
+ box.space.tester:update({999}, {{'=', 2, 'XYZ'}})
+
+ -- In the following update ...
+ -- The third argument is ':', that is, this is the example of splice.
+ -- The fourth argument is 2 because the change will occur in field[2].
+ -- The fifth argument is 2 because deletion will begin with the second byte.
+ -- The sixth argument is 1 because the number of bytes to delete is 1.
+ -- The seventh argument is '!!' because '!!' is to be added at this position.
+ -- Therefore, after the following update, field[1] = 999, field[2] = 'X!!Z'.
+ box.space.tester:update({999}, {{':', 2, 2, 1, '!!'}})
+
+.. function:: box.space.space-name:delete{field-value [, field-value ...]}
+
+ Delete a tuple identified by a primary key.
+
+ :param userdata space-name:
+ :param lua-value field-value(s): values to match against keys
+ in the primary index.
+
+ :return: the deleted tuple
+ :rtype: tuple
+
+ Complexity Factors: Index size, Index type
+
+ .. code-block:: lua
+
+ tarantool> box.space.tester:delete(0)
+ ---
+ - [0, 'My first tuple']
+ ...
+ tarantool> box.space.tester:delete(0)
+ ---
+ ...
+ tarantool> box.space.tester:delete('a')
+ ---
+ - error: 'Supplied key type of part 0 does not match index part type:
+ expected NUM'
+ ...
+
+.. data:: space-name.id
+
+ Ordinal space number. Spaces can be referenced by either name or
+ number. Thus, if space 'tester' has id = 800, then
+ ``box.space.tester:insert{0}`` and ``box.space[800]:insert{0}``
+ are equivalent requests.
+
+ :rtype: number
+
+.. data:: space-name.enabled
+
+ Whether or not this space is enabled.
+ The value is false if there is no index.
+
+ :rtype: boolean
+
+.. data:: space-name.field_count
+
+ The required field count for all tuples in this space. The field_count
+ can be set initially with
+ ``box.schema.space.create... field_count = new-field-count-value ...``.
+ The default value is 0, which means there is no required field count.
+
+ :rtype: number
+
+.. data:: space-name.index[]
+
+ A container for all defined indexes. An index is a Lua object of type
+ :mod:`box.index` with methods to search tuples and iterate over them in
+ predefined order.
+
+ :rtype: table
+
+ .. code-block: lua
+
+ tarantool> box.space.tester.id
+ ---
+ - 512
+ ...
+ tarantool> box.space.tester.field_count
+ ---
+ - 0
+ ...
+ tarantool> box.space.tester.index.primary.type
+ ---
+ - TREE
+ ...
+
+.. function:: box.space.space-name:len()
+
+ .. NOTE::
+
+ The ``len()`` function is only applicable for the memtx storage engine.
+
+ :return: Number of tuples in the space.
+
+ .. code-block:: lua
+
+ tarantool> box.space.tester:len()
+ ---
+ - 2
+ ...
+
+.. function:: box.space.space-name:truncate()
+
+ Deletes all tuples.
+
+ Complexity Factors: Index size, Index type, Number of tuples accessed.
+
+ :return: nil
+
+ .. code-block:: lua
+
+ tarantool> box.space.tester:truncate()
+ ---
+ ...
+ tarantool> box.space.tester:len()
+ ---
+ - 0
+ ...
+
+.. function:: box.space.space-name:inc{field-value [, field-value ...]}
+
+ Increments a counter in a tuple whose primary key matches the
+ ``field-value(s)``. The field following the primary-key fields
+ will be the counter. If there is no tuple matching the
+ ``field-value(s)``, a new one is inserted with initial counter
+ value set to 1.
+
+ :param userdata space-name:
+ :param lua-value field-value(s): values which must match the primary key.
+ :return: the new counter value
+ :rtype: number
+
+ Complexity Factors: Index size, Index type, WAL settings.
+
+ .. code-block:: lua
+
+ tarantool> s = box.schema.space.create('forty_second_space')
+ ---
+ ...
+ tarantool> s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})
+ ---
+ ...
+ tarantool> box.space.forty_second_space:inc{1,'a'}
+ ---
+ - 1
+ ...
+ tarantool> box.space.forty_second_space:inc{1,'a'}
+ ---
+ - 2
+ ...
+
+.. function:: box.space.space-name:dec{field-value [, field-value ...]}
+
+ Decrements a counter in a tuple whose primary key matches the
+ ``field-value(s)``. The field following the primary-key fields
+ will be the counter. If there is no tuple matching the
+ ``field-value(s)``, a new one is not inserted. If the counter value drops
+ to zero, the tuple is deleted.
+
+ :param userdata space-name:
+ :param lua-value field-value(s): values which must match the primary key.
+ :return: the new counter value
+ :rtype: number
+
+ Complexity Factors: Index size, Index type, WAL settings.
+
+ .. code-block:: lua
+
+ tarantool> s = box.schema.space.create('space19')
+ ---
+ ...
+ tarantool> s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})
+ ---
+ ...
+ tarantool> box.space.space19:insert{1,'a',1000}
+ ---
+ - [1, 'a', 1000]
+ ...
+ tarantool> box.space.space19:dec{1,'a'}
+ ---
+ - 999
+ ...
+ tarantool> box.space.space19:dec{1,'a'}
+ ---
+ - 998
+ ...
+
+.. function:: box.space.space-name:auto_increment{field-value [, field-value ...]}
+
+ Insert a new tuple using an auto-increment primary key. The space specified
+ by space-name must have a NUM primary key index of type TREE. The
+ primary-key field will be incremented before the insert.
+
+ :param userdata space-name:
+ :param lua-value field-value(s): values for the tuple's fields,
+ other than the primary-key field.
+
+ :return: the inserted tuple.
+ :rtype: tuple
+
+ Complexity Factors: Index size, Index type,
+ Number of indexes accessed, WAL settings.
+
+ :except: index has wrong type or primary-key indexed field is not a number.
+
+ .. code-block:: lua
+
+ tarantool> box.space.tester:auto_increment{'Fld#1', 'Fld#2'}
+ ---
+ - [1, 'Fld#1', 'Fld#2']
+ ...
+ tarantool> box.space.tester:auto_increment{'Fld#3'}
+ ---
+ - [2, 'Fld#3']
+ ...
+
+.. function:: box.space.space-name:pairs()
+
+ A helper function to prepare for iterating over all tuples in a space.
+
+ :return: function which can be used in a for/end loop. Within the loop, a value is returned for each iteration.
+ :rtype: function, tuple
+
+ .. code-block:: lua
+
+ tarantool> s = box.schema.space.create('space33')
+ ---
+ ...
+ tarantool> -- index 'X' has default parts {1,'NUM'}
+ tarantool> s:create_index('X', {})
+ ---
+ ...
+ tarantool> s:insert{0,'Hello my '}; s:insert{1,'Lua world'}
+ ---
+ ...
+ tarantool> tmp = ''; for k, v in s:pairs() do tmp = tmp .. v[2] end
+ ---
+ ...
+ tarantool> tmp
+ ---
+ - Hello my Lua world
+ ...
+
+.. data:: _schema
+
+ ``_schema`` is a system tuple set. Its single tuple contains these fields:
+ ``'version', major-version-number, minor-version-number``.
+
+ The following function will display all fields in all tuples of ``_schema``.
+
+ .. code-block:: lua
+
+ console = require('console'); console.delimiter('!')
+ function example()
+ local ta = {}, i, line
+ for k, v in box.space._schema:pairs() do
+ i = 1
+ line = ''
+ while i <= #v do line = line .. v[i] .. ' ' i = i + 1 end
+ table.insert(ta, line)
+ end
+ return ta
+ end!
+ console.delimiter('')!
+
+
+ Here is what ``example()`` returns in a typical installation:
+
+ .. code-block:: lua
+
+ tarantool> example()
+ ---
+ - - 'cluster 1ec4e1f8-8f1b-4304-bb22-6c47ce0cf9c6 '
+ - 'max_id 520 '
+ - 'version 1 6 '
+ ...
+
+.. data:: _space
+
+ ``_space`` is a system tuple set. Its tuples contain these fields:
+ ``id, uid, space-name, engine, field_count, temporary``.
+
+ The following function will display all simple fields
+ in all tuples of ``_space``.
+
+ .. code-block:: lua
+
+ console = require('console'); console.delimiter('!')
+ function example()
+ local ta = {}, i, line
+ for k, v in box.space._space:pairs() do
+ i = 1
+ line = ''
+ while i <= #v do
+ if type(v[i]) ~= 'table' then
+ line = line .. v[i] .. ' '
+ end
+ i = i + 1
+ end
+ table.insert(ta, line)
+ end
+ return ta
+ end!
+ console.delimiter('')!
+
+ Here is what ``example()`` returns in a typical installation:
+
+ .. code-block:: lua
+
+ tarantool> example()
+ ---
+ - - '272 1 _schema memtx 0 '
+ - '280 1 _space memtx 0 '
+ - '288 1 _index memtx 0 '
+ - '296 1 _func memtx 0 '
+ - '304 1 _user memtx 0 '
+ - '312 1 _priv memtx 0 '
+ - '320 1 _cluster memtx 0 '
+ - '512 1 tester memtx 0 '
+ - '513 1 origin sophia 0 '
+ - '514 1 archive memtx 0 '
+ ...
+
+.. data:: _index
+
+ ``_index`` is a system tuple set. Its tuples contain these fields:
+ ``space-id index-id index-name index-type index-is-unique
+ index-field-count [tuple-field-no, tuple-field-type ...]``.
+
+ The following function will display all fields in all tuples of _index.
+
+ .. code-block:: lua
+
+ console = require('console'); console.delimiter('!')
+ function example()
+ local ta = {}, i, line
+ for k, v in box.space._index:pairs() do
+ i = 1
+ line = ''
+ while i <= #v do line = line .. v[i] .. ' ' i = i + 1 end
+ table.insert(ta, line)
+ end
+ return ta
+ end!
+ console.delimiter('')!
+
+ Here is what ``example()`` returns in a typical installation:
+
+ .. code-block:: lua
+
+ tarantool> example()
+ ---
+ - - '272 0 primary tree 1 1 0 str '
+ - '280 0 primary tree 1 1 0 num '
+ - '280 1 owner tree 0 1 1 num '
+ - '280 2 name tree 1 1 2 str '
+ - '288 0 primary tree 1 2 0 num 1 num '
+ - '288 2 name tree 1 2 0 num 2 str '
+ - '296 0 primary tree 1 1 0 num '
+ - '296 1 owner tree 0 1 1 num '
+ - '296 2 name tree 1 1 2 str '
+ - '304 0 primary tree 1 1 0 num '
+ - '304 1 owner tree 0 1 1 num '
+ - '304 2 name tree 1 1 2 str '
+ - '312 0 primary tree 1 3 1 num 2 str 3 num '
+ - '312 1 owner tree 0 1 0 num '
+ - '312 2 object tree 0 2 2 str 3 num '
+ - '320 0 primary tree 1 1 0 num '
+ - '320 1 uuid tree 1 1 1 str '
+ - '512 0 primary tree 1 1 0 num '
+ - '513 0 first tree 1 1 0 NUM '
+ - '514 0 first tree 1 1 0 STR '
+ ...
+
+.. data:: _user
+
+ ``_user`` is a new system tuple set for
+ support of the :ref:`authorization feature <box-authentication>`.
+
+.. data:: _priv
+
+ ``_priv`` is a new system tuple set for
+ support of the :ref:`authorization feature <box-authentication>`.
+
+.. data:: _cluster
+
+ ``_cluster`` is a new system tuple set
+ for support of the :ref:`replication feature <box-replication>`.
+
+=================================================
+ Example
+=================================================
+
+This function will illustrate how to look at all the spaces, and for each
+display: approximately how many tuples it contains, and the first field of
+its first tuple. The function uses Tarantool ``box.space`` functions ``len()``
+and ``pairs()``. The iteration through the spaces is coded as a scan of the
+``_space`` system tuple set, which contains metadata. The third field in
+``_space`` contains the space name, so the key instruction
+"``space_name = v[3]``" means "``space_name`` = the ``space_name`` field in
+the tuple of ``_space`` that we've just fetched with ``pairs()``". The function
+returns a table.
+
+.. code-block:: lua
+
+ console = require('console'); console.delimiter('!')
+ function example()
+ local tuple_count, space_name, line
+ local ta = {}
+ for k, v in box.space._space:pairs() do
+ space_name = v[3]
+ if box.space[space_name].index[0] ~= nil then
+ tuple_count = box.space[space_name]:len()
+ else
+ tuple_count = 0
+ end
+ line = space_name .. ' tuple_count =' .. tuple_count
+ if tuple_count > 0 then
+ for k1, v1 in box.space[space_name]:pairs() do
+ line = line .. '. first field in first tuple = ' .. v1[1]
+ break
+ end
+ end
+ table.insert(ta, line)
+ end
+ return ta
+ end!
+ console.delimiter('')!
+
+... And here is what happens when one invokes the function:
+
+.. code-block:: lua
+
+ tarantool> example()
+ ---
+ - - _schema tuple_count =3. first field in first tuple = cluster
+ - _space tuple_count =15. first field in first tuple = 272
+ - _index tuple_count =25. first field in first tuple = 272
+ - _func tuple_count =1. first field in first tuple = 1
+ - _user tuple_count =4. first field in first tuple = 0
+ - _priv tuple_count =6. first field in first tuple = 1
+ - _cluster tuple_count =1. first field in first tuple = 1
+ - tester tuple_count =2. first field in first tuple = 1
+ - origin tuple_count =0
+ - archive tuple_count =13. first field in first tuple = test_0@tarantool.org
+ - space55 tuple_count =0
+ - tmp tuple_count =0
+ - forty_second_space tuple_count =1. first field in first tuple = 1
+ ...
diff --git a/doc/sphinx/book/box/box_tuple.rst b/doc/sphinx/book/box/box_tuple.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b2912b5c504fd47ff682622743ca9a992119c469
--- /dev/null
+++ b/doc/sphinx/book/box/box_tuple.rst
@@ -0,0 +1,307 @@
+.. include:: ../../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `box.tuple`
+-------------------------------------------------------------------------------
+
+.. module:: box.tuple
+
+The ``box.tuple`` package provides read-only access for the ``box.tuple``
+userdata type. It allows, for a single tuple: selective retrieval of the field
+contents, retrieval of information about size, iteration over all the fields,
+and conversion to a Lua table.
+
+.. function:: new(value)
+
+ Construct a new tuple from either a scalar or a Lua table. Alternatively,
+ one can get new tuples from tarantool's SQL-like statements: SELECT,
+ INSERT, UPDATE, REPLACE, which can be regarded as statements that do
+ ``new()`` implicitly.
+
+ :param lua-value value: the value that will become the tuple contents.
+
+ :return: a new tuple
+ :rtype: tuple
+
+ In the following example, ``x`` will be a new table object containing one
+ tuple and ``t`` will be a new tuple object. Saying ``t`` returns the
+ entire tuple ``t``.
+
+ .. code-block:: lua
+
+ tarantool> x = box.space.tester:insert{33,tonumber('1'),tonumber64('2')}:totable()
+ ---
+ ...
+ tarantool> t = box.tuple.new({'abc', 'def', 'ghi', 'abc'})
+ ---
+ ...
+ tarantool> t
+ ---
+ - ['abc', 'def', 'ghi', 'abc']
+ ...
+
+.. class:: tuple
+
+ .. method:: __len()
+
+ The ``#`` operator in Lua means "return count of components". So,
+ if ``t`` is a tuple instance, ``#t`` will return the number of fields.
+
+ :rtype: number
+
+ In the following example, a tuple named ``t`` is created and then the
+ number of fields in ``t`` is returned.
+
+ .. code-block:: lua
+
+ tarantool> t = box.tuple.new({'Fld#1','Fld#2','Fld#3','Fld#4'})
+ ---
+ ...
+ tarantool> #t
+ ---
+ - 4
+ ...
+
+ .. method:: bsize()
+
+ If ``t`` is a tuple instance, ``t:bsize()`` will return the number of
+ bytes in the tuple. It is useful to check this number when making
+ changes to data, because there is a fixed maximum: one megabyte. Every
+ field has one or more "length" bytes preceding the actual contents, so
+ ``bsize()`` returns a value which is slightly greater than the sum of
+ the lengths of the contents.
+
+ :return: number of bytes
+ :rtype: number
+
+ In the following example, a tuple named ``t`` is created which has
+ three fields, and for each field it takes one byte to store the length
+ and three bytes to store the contents, and a bit for overhead, so
+ ``bsize()`` returns ``3*(1+3)+1``.
+
+ .. code-block:: lua
+
+ tarantool> t = box.tuple.new({'aaa','bbb','ccc'})
+ ---
+ ...
+ tarantool> t:bsize()
+ ---
+ - 13
+ ...
+
+ .. method:: __index(key)
+
+ If ``t`` is a tuple instance, ``t[field-number]`` will return the field
+ numbered field-number in the tuple. The first field is ``t[1]``.
+
+ :return: field value.
+ :rtype: lua-value
+
+ In the following example, a tuple named ``t`` is created and then the
+ second field in ``t`` is returned.
+
+ .. code-block:: lua
+
+ tarantool> t = box.tuple.new({'Fld#1','Fld#2','Fld#3','Fld#4'})
+ ---
+ ...
+ tarantool> t[2]
+ ---
+ - Fld#2
+ ...
+
+ .. method:: find([field-number,] field-value)
+ findall([field-number,] field-value)
+
+ If ``t`` is a tuple instance, ``t:find(field-value)`` will return the
+ number of the first field in ``t`` that matches the field value),
+ and ``t:findall(field-value [, field-value ...])`` will return numbers
+ of all fields in ``t`` that match the field value. Optionally one can
+ put a numeric argument ``field-number`` before the search-value to
+ indicate “start searching at field number ``field-number``.â€
+
+ :return: the number of the field in the tuple.
+ :rtype: number
+
+ In the following example, a tuple named ``t`` is created and then: the
+ number of the first field in ``t`` which matches 'a' is returned, then
+ the numbers of all the fields in ``t`` which match 'a' are returned,
+ then the numbers of all the fields in t which match 'a' and are at or
+ fter the second field are returned.
+
+ .. code-block:: lua
+
+ tarantool> t = box.tuple.new({'a','b','c','a'})
+ ---
+ ...
+ tarantool> t:find('a')
+ ---
+ - 1
+ ...
+ tarantool> t:findall('a')
+ ---
+ - 1
+ - 4
+ ...
+ tarantool> t:findall(2, 'a')
+ ---
+ - 4
+ ...
+
+ .. method:: transform(start-field-number, fields-to-remove [, field-value ...])
+
+ If ``t`` is a tuple instance, ``t:transform(start-field-number,fields-to-remove)``
+ will return a tuple where, starting from field ``start-field-number``,
+ a number of fields (``fields-to-remove``) are removed. Optionally one
+ can add more arguments after ``fields-to-remove`` to indicate new
+ values that will replace what was removed.
+
+ :param integer start-field-number: base 1, may be negative
+ :param integer fields-to-remove:
+ :param lua-value field-value(s):
+ :return: tuple
+ :rtype: tuple
+
+ In the following example, a tuple named ``t`` is created and then,
+ starting from the second field, two fields are removed but one new
+ one is added, then the result is returned.
+
+ .. code-block:: lua
+
+ tarantool> t = box.tuple.new({'Fld#1','Fld#2','Fld#3','Fld#4','Fld#5'})
+ ---
+ ...
+ tarantool> t:transform(2,2,'x')
+ ---
+ - ['Fld#1', 'x', 'Fld#4', 'Fld#5']
+ ...
+
+ .. method:: unpack()
+
+ If ``t`` is a tuple instance, ``t:unpack(n)`` will return all fields.
+
+ :return: field(s) from the tuple.
+ :rtype: lua-value(s)
+
+ In the following example, a tuple named ``t`` is created and then all
+ its fields are selected, then the result is returned.
+
+ .. code-block:: lua
+
+ tarantool> t = box.tuple.new({'Fld#1','Fld#2','Fld#3','Fld#4','Fld#5'})
+ ---
+ ...
+ tarantool> t:unpack()
+ ---
+ - Fld#1
+ - Fld#2
+ - Fld#3
+ - Fld#4
+ - Fld#5
+ ...
+
+ .. method:: pairs()
+
+ In Lua, ``lua-table-value:pairs()`` is a method which returns:
+ ``function``, ``lua-table-value``, ``nil``. Tarantool has extended
+ this so that ``tuple-value:pairs()`` returns: ``function``,
+ ``tuple-value``, ``nil``. It is useful for Lua iterators, because Lua
+ iterators traverse a value's components until an end marker is reached.
+
+ :return: function, tuple-value, nil
+ :rtype: function, lua-value, nil
+
+ In the following example, a tuple named ``t`` is created and then all
+ its fields are selected using a Lua for-end loop.
+
+ .. code-block:: lua
+
+ tarantool> t = box.tuple.new({'Fld#1','Fld#2','Fld#3','Fld#4','Fld#5'})
+ ---
+ ...
+ tarantool> tmp = ''; for k, v in t:pairs() do tmp = tmp .. v end
+ ---
+ ...
+ tarantool> tmp
+ ---
+ - Fld#1Fld#2Fld#3Fld#4Fld#5
+ ...
+
+ .. method:: update({{format, field_number, value}...})
+
+ Update a tuple.
+
+ This function updates a tuple which is not in a space. Compare the function
+ ``box.space.space-name:update{key, format, {field_number, value}...)``,
+ which updates a tuple in a space.
+
+ Parameters: briefly: format indicates the type of update operation such as '``=``'
+ for 'assign new value', ``field_number`` indicates the field number to change such
+ as 2 for field number 2, value indicates the string which operates on the field such
+ as 'B' for a new assignable value = 'B'.
+
+ For details: see the description for ``format``, ``field_number``, and ``value`` in
+ the section ``box.space.space-name:update{key, format, {field_number, value}...)``.
+
+ :return: new tuple
+ :rtype: tuple
+
+ In the following example, a tuple named ``t`` is created and then its second field is
+ updated to equal 'B'.
+
+ .. code-block:: lua
+
+ tarantool> t = box.tuple.new({'Fld#1','Fld#2','Fld#3','Fld#4','Fld#5'})
+ ---
+ ...
+ tarantool> t:update({{'=',2,'B'}})
+ ---
+ - ['Fld#1', 'B', 'Fld#3', 'Fld#4', 'Fld#5']
+ ...
+
+===========================================================
+ Example
+===========================================================
+
+This function will illustrate how to convert tuples to/from Lua tables and
+lists of scalars:
+
+.. code-block:: lua
+
+ tuple = box.tuple.new({scalar1, scalar2, ... scalar_n}) -- scalars to tuple
+ lua_table = {tuple:unpack()} -- tuple to Lua table
+ scalar1, scalar2, ... scalar_n = tuple:unpack() -- tuple to scalars
+ tuple = box.tuple.new(lua_table) -- Lua table to tuple
+
+Then it will find the field that contains 'b', remove that field from the tuple,
+and display how many bytes remain in the tuple. The function uses Tarantool
+``box.tuple`` functions ``new()``, ``unpack()``, ``find()``, ``transform()``,
+``bsize()``.
+
+.. code-block:: lua
+
+ console = require('console'); console.delimiter('!')
+ function example()
+ local tuple1, tuple2, lua_table_1, scalar1, scalar2, scalar3, field_number
+ tuple1 = box.tuple.new({'a', 'b', 'c'})
+ luatable1 = {tuple1:unpack()}
+ scalar1, scalar2, scalar3 = tuple1:unpack()
+ tuple2 = box.tuple.new(luatable1)
+ field_number = tuple2:find('b')
+ tuple2 = tuple2:transform(field_number, 1)
+ return 'tuple2 = ' , tuple2 , ' # of bytes = ' , tuple2:bsize()
+ end!
+ console.delimiter('')!
+
+... And here is what happens when one invokes the function:
+
+.. code-block:: yaml
+
+ tarantool> example()
+ ---
+ - 'tuple2 = '
+ - ['a', 'c']
+ - ' # of bytes = '
+ - 5
+ ...
diff --git a/doc/sphinx/book/box/index.rst b/doc/sphinx/book/box/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..a096874172a4f29b6d20d442d5002d0470a35331
--- /dev/null
+++ b/doc/sphinx/book/box/index.rst
@@ -0,0 +1,90 @@
+-------------------------------------------------------------------------------
+ Database
+-------------------------------------------------------------------------------
+
+As well as executing Lua chunks or defining their own functions, users can exploit
+the Tarantool server's storage functionality with the ``box`` Lua library.
+
+=====================================================================
+ Packages of the box library
+=====================================================================
+
+The contents of the box library can be inspected at runtime with ``box``, with
+no arguments. The packages inside the box library are:
+
+.. toctree::
+ :maxdepth: 1
+
+ box_schema
+ box_tuple
+ box_space
+ box_index
+ box_session
+ box_error
+ box_introspection
+ net_box
+ admin
+ atomic
+ authentication
+ limitations
+ triggers
+
+Every package contains one or more Lua functions. A few packages contain
+members as well as functions. The functions allow data definition (create
+alter drop), data manipulation (insert delete update select replace), and
+introspection (inspecting contents of spaces, accessing server configuration).
+
+
+.. container:: table
+
+ **Complexity Factors that may affect data
+ manipulation functions in the box library**
+
+ +-------------------+-----------------------------------------------------+
+ | Index size | The number of index keys is the same as the number |
+ | | of tuples in the data set. For a TREE index, if |
+ | | there are more keys then the lookup time will be |
+ | | greater, although of course the effect is not |
+ | | linear. For a HASH index, if there are more keys |
+ | | then there is more RAM use, but the number of |
+ | | low-level steps tends to remain constant. |
+ +-------------------+-----------------------------------------------------+
+ | Index type | Typically a HASH index is faster than a TREE index |
+ | | if the number of tuples in the tuple set is greater |
+ | | than one. |
+ +-------------------+-----------------------------------------------------+
+ | Number of indexes | Ordinarily only one index is accessed to retrieve |
+ | accessed | one tuple. But to update the tuple, there must be N |
+ | | accesses if the tuple set has N different indexes. |
+ +-------------------+-----------------------------------------------------+
+ | Number of tuples | A few requests, for example select, can retrieve |
+ | accessed | multiple tuples. This factor is usually less |
+ | | important than the others. |
+ +-------------------+-----------------------------------------------------+
+ | WAL settings | The important setting for the write-ahead log is |
+ | | :ref:`wal_mode <wal_mode>`. If the setting causes |
+ | | no writing or |
+ | | delayed writing, this factor is unimportant. If the |
+ | | settings causes every data-change request to wait |
+ | | for writing to finish on a slow device, this factor |
+ | | is more important than all the others. |
+ +-------------------+-----------------------------------------------------+
+
+In the discussion of each data-manipulation function there will be a note about
+which Complexity Factors might affect the function's resource usage.
+
+=====================================================================
+ The two storage engines: memtx and sophia
+=====================================================================
+
+A storage engine is a set of very-low-level routines which actually store and
+retrieve tuple values. Tarantool offers a choice of two storage engines: memtx
+(the in-memory storage engine) and sophia (the on-disk storage engine).
+To specify that the engine should be sophia, add a clause: ``engine = 'sophia'``.
+The manual concentrates on memtx because it is the default and has been around
+longer. But sophia is a working key-value engine and will especially appeal to
+users who like to see data go directly to disk, so that recovery time might be
+shorter and database size might be larger. For architectural explanations and
+benchmarks, see sphia.org. On the other hand, sophia lacks some functions and
+options that are available with memtx. Where that is the case, the relevant
+description will contain the words "only applicable for the memtx storage engine".
diff --git a/doc/sphinx/book/box/limitations.rst b/doc/sphinx/book/box/limitations.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b429c59940b2f85265d50dbdc7b78f1275c467d2
--- /dev/null
+++ b/doc/sphinx/book/box/limitations.rst
@@ -0,0 +1,50 @@
+.. include:: ../../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Limitations
+-------------------------------------------------------------------------------
+
+Number of fields in an index
+ For BITSET indexes, the maximum is 1. For TREE or HASH indexes, the maximum
+ is 255 (``box.schema.INDEX_PART_MAX``). For RTREE indexes, the number of
+ fields must be either 2 or 4.
+
+Number of indexes in a space
+ 10 (``box.schema.INDEX_MAX``).
+
+Number of fields in a tuple
+ The theoretical maximum is 2147483647 (``box.schema.FIELD_MAX``). The
+ practical maximum is whatever is specified by the space's field_count
+ member, or the maximum tuple length.
+
+Number of spaces
+ The theoretical maximum is 2147483647 (``box.schema.SPACE_MAX``).
+
+Number of connections
+ The practical limit is the number of file descriptors that one can set
+ with the operating system.
+
+Space size
+ The total maximum size for all spaces is in effect set by
+ :ref:`slab_alloc_arena <slab_alloc_arena>`, which in turn
+ is limited by the total available memory.
+
+Update operations count
+ The maximum number of operations that can be in a single update
+ is 4000 (``BOX_UPDATE_OP_CNT_MAX``).
+
+Number of users and roles
+ 32 ().
+
+Length of an index name or space name or user name
+ 32 (``box.schema.NAME_MAX``).
+
+Limitations which are only applicable for the sophia storage engine
+ The maximum number of fields in an index is always 1, that is, multi-part
+ indexes are not supported. The maximum number of indexes in a space is
+ always 1, that is, secondary indexes are not supported. Indexes must be
+ unique, that is, the options type=HASH or type=RTREE or type=BITSET are
+ not supported. Indexes must be unique, that is, the option unique=false
+ is not supported. The ``alter()``, ``len()``, and ``count()`` functions
+ are not supported.
diff --git a/doc/sphinx/book/box/net_box.rst b/doc/sphinx/book/box/net_box.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f0d6bb0ee8d4041b1e9be188532b998b7e5e11d9
--- /dev/null
+++ b/doc/sphinx/book/box/net_box.rst
@@ -0,0 +1,237 @@
+.. include:: ../../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `net.box`
+-------------------------------------------------------------------------------
+
+The ``net.box`` package contains connectors to remote database systems. One
+variant, ``box.net.sql``, is for connecting to MySQL or MariaDB or PostgreSQL —
+that variant is the subject of the :ref:`SQL DBMS plugins <dbms-plugins>` appendix.
+In this section the subject is the built-in variant, ``box.net``. This is for
+connecting to tarantool servers via a network.
+
+Call ``require('net.box')`` to get a ``net.box`` object, which will be called
+``net_box`` for examples in this section. Call ``net_box.new()`` to connect and
+get a connection object, which will be called conn for examples in this section.
+Call the other ``net.box()`` routines, passing ``conn:``, to execute requests on
+the remote box. Call :func:`conn:close <socket_object.close>` to disconnect.
+
+All `net.box`` methods are fiber-safe, that is, it is safe to share and use the
+same connection object across multiple concurrent fibers. In fact, it's perhaps
+the best programming practice with Tarantool. When multiple fibers use the same
+connection, all requests are pipelined through the same network socket, but each
+fiber gets back a correct response. Reducing the number of active sockets lowers
+the overhead of system calls and increases the overall server performance. There
+are, however, cases when a single connection is not enough — for example when it's
+necessary to prioritize requests or to use different authentication ids.
+
+.. module:: net_box
+
+.. function:: new(host, port [, {params}])
+
+ Create a new connection. The connection is established on demand, at the
+ time of the first request. It is re-established automatically after a
+ disconnect. The returned conn object supports methods for making remote
+ requests, such as select, update or delete.
+
+ For the local tarantool server there is a pre-created always-established
+ connection object named net_box.self. Its purpose is to make polymorphic
+ use of the ``net_box`` API easier. Therefore ``conn = net_box:new('localhost', 3301)``
+ can be replaced by ``conn = net_box.self``. However, there is an important
+ difference between the embedded connection and a remote one. With the
+ embedded connection, requests which do not modify data do not yield.
+ When using a remote connection, any request can yield, and local database
+ state may have changed by the time it returns.
+
+ :param string host:
+ :param number port:
+ :param boolean wait_connect:
+ :param string user:
+ :param string password:
+ :return: conn object
+ :rtype: userdata
+
+ .. code-block:: lua
+
+ conn = net_box:new('localhost', 3301)
+ conn = net_box:new('127.0.0.1', box.cfg.listen, {
+ wait_connect = false,
+ user = 'guest',
+ password = ''
+ })
+
+.. class:: connection
+
+ .. method:: ping()
+
+ Execute a PING command.
+
+ :return: true on success, false on error
+ :rtype: boolean
+
+ .. code-block:: lua
+
+ net_box.self:ping()
+
+ .. method:: wait_connected([timeout])
+
+ Wait for connection to be active or closed.
+
+ :param number timeout:
+ :return: true when connected, false on failure.
+ :rtype: boolean
+
+ .. code-block:: lua
+
+ net_box.self:wait_connected().
+
+ .. method:: close()
+
+ Close a connection.
+
+ Connection objects are garbage collected just like any other objects in Lua, so
+ an explicit destruction is not mandatory. However, since close() is a system
+ call, it is good programming practice to close a connection explicitly when it
+ is no longer needed, to avoid lengthy stalls of the garbage collector.
+
+ .. code-block:: lua
+
+ conn:close()
+
+ .. method:: connection.space.<space-name>:select{field-value, ...}
+
+ ``conn.space.space-name:select{...}`` is the remote-call equivalent
+ of the local call ``box.space.space-name:select{...}``. Please note
+ this difference: a local ``box.space.space-name:select{...}`` does
+ not yield, but a remote ``conn.space.space-name:select{...}`` call
+ does yield, so local data may change while a remote
+ ``conn.space.space-name:select{...}`` is running.
+
+ .. method:: connection.space.<space-name>:insert{field-value, ...}
+
+ ``conn.space.space-name:insert(...)`` is the remote-call equivalent
+ of the local call ``box.space.space-name:insert(...)``.
+
+ .. method:: connection.space.<space-name>:replace{field-value, ...}
+
+ ``conn.space.space-name:replace(...)`` is the remote-call equivalent
+ of the local call ``box.space.space-name:replace(...)``.
+
+ .. method:: connection.space.<space-name>:update{field-value, ...}
+
+ ``conn.space.space-name:update(...)`` is the remote-call equivalent
+ of the local call ``box.space.space-name:update(...)``.
+
+ .. method:: connection.space.<space-name>:delete{field-value, ...}
+
+ ``conn.space.space-name:delete(...)`` is the remote-call equivalent
+ of the local call ``box.space.space-name:delete(...)``.
+
+ .. method:: call(function-name [, arguments])
+
+ ``conn:call('func', '1', '2', '3')`` is the remote-call equivalent of
+ ``func('1', '2', '3')``. That is, ``conn:call`` is a remote
+ stored-procedure call.
+
+ .. code-block:: lua
+
+ conn:call('function5').
+
+ .. method:: timeout(timeout)
+
+ ``timeout(...)`` is a wrapper which sets a timeout for the request that
+ follows it.
+
+ .. code-block:: lua
+
+ conn:timeout(0.5).space.tester:update({1}, {{'=', 2, 15}}).
+
+ All remote calls support execution timeouts. Using a wrapper object makes
+ the remote connection API compatible with the local one, removing the need
+ for a separate timeout argument, which the local version would ignore. Once
+ a request is sent, it cannot be revoked from the remote server even if a
+ timeout expires: the timeout expiration only aborts the wait for the remote
+ server response, not the request itself.
+
+===========================================================
+ Example
+===========================================================
+
+This example will work with the sandbox configuration described in the preface.
+That is, there is a space named tester with a numeric primary key. Assume that
+the database is nearly empty. Assume that the tarantool server is running on
+``localhost 127.0.0.1:3301``.
+
+.. code-block:: lua
+
+ tarantool> box.schema.user.grant('guest', 'read,write,execute', 'universe')
+ ---
+ ...
+ tarantool> console = require('console'); console.delimiter('!')
+ ---
+ ...
+ tarantool> net_box = require('net.box')!
+ ---
+ ...
+ tarantool> function example()
+ > if net_box.self:ping() then
+ > table.insert(ta, 'self:ping() succeeded')
+ > table.insert(ta, ' (no surprise -- self connection is pre-established)')
+ > end
+ > if box.cfg.listen == '3301' then
+ > table.insert(ta,'The local server listen address = 3301')
+ > else
+ > table.insert(ta, 'The local server listen address is not 3301')
+ > table.insert(ta, '( (maybe box.cfg{...listen="3301"...} was not stated)')
+ > table.insert(ta, '( (so connect will fail)')
+ > end
+ > conn = net_box:new('127.0.0.1', 3301)
+ > conn.space.tester:delete{800}
+ > table.insert(ta, 'conn delete done on tester.')
+ > conn.space.tester:insert{800, 'data'}
+ > table.insert(ta, 'conn insert done on tester, index 0')
+ > table.insert(ta, ' primary key value = 800.')
+ > wtuple = conn.space.tester:select{800}
+ > table.insert(ta, 'conn select done on tester, index 0')
+ > table.insert(ta, ' number of fields = ' .. #wtuple)
+ > conn.space.tester:delete{800}
+ > table.insert(ta, 'conn delete done on tester')
+ > conn.space.tester:replace{800, 'New data', 'Extra data'}
+ > table.insert(ta, 'conn:replace done on tester')
+ > conn:timeout(0.5).space.tester:update({800}, {{'=', 2, 'Fld#1'}})
+ > table.insert(ta, 'conn update done on tester')
+ > conn:close()
+ > table.insert(ta, 'conn close done')
+ > end!
+ ---
+ ...
+ tarantool> console.delimiter('')!
+ ---
+ ...
+ tarantool> ta = {}
+ ---
+ ...
+ tarantool> example()
+ ---
+ ...
+ tarantool> ta
+ ---
+ - - self:ping() succeeded
+ - ' (no surprise -- self connection is pre-established)'
+ - The local server listen address = 3301
+ - conn delete done on tester.
+ - conn insert done on tester, index 0
+ - ' primary key value = 800.'
+ - conn select done on tester, index 0
+ - ' number of fields = 1'
+ - conn delete done on tester
+ - conn:replace done on tester
+ - conn update done on tester
+ - conn close done
+ ...
+ tarantool> box.space.tester:select{800} -- Prove that the update succeeded.
+ ---
+ - [800, 'Fld#1', 'Extra data']
+ ...
+
diff --git a/doc/sphinx/book/box/triggers.rst b/doc/sphinx/book/box/triggers.rst
new file mode 100644
index 0000000000000000000000000000000000000000..da039f234ffcb429abd4d7e1aa7a25d8980059f3
--- /dev/null
+++ b/doc/sphinx/book/box/triggers.rst
@@ -0,0 +1,188 @@
+.. include:: ../../directives.rst
+.. highlight:: lua
+
+.. _box-triggers:
+
+-------------------------------------------------------------------------------
+ Triggers
+-------------------------------------------------------------------------------
+
+Triggers, also known as callbacks, are functions which the server executes when
+certain events happen. Currently the two types of triggers are `connection triggers`_,
+which are executed when a session begins or ends, and `replace triggers`_ which are
+for database events,
+
+All triggers have the following characteristics.
+
+* They associate a function with an `event`. The request to "define a trigger"
+ consists of passing the name of the trigger's function to one of the
+ "on_``event-name...``" functions: ``on_connect()``, ``on_disconnect()``,
+ or ``on_replace()``.
+* They are `defined by any user`. There are no privilege requirements for defining
+ triggers.
+* They are called `after` the event. They are not called if the event ends
+ prematurely due to an error.
+* They are in `server memory`. They are not stored in the database. Triggers
+ disappear when the server is shut down. If there is a requirement to make
+ them permanent, then the function definitions and trigger settings should
+ be part of an initialization script.
+* They have `low overhead`. If a trigger is not defined, then the overhead is
+ minimal: merely a pointer dereference and check. If a trigger is defined,
+ then its overhead is equivalent to the overhead of calling a stored procedure.
+* They can be `multiple` for one event. Triggers are executed in the reverse
+ order that they were defined in.
+* They must work `within the event context`. If the function contains requests
+ which normally could not occur immediately after the event but before the
+ return from the event, effects are undefined. For example, defining a trigger
+ function as ``os.exit()`` or ``box.rollback()`` would be bringing in requests
+ outside the event context.
+* They are `replaceable`. The request to "redefine a trigger" consists of passing
+ the names of a new trigger function and an old trigger function to one of the
+ "on_``event-name...``" functions.
+
+===========================================================
+ Connection triggers
+===========================================================
+
+.. function:: box.session.on_connect(trigger-function [, old-trigger-function-name])
+
+ Define a trigger for execution when a new session is created due to an event
+ such as :func:`console.connect`. The trigger function will be the first thing
+ executed after a new session is created. If the trigger fails by raising an
+ error, the error is sent to the client and the connection is closed.
+
+ :param function trigger-function: function which will become the trigger function
+ :param function old-trigger-function: existing trigger function which will be replaced by trigger-function
+ :return: nil
+
+ If the parameters are (nil, old-trigger-function), then the old trigger is deleted.
+
+ .. code-block:: lua
+
+ function f ()
+ x = x + 1
+ end
+ box.session.on_connect(f)
+
+ .. WARNING::
+
+ If a trigger always results in an error, it may become impossible to
+ connect to the server to reset it.
+
+.. function:: box.sessio.non_disconnect(trigger-function [, old-trigger-function])
+
+ Define a trigger for execution after a client has disconnected. If the trigger
+ function causes 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 box.session.id.
+
+ :param function trigger-function: function which will become the trigger function
+ :param function old-trigger-function: existing trigger function which will be replaced by trigger-function
+ :return: nil
+
+ .. code-block:: lua
+
+ function f ()
+ x = x + 1
+ end
+ box.session.on_disconnect(f)
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ After the following series of requests, the server will write a message
+ using the :mod:`log` package whenever any user connects or disconnects.
+
+.. code-block:: lua
+
+ function log_connect ()
+ local log = require('log')
+ local m = 'Connection. user=' .. box.session.user() .. ' id=' .. box.session.id()
+ log.info(m)
+ end
+ function log_disconnect ()
+ local log = require('log')
+ local m = 'Disconnection. user=' .. box.session.user() .. ' id=' .. box.session.id()
+ log.info(m)
+ end
+ box.session.on_connect(log_connect)
+ box.session.on_disconnect(log_disconnect)
+
+Here is what might appear in the log file in a typical installation:
+
+.. code-block:: lua
+
+ 2014-12-15 13:21:34.444 [11360] main/103/iproto I>
+ Connection. user=guest id=3
+ 2014-12-15 13:22:19.289 [11360] main/103/iproto I>
+ Disconnection. user=guest id=3
+
+
+===========================================================
+ Replace triggers
+===========================================================
+
+.. function:: box.space.<space-name>:on_replace(trigger-function [, old-trigger-function])
+
+ Create a "``replace trigger``". The ``function-name`` will be executed whenever
+ a ``replace()`` or ``insert()`` or ``update()`` or ``delete()`` happens to a
+ tuple in ``<space-name>``.
+
+ :param function trigger-function: function which will become the trigger function
+ :param function old-trigger-function: existing trigger function which will be replaced by trigger-function
+ :return: nil
+
+ .. code-block:: lua
+
+ function f ()
+ x = x + 1
+ end
+ box.space.X:on_replace(f)
+
+.. function:: box.space.<space-name>:run_triggers(true|false)
+
+ At the time that a trigger is defined, it is automatically enabled - that
+ is, it will be executed. Replace triggers can be disabled with
+ ``box.space.space-name:run_triggers(false)`` and re-enabled with
+ ``box.space.space-name:run_triggers(true)``.
+
+ :return: nil
+
+ .. code-block:: lua
+
+ box.space.X:run_triggers(false)
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following series of requests will create a space, create an index, create
+a function which increments a counter, create a trigger, do two inserts, drop
+the space, and display the counter value - which is 2, because the function
+is executed once after each insert.
+
+.. code-block:: lua
+
+ s = box.schema.space.create('space53')
+ s:create_index('primary', {parts = {1, 'NUM'}})
+ function replace_trigger() replace_counter = replace_counter + 1 end
+ s:on_replace(replace_trigger)
+ replace_counter = 0
+ t = s:insert{1, 'First replace'}
+ t = s:insert{2, 'Second replace'}
+ s:drop()
+ replace_counter
+
+The following series of requests will associate an existing function named F
+with an existing space named T, associate the function a second time with the
+same space (so it will be called twice), disable all triggers of T, and destroy
+each trigger by replacing with ``nil``.
+
+.. code-block:: lua
+
+ box.space.T:on_replace(F)
+ box.space.T:on_replace(F)
+ box.space.T:run_triggers(false)
+ box.space.T:on_replace(nil, F)
+ box.space.T:on_replace(nil, F)
diff --git a/doc/sphinx/book/configuration.rst b/doc/sphinx/book/configuration.rst
new file mode 100644
index 0000000000000000000000000000000000000000..28dd27bf19b1c35bd2f41838e05001924483d725
--- /dev/null
+++ b/doc/sphinx/book/configuration.rst
@@ -0,0 +1,485 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+.. _box-configuration:
+
+-------------------------------------------------------------------------------
+ Configuration reference
+-------------------------------------------------------------------------------
+
+This chapter provides a reference of options which can be set on the command
+line or in an initialization file.
+
+Tarantool is started by entering the command:
+
+.. program:: tarantool
+
+.. code-block:: bash
+
+ $ tarantool
+ OR
+ $ tarantool <options>
+ OR
+ $ tarantool <lua-initialization-file> [arguments]
+
+=====================================================================
+ Command options
+=====================================================================
+
+.. option:: -h, --help
+
+ Print an annotated list of all available options and exit.
+
+.. option:: -V, --version
+
+ Print product name and version, for example:
+
+ .. code-block:: bash
+
+ $ ./tarantool --version
+ Tarantool 1.6.3-439-g7e1011b
+ Target: Linux-x86_64-Debug
+ ...
+
+ In this example:
+ “Tarantool†is the name of the reusable asynchronous networking
+ programming framework.
+
+ The 3-number version follows the standard ``<major>-<minor>-<patch>``
+ scheme, in which ``<major>`` number is changed only rarely, ``<minor>`` is
+ incremented for each new milestone and indicates possible incompatible
+ changes, and ``<patch>`` stands for the number of bug fix releases made after
+ the start of the milestone. For non-released versions only, there may be a
+ commit number and commit SHA1 to indicate how much this particular build has
+ diverged from the last release.
+
+ “Target†is the platform tarantool was built on. Some platform-specific details
+ may follow this line.
+
+ .. NOTE::
+
+ Tarantool uses `git describe`_ to produce its version id, and this id
+ can be used at any time to check out the corresponding source from our
+ `git repository`_.
+
+.. _git describe: http://www.kernel.org/pub/software/scm/git/docs/git-describe.html
+.. _git repository: http://github.com/tarantool/tarantool.git
+
+
+.. _URI:
+
+=====================================================================
+ URI
+=====================================================================
+
+Some configuration parameters and some functions depend on a URI, or
+"Universal Resource Identifier". The URI string format is similar to the
+`generic syntax for a URI schema`_. So it may contain (in order) a user name
+for login, a password, a host name or host IP address, and a port number. Only
+the port number is always mandatory. The password is mandatory if the user
+name is specified, unless the user name is 'guest'. So, formally, the URI
+syntax is ``[host:]port`` or ``[username:password@]host:port``
+If host is omitted, then 'localhost' is assumed.
+If username:password is omitted, then 'guest' is assumed. Some examples:
+
+.. _generic syntax for a URI schema: http://en.wikipedia.org/wiki/URI_scheme#Generic_syntax
+
+.. container:: table
+
+ +-----------------------------+------------------------------+
+ | URI fragment | Example |
+ +=============================+==============================+
+ | port | 3301 |
+ +-----------------------------+------------------------------+
+ | host:port | 127.0.0.1:3301 |
+ +-----------------------------+------------------------------+
+ | username:password@host:port | notguest:sesame@mail.ru:3301 |
+ +-----------------------------+------------------------------+
+
+In certain circumstances a Unix socket may be used where a URI is required.
+
+=====================================================================
+ Initialization file
+=====================================================================
+
+If the command to start Tarantool includes ``<lua-initialization-file>``, then
+Tarantool begins by invoking the Lua program in the file, which by convention
+may have the name "``script.lua``". The Lua program may get further arguments
+from the command line or may use operating-system functions, such as ``getenv()``.
+The Lua program almost always begins by invoking ``box.cfg()``, if the database
+server will be used or if ports need to be opened. For example, suppose
+``script.lua`` contains the lines
+
+.. code-block:: lua
+
+ #!/usr/bin/env tarantool
+ box.cfg{
+ listen = os.getenv("LISTEN_URI"),
+ slab_alloc_arena = 0.1,
+ pid_file = "tarantool.pid",
+ rows_per_wal = 50
+ }
+ print('Starting ',arg[1])
+
+and suppose the environment variable LISTEN_URI contains 3301,
+and suppose the command line is ``~/tarantool/src/tarantool script.lua ARG``.
+Then the screen might look like this:
+
+.. code-block:: lua
+
+ $ export LISTEN_URI=3301
+ $ ~/tarantool/src/tarantool script.lua ARG
+ ... main/101/script.lua C> version 1.6.3-439-g7e1011b
+ ... main/101/script.lua C> log level 5
+ ... main/101/script.lua I> mapping 107374184 bytes for a shared arena...
+ ... main/101/script.lua I> recovery start
+ ... main/101/script.lua I> recovering from `./00000000000000000000.snap'
+ ... main/101/script.lua I> primary: bound to 0.0.0.0:3301
+ ... main/102/leave_local_hot_standby I> ready to accept requests
+ Starting ARG
+ ... main C> entering the event loop
+
+.. _local_hot_standby:
+.. _replication_port:
+.. _slab_alloc_arena:
+.. _replication_source:
+.. _admin_port:
+.. _snap_dir:
+.. _wal_dir:
+.. _wal_mode:
+.. _snapshot daemon:
+.. _logger:
+
+=====================================================================
+ Configuration parameters
+=====================================================================
+
+Configuration parameters have the form ``box.cfg{ key = value [, key = value ...]}``.
+Since ``box.cfg`` may contain many configuration parameters and since some of the
+parameters (such as directory addresses) are semi-permanent, it's best to keep
+``box.cfg`` in a Lua file. Typically this Lua file is the initialization file
+which is specified on the tarantool command line.
+
+Most configuration parameters are for allocating resources, opening ports, and
+specifying database behavior. All parameters are optional. A few parameters are
+dynamic, that is, they can be changed at runtime by calling ``box.cfg{}``
+a second time.
+
+To see all the non-null parameters, say ``box.cfg`` (no parentheses). To see a
+particular parameter, for example the listen address, say ``box.cfg.listen``.
+
+The following tables describe all parameters for basic operation, for storage,
+for binary logging and snapshots, for replication, for networking, and for logging.
+
+.. container:: table
+
+ **Basic parameters**
+
+ +-------------------+-----------+----------+----------+-------------------------------------------------+
+ | Name | Type | Default | Dynamic? | Description |
+ +===================+===========+==========+==========+=================================================+
+ | username | string | null | no | UNIX user name to switch to after start. |
+ +-------------------+-----------+----------+----------+-------------------------------------------------+
+ | work_dir | string | null | no | A directory where database working files will |
+ | | | | | be stored. The server switches to work_dir with |
+ | | | | | chdir(2) after start. Can be relative to the |
+ | | | | | current directory. If not specified, defaults |
+ | | | | | to the current directory. |
+ +-------------------+-----------+----------+----------+-------------------------------------------------+
+ | wal_dir | string | "." | no | A directory where write-ahead log (.xlog) files |
+ | | | | | are stored. Can be relative to work_dir. Most |
+ | | | | | commonly used so that snapshot files and |
+ | | | | | write-ahead log files can be stored on separate |
+ | | | | | disks. If not specified, defaults to work_dir. |
+ +-------------------+-----------+----------+----------+-------------------------------------------------+
+ | snap_dir | string | "." | no | A directory where snapshot (.snap) files will |
+ | | | | | be stored. Can be relative to work_dir. If not |
+ | | | | | specified, defaults to work_dir. See also |
+ | | | | | :ref:`wal_dir`. |
+ +-------------------+-----------+----------+----------+-------------------------------------------------+
+ | sophia_dir | string | "sophia" | no | A directory where sophia files will be stored. |
+ | | | | | Can be relative to work_dir. If not specified, |
+ | | | | | defaults to ``work_dir/sophia``. |
+ +-------------------+-----------+----------+----------+-------------------------------------------------+
+ | coredump | boolean | "false" | no | Deprecated. Do not use. |
+ +-------------------+-----------+----------+----------+-------------------------------------------------+
+ | listen | integer | "null" | yes | The read/write data port number or `URI`_ |
+ | | or string | | | (Universal Resource Identifier) string. Has no |
+ | | | | | default value, so must be specified if |
+ | | | | | connections will occur from remote clients that |
+ | | | | | do not use "admin address" (the administrative |
+ | | | | | host and port). Note: a replica also binds to |
+ | | | | | this port, and accepts connections, but these |
+ | | | | | connections can only serve reads until the |
+ | | | | | replica becomes a master. A typical value is |
+ | | | | | 3301. The listen parameter may also be set |
+ | | | | | for `local hot standby`_. |
+ +-------------------+-----------+----------+----------+-------------------------------------------------+
+ | pid_file | string | "null" | no | Store the process id in this file. Can be |
+ | | | | | relative to work_dir. A typical value is |
+ | | | | | "tarantool.pid". |
+ +-------------------+-----------+----------+----------+-------------------------------------------------+
+ | custom_proc_title | string | "null" | no | Inject the given string into |
+ | | | | | :doc:`app_b_proctitle` (what's shown in the |
+ | | | | | COMMAND column for ps and top commands). |
+ +-------------------+-----------+----------+----------+-------------------------------------------------+
+ | background | boolean | false | no | Run the server as a background task. The logger |
+ | | | | | and pid_file parameters must be non-null for |
+ | | | | | this to work. |
+ | | | | | |
+ +-------------------+-----------+----------+----------+-------------------------------------------------+
+
+ .. NOTE::
+
+ **custom_proc_title**
+
+ For example, ordinarily ps shows the Tarantool server process thus:
+
+ .. code-block:: lua
+
+ $ ps -ef | grep tarantool
+ 1000 22364 2778 0 09:14 pts/0 00:00:00 tarantool: running
+ 1000 22394 22364 0 09:14 pts/0 00:00:00 tarantool: spawner
+ tarantool: primary pri: 3301 adm: 3313
+
+ But if the configuration parameters include
+ ``custom_proc_title='sessions'`` then the output looks like:
+
+ .. code-block:: lua
+
+ $ ps -ef | grep tarantool
+ 1000 22364 2778 0 09:14 pts/0 00:00:00 tarantool: running@sessions
+ 1000 22394 22364 0 09:14 pts/0 00:00:00 tarantool: spawner@sessions
+ tarantool: primary pri: 3301 adm: 3313
+
+ **Configuring the storage**
+
+ +--------------------------+-----------+----------+----------+-------------------------------------------------+
+ | Name | Type | Default | Dynamic? | Description |
+ +==========================+===========+==========+==========+=================================================+
+ | slab_alloc_arena | float | null | no | How much memory Tarantool allocates to actually |
+ | | | | | store tuples, in gigabytes. When the limit is |
+ | | | | | reached, INSERT or UPDATE requests begin |
+ | | | | | failing with error :ref:`ER_MEMORY_ISSUE`. While|
+ | | | | | the server does not go beyond the defined limit |
+ | | | | | to allocate tuples, there is additional memory |
+ | | | | | used to store indexes and connection |
+ | | | | | information. Depending on actual configuration |
+ | | | | | and workload, Tarantool can consume up to 20% |
+ | | | | | more than the limit set here. |
+ +--------------------------+-----------+----------+----------+-------------------------------------------------+
+ | slab_alloc_minimal | integer | 64 | no | Size of the smallest allocation unit. It can be |
+ | | | | | tuned down if most of the tuples are very small |
+ +--------------------------+-----------+----------+----------+-------------------------------------------------+
+ | slab_alloc_maximal | integer | 1048576 | no | Size of the largest allocation unit. It can be |
+ | | | | | tuned down up if it is necessary to store large |
+ | | | | | tuples. |
+ +--------------------------+-----------+----------+----------+-------------------------------------------------+
+ | slab_alloc_factor | float | 2.0 | no | Use slab_alloc_factor as the multiplier for |
+ | | | | | computing the sizes of memory chunks that |
+ | | | | | tuples are stored in. A lower value may result |
+ | | | | | in less wasted memory depending on the total |
+ | | | | | amount of memory available and the distribution |
+ | | | | | of item sizes. |
+ +--------------------------+-----------+----------+----------+-------------------------------------------------+
+ | sophia | table | (see the | no | The default sophia configuration can be changed |
+ | | | note) | | with |
+ | | | | | |
+ | | | | | .. code-block:: lua |
+ | | | | | |
+ | | | | | sophia = { |
+ | | | | | page_size = number, |
+ | | | | | threads = number, |
+ | | | | | node_size = number, |
+ | | | | | memory_limit = number |
+ | | | | | } |
+ | | | | | |
+ | | | | | This method may change in the future. |
+ +--------------------------+-----------+----------+----------+-------------------------------------------------+
+
+ **Snapshot daemon**
+
+ +--------------------+-----------+----------+----------+-----------------------------------------------------+
+ | Name | Type | Default | Dynamic? | Description |
+ +====================+===========+==========+==========+=====================================================+
+ | snapshot_period | integer | 0 | yes | The interval between actions by the snapshot |
+ | | | | | daemon, in seconds. The snapshot daemon is a |
+ | | | | | fiber which is constantly running. If |
+ | | | | | ``snapshot_period`` is set to a value greater |
+ | | | | | than zero, then the snapshot daemon will call |
+ | | | | | :func:`box.snapshot` every ``snapshot_period`` |
+ | | | | | seconds, creating a new snapshot file each |
+ | | | | | time. For example, |
+ | | | | | ``box.cfg{snapshot_period=3600}`` will cause |
+ | | | | | the snapshot daemon to create a new database |
+ | | | | | snapshot once per hour. |
+ +--------------------+-----------+----------+----------+-----------------------------------------------------+
+ | snapshot_count | integer | 6 | yes | The maximum number of snapshots that the |
+ | | | | | snapshot daemon maintains. For example, |
+ | | | | | ``box.cfg{snapshot_period=3600, snapshot_count=10}``|
+ | | | | | will cause the snapshot daemon to create a new |
+ | | | | | snapshot each hour until it has created ten |
+ | | | | | snapshots. After that, it will remove the |
+ | | | | | oldest snapshot (and any associated |
+ | | | | | write-ahead-log files) after creating a new |
+ | | | | | one. If ``snapshot_count`` equals zero, then the |
+ | | | | | snapshot daemon does not remove old snapshots. |
+ +--------------------+-----------+----------+----------+-----------------------------------------------------+
+
+ **Snapshot daemon**
+
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+ | Name | Type | Default | Dynamic? | Description |
+ +======================+===========+==========+==========+=====================================================+
+ | panic_on_snap_error | boolean | true | no | If there is an error while reading the snapshot |
+ | | | | | file (at server start), abort. |
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+ | panic_on_wal_error | boolean | true | no | If there is an error while reading a write-ahead |
+ | | | | | log file (at server start or to relay to a replica),|
+ | | | | | abort. |
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+ | rows_per_val | integer | 500000 | no | How many log records to store in a single |
+ | | | | | write-ahead log file. When this limit is reached, |
+ | | | | | Tarantool creates another WAL file named |
+ | | | | | ``<first-lsn-in-wal>.xlog`` This can be useful for |
+ | | | | | simple rsync-based backups. |
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+ | snap_io_rate_limit | float | null | **yes** | Reduce the throttling effect of |
+ | | | | | :func:`box.snapshot()` on INSERT/UPDATE/DELETE |
+ | | | | | performance by setting a limit on how many |
+ | | | | | megabytes per second it can write to disk. The same |
+ | | | | | can be achieved by splitting `wal_dir`_ and |
+ | | | | | :ref:`snap_dir` locations and moving snapshots to a |
+ | | | | | separate disk. |
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+ | wal_mode | string | "write" | **yes** | Specify fiber-WAL-disk synchronization mode as: |
+ | | | | | ``none``: write-ahead log is not maintained; |
+ | | | | | ``write``: fibers wait for their data to be written |
+ | | | | | to the write-ahead log (no fsync(2)); |
+ | | | | | ``fsync``: fibers wait for their data, fsync(2) |
+ | | | | | follows each write(2); |
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+ | wal_dir_rescan_delay | float | 0.1 | no | Number of seconds between periodic scans of the |
+ | | | | | write-ahead-log file directory, when checking for |
+ | | | | | changes to write-ahead-log files for the sake of |
+ | | | | | replication or local hot standby. |
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+
+ **Replication**
+
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+ | Name | Type | Default | Dynamic? | Description |
+ +======================+===========+==========+==========+=====================================================+
+ | replication_source | string | null | **yes** | If replication_source is not an empty string, the |
+ | | | | | server is considered to be a Tarantool replica. The |
+ | | | | | replica server will try to connect to the master |
+ | | | | | which replication_source specifies with a `URI`_ |
+ | | | | | (Universal Resource Identifier), for example |
+ | | | | | '``konstantin:secret_password@tarantool.org:3301``' |
+ | | | | | The default user name is 'guest'. |
+ | | | | | The replication_source parameter is dynamic, |
+ | | | | | that is, to enter master mode, simply set |
+ | | | | | replication_source to an empty string and issue |
+ | | | | | "``box.cfg{replication_source=new-value}``" |
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+
+ **Networking**
+
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+ | Name | Type | Default | Dynamic? | Description |
+ +======================+===========+==========+==========+=====================================================+
+ | io_collect_interval | float | null | **yes** | The server will sleep for io_collect_interval |
+ | | | | | seconds between iterations of the event loop. Can |
+ | | | | | be used to reduce CPU load in deployments in which |
+ | | | | | the number of client connections is large, but |
+ | | | | | requests are not so frequent (for example, each |
+ | | | | | connection issues just a handful of requests per |
+ | | | | | second). |
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+ | readahead | integer | 16320 | **yes** | The size of the read-ahead buffer associated with a |
+ | | | | | client connection. The larger the buffer, the more |
+ | | | | | memory an active connection consumes and the more |
+ | | | | | requests can be read from the operating system |
+ | | | | | buffer in a single system call. The rule of thumb |
+ | | | | | is to make sure the buffer can contain at least a |
+ | | | | | few dozen requests. Therefore, if a typical tuple |
+ | | | | | in a request is large, e.g. a few kilobytes or even |
+ | | | | | megabytes, the read-ahead buffer size should be |
+ | | | | | increased. If batched request processing is not |
+ | | | | | used, it's prudent to leave this setting at its |
+ | | | | | default. |
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+
+ **Logging**
+
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+ | Name | Type | Default | Dynamic? | Description |
+ +======================+===========+==========+==========+=====================================================+
+ | log_level | integer | true | **yes** | How verbose the logging is. There are six log |
+ | | | | | verbosity classes: 1 -- SYSERROR, 2 -- ERROR, |
+ | | | | | 3 -- CRITICAL, 4 -- WARNING, 5 -- INFO, 6 -- DEBUG. |
+ | | | | | By setting log_level, one can enable logging of all |
+ | | | | | classes below or equal to the given level. |
+ | | | | | Tarantool prints its logs to the standard error |
+ | | | | | stream by default, but this can be changed with |
+ | | | | | the "logger" configuration parameter. |
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+ | logger | string | "null" | no | By default, the log is sent to the standard error |
+ | | | | | stream (``stderr``). If logger is specified, the |
+ | | | | | log is sent to the file named in the string. |
+ | | | | | Example setting: ``logger = 'tarantool.log'`` (this |
+ | | | | | will open tarantool.log for output on the server's |
+ | | | | | default directory). |
+ | | | | | If logger string begins with a pipe, for example |
+ | | | | | '| cronolog tarantool.log', the program specified in|
+ | | | | | the option is executed at server start and all log |
+ | | | | | When logging to a file, tarantool reopens the log |
+ | | | | | on SIGHUP. When log is a program, it's pid is saved |
+ | | | | | in logger_pid variable of package log. You need to |
+ | | | | | send it a signal to rotate logs. |
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+ | logger_nonblock | boolean | true | no | If logger_nonblock equals true, Tarantool does not |
+ | | | | | block on the log file descriptor when it's not |
+ | | | | | ready for write, and drops the message instead. If |
+ | | | | | log_level is high, and a lot of messages go to the |
+ | | | | | log file, setting logger_nonblock to true may |
+ | | | | | improve logging performance at the cost of some log |
+ | | | | | messages getting lost. |
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+ | too_long_threshold | float | 0.5 | **yes** | If processing a request takes longer than the given |
+ | | | | | value (in seconds), warn about it in the log. Has |
+ | | | | | effect only if log_level is less than or equal to |
+ | | | | | 4 (WARNING). |
+ +----------------------+-----------+----------+----------+-----------------------------------------------------+
+
+=====================================================================
+ Local hot standby
+=====================================================================
+
+Local hot standby is a feature which provides a simple form of failover without
+replication. To initiate it, start a second instance of the Tarantool server on
+the same computer with the same :func:`box.cfg` configuration settings -
+including the same directories and same non-null URIs. A warning should appear with a
+message like
+
+.. code-block:: lua
+
+ W> primary: [URI] is already in use, will retry binding after [n] seconds
+
+This is fine. It means that the second instance is ready to take over if the
+first instance goes down.
+
+The expectation is that there will be two instances of the server using the
+same configuration. The first one to start will be the "primary" instance.
+The second one to start will be the "standby" instance. The standby instance
+will initialize and will try to connect on listen address,
+but will fail because the primary instance has already taken it. So the
+standby instance goes into a loop, reading the write ahead log which the
+primary instance is writing (so the two instances are always in synch),
+and trying to connect on the port. If the primary instance goes down for any
+reason, the port will become free so the standby instance will succeed in
+connecting, and will become the primary instance. Thus there is no noticeable
+downtime if the primary instance goes down.
+
+If this ``local_hot_standby`` feature is being used, then ``wal_mode`` should
+not be equal to "none".
diff --git a/doc/sphinx/book/connectors/__go.rst b/doc/sphinx/book/connectors/__go.rst
new file mode 100644
index 0000000000000000000000000000000000000000..dfd8763bca44d8ac045dc63de2ac40a3fd24f99a
--- /dev/null
+++ b/doc/sphinx/book/connectors/__go.rst
@@ -0,0 +1,5 @@
+=====================================================================
+ Go
+=====================================================================
+
+Please see https://github.com/mialinx/go-tarantool-1.6.
diff --git a/doc/sphinx/book/connectors/__java.rst b/doc/sphinx/book/connectors/__java.rst
new file mode 100644
index 0000000000000000000000000000000000000000..a5ecb509895577aa687b4b410a61ca090110fefc
--- /dev/null
+++ b/doc/sphinx/book/connectors/__java.rst
@@ -0,0 +1,5 @@
+=====================================================================
+ Java
+=====================================================================
+
+Please, see http://dgreenru.github.io/tarantool-java/.
diff --git a/doc/sphinx/book/connectors/__perl.rst b/doc/sphinx/book/connectors/__perl.rst
new file mode 100644
index 0000000000000000000000000000000000000000..2ba37653b235f464fbfbcee9285304509341cece
--- /dev/null
+++ b/doc/sphinx/book/connectors/__perl.rst
@@ -0,0 +1,61 @@
+=====================================================================
+ Perl
+=====================================================================
+
+The most commonly used Perl driver is `DR::Tarantool`_. It is not supplied as
+part of the Tarantool repository; it must be installed separately. The most
+common way to install it is with `CPAN, the Comprehensive Perl Archive Network`_.
+`DR::Tarantool`_ requires other modules which should be installed first. For
+example, on Ubuntu, the installation could look like this:
+
+.. code-block:: bash
+
+ sudo cpan install AnyEvent
+ sudo cpan install Devel::GlobalDestruction
+ sudo cpan install Coro
+ sudo cpan install Test::Pod
+ sudo cpan install Test::Spelling
+ sudo cpan install PAR::Dist
+ sudo cpan install List::MoreUtils
+ sudo cpan install DR::Tarantool
+
+Here is a complete Perl program that inserts [99999,'BB'] into space[999] via
+the Perl API. Before trying to run, check that the server is listening and
+that ``examples`` exists, as `described earlier`_. To run, paste the code into
+a file named example.pl and say ``perl example.pl``. The program will connect
+using an application-specific definition of the space. The program will open a
+socket connection with the tarantool server at localhost:3301, then send an
+INSERT request, then — if all is well — end without displaying any messages.
+If tarantool is not running on localhost with listen address = 3301, the program
+will print “Connection refusedâ€.
+
+.. code-block:: perl
+
+ #!/usr/bin/perl
+ use DR::Tarantool ':constant', 'tarantool';
+ use DR::Tarantool ':all';
+ use DR::Tarantool::MsgPack::SyncClient;
+
+ my $tnt = DR::Tarantool::MsgPack::SyncClient->connect(
+ host => '127.0.0.1', # look for tarantool on localhost
+ port => 3301, # assume tarantool listen address = default
+ user => 'guest', # username. one could also say 'password=>...'
+
+ spaces => {
+ 999 => { # definition of space[999] ...
+ name => 'examples', # space[999] name = 'examples'
+ default_type => 'STR', # space[999] field type is 'STR' if undefined
+ fields => [ { # definition of space[512].fields ...
+ name => 'field1', type => 'NUM' } ], # space[999].field[1] name='field1',type='NUM'
+ indexes => { # definition of space[999] indexes ...
+ 0 => {
+ name => 'primary', fields => [ 'field1' ] } } } } );
+
+ $tnt->insert('examples' => [ 99999, 'BB' ]);
+
+The example program only shows one command and does not show all that's
+necessary for good practice. For that, please see `DR::Tarantool`_ CPAN repository.
+
+.. _DR::Tarantool: http://search.cpan.org/~unera/DR-Tarantool/
+.. _CPAN, the Comprehensive Perl Archive Network: https://en.wikipedia.org/wiki/Cpan
+.. _described earlier: https://en.wikipedia.org/wiki/Cpan
diff --git a/doc/sphinx/book/connectors/__php.rst b/doc/sphinx/book/connectors/__php.rst
new file mode 100644
index 0000000000000000000000000000000000000000..396bc417cdf4d85fc845a089ac4b99db874fecc9
--- /dev/null
+++ b/doc/sphinx/book/connectors/__php.rst
@@ -0,0 +1,63 @@
+=====================================================================
+ PHP
+=====================================================================
+
+The PHP driver is `tarantool-php`_. It is not supplied as part of the Tarantool
+repository; it must be installed separately. It can be installed with git. It
+requires other modules which should be installed first. For example, on Ubuntu,
+the installation could look like this:
+
+.. code-block:: bash
+
+ sudo apt-get install php5-cli
+ sudo apt-get install php5-dev
+ sudo apt-get install php-pear
+ cd ~
+ git clone https://github.com/tarantool/tarantool-php.git
+ cd tarantool-php
+ phpize
+ ./configure
+ make
+ # make install is optional
+
+At this point there is a file named ``~/tarantool-php/modules/tarantool.so``.
+PHP will only find it if the PHP initialization file ``php.ini`` contains a
+line like ``extension=./tarantool.so``. So copy ``tarantool.so`` to the working
+directory and tell PHP where to find the ``php.ini`` file that contains that line ...
+
+.. code-block:: bash
+
+ cd ~
+ cp ./tarantool-php/modules/tarantool.so .
+ export PHP_INI_SCAN_DIR=~/tarantool-php/test/shared
+
+Here is a complete PHP program that inserts [99999,'BB'] into a space named 'examples'
+via the PHP API. Before trying to run, check that the server is listening and that
+``examples`` exists, as `described earlier`_. To run, paste the code into a file named
+example.php and say ``php example.php``. The program will open a socket connection with
+the tarantool server at localhost:3301, then send an INSERT request, then — if all is
+well — print "Insert succeeded". If the tuple already exists, the program will print
+“Duplicate key exists in unique index 0â€.
+
+.. code-block:: php
+
+ <?php
+ $tarantool = new Tarantool("localhost", 3301);
+ try {
+ $tarantool->insert("examples", array(99999, "BB"));
+ print "Insert succeeded\n";
+ }
+ catch (Exception $e) {
+ echo "Exception: ", $e->getMessage(), "\n";
+ }
+ ?>
+
+After running the example, it is good practice to delete the file ./tarantool.so,
+since it is only compatible with PHP and its existence could confuse non-PHP
+applications.
+
+The example program only shows one command and does not show all that's necessary
+for good practice. For that, please see `tarantool-php`_ project at GitHub.
+
+.. _described earlier: https://en.wikipedia.org/wiki/Cpan
+.. _tarantool-php: https://github.com/tarantool/tarantool-php
diff --git a/doc/sphinx/book/connectors/__python.rst b/doc/sphinx/book/connectors/__python.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b39d64cdd2344b9205542592c7721ce01d35799f
--- /dev/null
+++ b/doc/sphinx/book/connectors/__python.rst
@@ -0,0 +1,33 @@
+=====================================================================
+ Python
+=====================================================================
+
+Here is a complete Python program that inserts ``[99999,'Value','Value']`` into
+space ``examples`` via the high-level Python API.
+
+.. code-block:: python
+
+ #!/usr/bin/python
+ from tarantool import Connection
+
+ c = Connection("127.0.0.1", 3301)
+ result = c.insert("examples",(99999,'Value', 'Value'))
+ print result
+
+To prepare, paste the code into a file named example.py and install
+tarantool-python with either ``pip install tarantool\>0.4`` to install
+in ``/usr`` (requires **root** privilege) or ``pip install tarantool\>0.4 --user``
+to install in ``~`` i.e. user's default directory. Before trying to run,
+check that the server is listening and that examples exists, as `described earlier`_.
+To run the program, say ``python example.py``. The program will connect
+to the server, will send the request, and will not throw an exception if
+all went well. If the tuple already exists, the program will throw
+``DatabaseException(“Duplicate key exists in unique indexâ€)``.
+
+The example program only shows one request and does not show all that's
+necessary for good practice. For that, see http://github.com/tarantool/tarantool-python.
+For an example of a Python API for `Queue managers on Tarantool`_, see
+https://github.com/tarantool/tarantool-queue-python.
+
+.. _described earlier: https://en.wikipedia.org/wiki/Cpan
+.. _Queue managers on Tarantool: https://github.com/tarantool/queue
diff --git a/doc/sphinx/book/connectors/index.rst b/doc/sphinx/book/connectors/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..5f4898701f8d3c98ae3ec9d12997dd5b75d3d221
--- /dev/null
+++ b/doc/sphinx/book/connectors/index.rst
@@ -0,0 +1,100 @@
+.. include:: ../../directives.rst
+.. highlight:: lua
+
+.. _box-connectors:
+
+-------------------------------------------------------------------------------
+ Connectors
+-------------------------------------------------------------------------------
+
+This chapter documents APIs for various programming languages.
+
+=====================================================================
+ Protocol
+=====================================================================
+
+Tarantool protocol was designed with a focus on asynchronous I/O and easy integration
+with proxies. Each client request starts with a variable-length binary header,
+containing request id, request type, server id, log sequence number, and so on.
+
+The mandatory length, present in request header simplifies client or proxy I/O.
+A response to a request is sent to the client as soon as it is ready. It always
+carries in its header the same type and id as in the request. The id makes it
+possible to match a request to a response, even if the latter arrived out of order.
+
+Unless implementing a client driver, one needn't concern oneself with the
+complications of the binary protocol. `Language-specific drivers`_ provide a
+friendly way to store domain language data structures in Tarantool. A complete
+description of the binary protocol is maintained in annotated Backus-Naur form
+in the source tree: please see :ref:`iproto protocol`.
+
+====================================================================
+ Packet example
+====================================================================
+
+The Tarantool API exists so that a client program can send a request packet to
+the server, and receive a response. Here is an example of a what the client
+would send for ``box.space[513]:insert{'A', 'BB'}``. The BNF description of the
+components is in file :ref:`iproto protocol`.
+
+.. _Language-specific drivers: `Connectors`_
+
+.. container:: table
+
+ +---------------------------------+---------+---------+---------+---------+
+ | Component | Byte #0 | Byte #1 | Byte #2 | Byte #3 |
+ +=================================+=========+=========+=========+=========+
+ | code for insert | 2 | | | |
+ +---------------------------------+---------+---------+---------+---------+
+ | rest of header | ... | ... | ... | ... |
+ +---------------------------------+---------+---------+---------+---------+
+ | 2-digit number: space id | cd | 02 | 01 | |
+ +---------------------------------+---------+---------+---------+---------+
+ | code for tuple | 21 | | | |
+ +---------------------------------+---------+---------+---------+---------+
+ | 1-digit number: field count = 2 | 92 | | | |
+ +---------------------------------+---------+---------+---------+---------+
+ | 1-character string: field[1] | a1 | 41 | | |
+ +---------------------------------+---------+---------+---------+---------+
+ | 2-character string: field[2] | a2 | 42 | 42 | |
+ +---------------------------------+---------+---------+---------+---------+
+
+Now, one could send that packet to the tarantool server, and interpret the response
+(:ref:`iproto protocol` has a description of the packet format for responses as
+well as requests). But it would be easier, and less error-prone, if one could invoke
+a routine that formats the packet according to typed parameters. Something like
+``response=tarantool_routine("insert",513,"A","B");``. And that is why APIs exist for
+drivers for Perl, Python, PHP, and so on.
+
+====================================================================
+ Setting up the server for connector examples
+====================================================================
+
+This chapter has examples that show how to connect to the Tarantool server via
+the Perl, PHP, and Python connectors. The examples contain hard code that will
+work if and only if the server (tarantool) is running on localhost (127.0.0.1)
+and is listening on port 3301 (``box.cfg.listen='3301'``) and space 'examples'
+has id = 999 (``box.space.tester.id = 999``), and space 'examples' has a
+primary-key index for a numeric field (``box.space[999].index[0].parts[1].type
+= "NUM"``) and user 'guest' has privileges for reading and writing.
+
+It is easy to meet all the conditions by starting the server and executing this
+script:
+
+.. code-block:: lua
+
+ box.cfg{listen=3301}
+ box.schema.space.create('examples',{id=999})
+ box.space.examples:create_index('primary', {type = 'hash', parts = {1, 'NUM'}})
+ box.schema.user.grant('guest','read,write','space','examples')
+ box.schema.user.grant('guest','read','space','_space')
+
+.. include:: __java.rst
+
+.. include:: __go.rst
+
+.. include:: __perl.rst
+
+.. include:: __php.rst
+
+.. include:: __python.rst
diff --git a/doc/sphinx/book/index.rst b/doc/sphinx/book/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..73e28acbb9972b50ebff8e2d736a0b0420646142
--- /dev/null
+++ b/doc/sphinx/book/index.rst
@@ -0,0 +1,17 @@
+-------------------------------------------------------------------------------
+ User Guide
+-------------------------------------------------------------------------------
+
+.. toctree::
+ :maxdepth: 2
+
+ intro
+ box/index
+ replication/index
+ configuration
+ administration
+ connectors/index
+ app_a_errcodes
+ app_b_proctitle
+ app_c_lua_tutorial
+ app_d_plugins
diff --git a/doc/sphinx/book/intro.rst b/doc/sphinx/book/intro.rst
new file mode 100644
index 0000000000000000000000000000000000000000..64a093dda00359c67a00bb45afc7b5839437c76b
--- /dev/null
+++ b/doc/sphinx/book/intro.rst
@@ -0,0 +1,109 @@
+-------------------------------------------------------------------------------
+ Intro
+-------------------------------------------------------------------------------
+
+===============================================================================
+ Tarantool: an overview
+===============================================================================
+
+Tarantool is a Lua application server integrated with a database management system.
+It has a "fiber" model which means that many applications can run simultaneously on
+a single thread, while the Tarantool server can run multiple threads for input-output
+and background maintenance. It integrates the LuaJIT -- "Just In Time" -- Lua compiler,
+Lua libraries for most common applications, and the Tarantool Database Server which
+is an established NoSQL DBMS. Thus it serves all the purposes that have made node.js
+and Twisted popular in other environments, with the additional twist that it has a
+data persistence level.
+
+The code is free. The open-source license is *`BSD license`_*. The supported platforms
+are GNU/Linux, Mac OS and FreeBSD.
+
+Tarantool database is deeply integrated with the application server. On
+the surface, Tarantool is simply a Lua language interpreter, and the database
+is one of many built-in Lua packages. But the exposed database API not only
+allows to persist Lua objects to disk, but to manage object collections, create
+or drop secondary keys, configure and monitor replication, perform controlled
+fail-over, execute Lua code upon database events.
+Remote database instances are accessible transparently via remote
+procedure invocation API.
+
+Unlike popular application development frameworks based on a "reactor" pattern,
+networking in server-side Lua is sequential, yet very efficient, as it is built
+on top of the **cooperative multitasking** environment that Tarantool itself
+uses. A key feature is that the functions can access and modify databases
+atomically. Thus some developers look at it as a DBMS with a popular stored
+procedure language, while others look at it as a replacement for multiple
+components of multi-tier Web application architectures. Performance is a few
+thousand transactions per second on a laptop, scalable upwards or outwards to
+server farms.
+
+Tarantool data storage is built around **storage engine** concept, when
+different sets of algorithms and data structures can be used for different
+collections of objects. Two storage engines are built-in: in-memory engine,
+which represents 100% of data and indexes in RAM, and a two-level B-tree,
+for data sets exceeding the amount of available RAM from 10 to up to 1000
+times. All storage engines in Tarantool support transactions and
+replication by using a common **write ahead log**. This ensures consistency
+and crash safety of the persistent state. The logging subsystem supports
+group commit.
+
+**Tarantool in-memory engine is lock-free**. Instead of the operating system's
+concurrency primitives, such as mutexes, it uses cooperative multitasking to
+handle thousands of connections simultaneously. There is a fixed number of
+independent execution threads. The threads do not share state. Instead they
+exchange data using low-overhead message queues. While this approach limits the
+number of cores that the server will use, it removes competition for the memory
+bus and ensures peak scalability of memory access and network throughput. CPU
+utilization of a typical highly-loaded Tarantool server is under 10%.
+
+**Tarantool disk-based engine** is a fusion of ideas from modern filesystems,
+log-structured merge trees and classical B-trees. All data is organized
+into **branches**, each branch is represented by a file on disk. Branch
+size is a configuration option and normally is around 64MB. Each
+branch is a collection of pages, serving different purposes. Pages
+in a fully merged branch contain non-overlapping ranges of keys. A branch
+can be partially merged if there were a lot of changes in its key range
+recently. In that case some pages represent new keys and values in the
+branch. The disk-based engine is append only: new data never overwrites
+the old.
+
+Unlike most NoSQL DBMSs, Tarantool supports **secondary index keys** as well as
+primary keys, and **multi-part index keys**. The possible index types are HASH,
+TREE, BITSET, and RTREE.
+
+Tarantool supports **asynchronous replication**, locally or to remote hosts.
+The replication architecture can be **master-master**, that is, many nodes may
+both handle the loads and receive what others have handled, for the same data
+sets.
+
+Tarantool's creator and biggest user is `Mail.Ru`_, the largest internet
+company in Russia, with 30 million users, 25 million emails per day, and a web
+site whose Alexa global rank is in the `top 40`_ worldwide. Tarantool services
+Mail.Ru's hottest data, such as the session data of online users, the
+properties of online applications, the caches of the underlying data, the
+distribution and sharding algorithms, and much more. Outside Mail.Ru the
+software is used by a growing number of projects in online gaming, digital
+marketing, and social media industries. While product development is sponsored
+by Mail.Ru, the roadmap, the bugs database and the development process are
+fully open. The software incorporates patches from dozens of community
+contributors. The Tarantool community writes and maintains most of the drivers
+for programming languages. The greater Lua community has hundreds of useful
+packages most of which can be used in Tarantool applications with no change.
+
+
+===============================================================================
+ Reporting bugs
+===============================================================================
+
+Please report bugs in Tarantool at http://github.com/tarantool/tarantool/issues.
+You can contact developers directly on the `#tarantool`_ IRC channel on freenode,
+or via a mailing list, `Tarantool Google group`_.
+
+.. _#tarantool: irc://irc.freenode.net#tarantool
+.. _Tarantool Google group: https://groups.google.com/forum/#!forum/tarantool
+.. _Tarantool Russian-speaking list: https://googlegroups.com/group/tarantool-ru
+.. _Tarantool Gitter chat: https://gitter.im/tarantool/tarantool
+
+.. _BSD license: http://www.gnu.org/licenses/license-list.html#ModifiedBSD
+.. _Mail.Ru: http://corp.mail.ru
+.. _top 40: http://www.alexa.com/siteinfo/mail.ru
diff --git a/doc/sphinx/book/replication/1-1.rst b/doc/sphinx/book/replication/1-1.rst
new file mode 100644
index 0000000000000000000000000000000000000000..86d9d29d121882d62525057225a24fe5f71d5a21
--- /dev/null
+++ b/doc/sphinx/book/replication/1-1.rst
@@ -0,0 +1,22 @@
+.. code-block:: bash
+
+ $ # Terminal 1
+ $ mkdir -p ~/tarantool_test_node_1
+ $ cd ~/tarantool_test_node_1
+ ~/tarantool_test_node_1$ rm -R ~/tarantool_test_node_1/*
+ ~/tarantool_test_node_1$ ~/tarantool/src/tarantool
+ ~/tarantool/src/tarantool: version 1.6.3-1724-g033ed69
+ type 'help' for interactive help
+ tarantool> box.cfg{listen=3301}
+ ... ...
+ tarantool> box.schema.user.create('replicator', {password = 'password'})
+ 2014-10-13 11:12:56.052 [25018] wal I> creating `./00000000000000000000.xlog.inprogress'
+ ---
+ ...
+ tarantool> box.schema.user.grant('replicator','read,write','universe')
+ ---
+ ...
+ tarantool> box.space._cluster:select({0},{iterator='GE'})
+ ---
+ - - [1, '6190d919-1133-4452-b123-beca0b178b32']
+ ...
diff --git a/doc/sphinx/book/replication/1-2.rst b/doc/sphinx/book/replication/1-2.rst
new file mode 100644
index 0000000000000000000000000000000000000000..51e9e7687119ceda6472f6ea6f7a4f3948bd4aa5
--- /dev/null
+++ b/doc/sphinx/book/replication/1-2.rst
@@ -0,0 +1,3 @@
+.. code-block:: bash
+
+ $
diff --git a/doc/sphinx/book/replication/2-1.rst b/doc/sphinx/book/replication/2-1.rst
new file mode 100644
index 0000000000000000000000000000000000000000..852b82fd4ac500f6f4834fcbeb8a5665c6b0c497
--- /dev/null
+++ b/doc/sphinx/book/replication/2-1.rst
@@ -0,0 +1,14 @@
+.. code-block:: lua
+
+ ... ...
+ tarantool> box.space._cluster:select({0},{iterator='GE'})
+ ---
+ - - [1, '6190d919-1133-4452-b123-beca0b178b32']
+ ...
+ tarantool> 2014-10-13 11:20:08.691 [25020] main/101/spawner I> created a replication relay: pid = 25583
+ 2014-10-13 11:20:08.691 [25583] main/101/relay/127.0.0.1:50883 I> recovery start
+ 2014-10-13 11:20:08.691 [25583] main/101/relay/127.0.0.1:50883 I> recovering from `./00000000000000000000.snap'
+ 2014-10-13 11:20:08.692 [25583] main/101/relay/127.0.0.1:50883 I> snapshot sent
+ 2014-10-13 11:20:08.789 [25020] main/101/spawner I> created a replication relay: pid = 25585
+ 2014-10-13 11:20:08.890 [25585] main/101/relay/127.0.0.1:50884 I> recover from `./00000000000000000000.xlog'
+
diff --git a/doc/sphinx/book/replication/2-2.rst b/doc/sphinx/book/replication/2-2.rst
new file mode 100644
index 0000000000000000000000000000000000000000..82c1432d5e960568326a8c01dc6194ef2392d1e7
--- /dev/null
+++ b/doc/sphinx/book/replication/2-2.rst
@@ -0,0 +1,23 @@
+
+.. code-block:: bash
+
+ $ # Terminal 2
+ ~/tarantool_test_node_2$ mkdir -p ~/tarantool_test_node_2
+ ~/tarantool_test_node_2$ cd ~/tarantool_test_node_2
+ ~/tarantool_test_node_2$ rm -R ~/tarantool_test_node_2/*
+ ~/tarantool_test_node_2$ ~/tarantool/src/tarantool
+ /home/username/tarantool/src/tarantool: version 1.6.3-1724-g033ed69
+ type 'help' for interactive help
+ tarantool> box.cfg{listen=3302, replication_source='replicator:password@localhost:3301'}
+ ... ...
+ ---
+ ...
+ tarantool> box.space._cluster:select({0},{iterator='GE'})
+ 2014-10-13 11:20:08.789 [25579] main/103/replica/localhost:3301 C> connected to 127.0.0.1:3301
+ 2014-10-13 11:20:08.789 [25579] main/103/replica/localhost:3301 I> authenticated
+ 2014-10-13 11:20:08.901 [25579] wal I> creating `./00000000000000000000.xlog.inprogress'
+ ---
+ - - [1, '6190d919-1133-4452-b123-beca0b178b32']
+ - [2, '236230b8-af3e-406b-b709-15a60b44c20c']
+ ...
+
diff --git a/doc/sphinx/book/replication/3-1.rst b/doc/sphinx/book/replication/3-1.rst
new file mode 100644
index 0000000000000000000000000000000000000000..6f5a63dfba044d6d3dbe660f84a06e6f1b5ee7ba
--- /dev/null
+++ b/doc/sphinx/book/replication/3-1.rst
@@ -0,0 +1,21 @@
+.. code-block:: lua
+
+ ... ...
+ tarantool> 2014-10-13 11:20:08.691 [25020] main/101/spawner I> created a replication relay: pid = 25583
+ 2014-10-13 11:20:08.691 [25583] main/101/relay/127.0.0.1:50883 I> recovery start
+ 2014-10-13 11:20:08.691 [25583] main/101/relay/127.0.0.1:50883 I> recovering from `./00000000000000000000.snap'
+ 2014-10-13 11:20:08.692 [25583] main/101/relay/127.0.0.1:50883 I> snapshot sent
+ 2014-10-13 11:20:08.789 [25020] main/101/spawner I> created a replication relay: pid = 25585
+ 2014-10-13 11:20:08.890 [25585] main/101/relay/127.0.0.1:50884 I> recover from `./00000000000000000000.xlog'
+ ---
+ ...
+ tarantool> s = box.schema.space.create('tester')
+ ---
+ ...
+ tarantool> i = s:create_index('primary', {})
+ ---
+ ...
+ tarantool> s:insert{1,'Tuple inserted on Terminal #1'}
+ ---
+ - [1, 'Tuple inserted on Terminal #1']
+ ...
diff --git a/doc/sphinx/book/replication/3-2.rst b/doc/sphinx/book/replication/3-2.rst
new file mode 100644
index 0000000000000000000000000000000000000000..faf49f0b0af1081f29429326cb4f0a0faf8a2851
--- /dev/null
+++ b/doc/sphinx/book/replication/3-2.rst
@@ -0,0 +1,21 @@
+.. code-block:: lua
+
+ $ # Terminal 2
+ ~/tarantool_test_node_2$ mkdir -p ~/tarantool_test_node_2
+ ~/tarantool_test_node_2$ cd ~/tarantool_test_node_2
+ ~/tarantool_test_node_2$ rm -R ~/tarantool_test_node_2/*
+ ~/tarantool_test_node_2$ ~/tarantool/src/tarantool
+ /home/username/tarantool/src/tarantool: version 1.6.3-1724-g033ed69
+ type 'help' for interactive help
+ tarantool> box.cfg{listen=3302, replication_source='replicator:password@localhost:3301'}
+ ... ...
+ ---
+ ...
+ tarantool> box.space._cluster:select({0},{iterator='GE'})
+ 2014-10-13 11:20:08.789 [25579] main/103/replica/localhost:3301 C> connected to 127.0.0.1:3301
+ 2014-10-13 11:20:08.789 [25579] main/103/replica/localhost:3301 I> authenticated
+ 2014-10-13 11:20:08.901 [25579] wal I> creating `./00000000000000000000.xlog.inprogress'
+ ---
+ - - [1, '6190d919-1133-4452-b123-beca0b178b32']
+ - [2, '236230b8-af3e-406b-b709-15a60b44c20c']
+ ...
diff --git a/doc/sphinx/book/replication/4-1.rst b/doc/sphinx/book/replication/4-1.rst
new file mode 100644
index 0000000000000000000000000000000000000000..9027fda19a4ea5a9f5bcb8627f7e3ccd90abbe9e
--- /dev/null
+++ b/doc/sphinx/book/replication/4-1.rst
@@ -0,0 +1,21 @@
+.. code-block:: lua
+
+ ...
+ tarantool> 2014-10-13 11:20:08.691 [25020] main/101/spawner I> created a replication relay: pid = 25583
+ 2014-10-13 11:20:08.691 [25583] main/101/relay/127.0.0.1:50883 I> recovery start
+ 2014-10-13 11:20:08.691 [25583] main/101/relay/127.0.0.1:50883 I> recovering from `./00000000000000000000.snap'
+ 2014-10-13 11:20:08.692 [25583] main/101/relay/127.0.0.1:50883 I> snapshot sent
+ 2014-10-13 11:20:08.789 [25020] main/101/spawner I> created a replication relay: pid = 25585
+ 2014-10-13 11:20:08.890 [25585] main/101/relay/127.0.0.1:50884 I> recover from `./00000000000000000000.xlog'
+ ---
+ ...
+ tarantool> s = box.schema.space.create('tester')
+ ---
+ ...
+ tarantool> i = s:create_index('primary', {})
+ ---
+ ...
+ tarantool> s:insert{1,'Tuple inserted on Terminal #1'}
+ ---
+ - [1, 'Tuple inserted on Terminal #1']
+ ...
diff --git a/doc/sphinx/book/replication/4-2.rst b/doc/sphinx/book/replication/4-2.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b524f87af687c8d68559a2b204430d8ccfd22ee2
--- /dev/null
+++ b/doc/sphinx/book/replication/4-2.rst
@@ -0,0 +1,22 @@
+.. code-block:: lua
+
+ ... ...
+ tarantool> box.space._cluster:select({0},{iterator='GE'})
+ 2014-10-13 11:20:08.789 [25579] main/103/replica/localhost:3301 C> connected to 127.0.0.1:3301
+ 2014-10-13 11:20:08.789 [25579] main/103/replica/localhost:3301 I> authenticated
+ 2014-10-13 11:20:08.901 [25579] wal I> creating `./00000000000000000000.xlog.inprogress'
+ ---
+ - - [1, '6190d919-1133-4452-b123-beca0b178b32']
+ - [2, '236230b8-af3e-406b-b709-15a60b44c20c']
+ ...
+ tarantool> s = box.space.tester
+ ---
+ ...
+ tarantool> s:select({1},{iterator='GE'})
+ ---
+ - - [1, 'Tuple inserted on Terminal #1']
+ ...
+ tarantool> s:insert{2,'Tuple inserted on Terminal #2'}
+ ---
+ - [2, 'Tuple inserted on Terminal #2']
+ ...
diff --git a/doc/sphinx/book/replication/5-1.rst b/doc/sphinx/book/replication/5-1.rst
new file mode 100644
index 0000000000000000000000000000000000000000..cdcb79518dbbe64c2b91daa8a4e824d318db5c7c
--- /dev/null
+++ b/doc/sphinx/book/replication/5-1.rst
@@ -0,0 +1,21 @@
+.. code-block:: lua
+
+ ... ...
+ tarantool> s:insert{1,'Tuple inserted on Terminal #1'}
+ ---
+ - [1, 'Tuple inserted on Terminal #1']
+ ...
+ tarantool> os.exit()
+ 2014-10-13 11:45:20.455 [25585] main/101/relay/127.0.0.1:50884 I> done `./00000000000000000000.xlog'
+ 2014-10-13 11:45:20.531 [25020] main/101/spawner I> Exiting: master shutdown
+ 2014-10-13 11:45:20.531 [25020] main/101/spawner I> sending signal 15 to 1 children
+ 2014-10-13 11:45:20.531 [25020] main/101/spawner I> waiting for children for up to 5 seconds
+ ~/tarantool_test_node_1$ ls -l ~/tarantool_test_node_1
+ total 8
+ -rw-rw-r-- 1 1781 Oct 13 11:12 00000000000000000000.snap
+ -rw-rw-r-- 1 518 Oct 13 11:45 00000000000000000000.xlog
+ ~/tarantool_test_node_1$ ls -l ~/tarantool_test_node_2/
+ total 8
+ -rw-rw-r-- 1 1781 Oct 13 11:20 00000000000000000000.snap
+ -rw-rw-r-- 1 588 Oct 13 11:38 00000000000000000000.xlog
+ ~/tarantool_test_node_1$
diff --git a/doc/sphinx/book/replication/5-2.rst b/doc/sphinx/book/replication/5-2.rst
new file mode 100644
index 0000000000000000000000000000000000000000..5b8a5825762f3919c22bfc36a532e07d438e3c24
--- /dev/null
+++ b/doc/sphinx/book/replication/5-2.rst
@@ -0,0 +1,16 @@
+.. code-block:: lua
+
+ ... ...
+ tarantool> s:select({1},{iterator='GE'})
+ ---
+ - - [1, 'Tuple inserted on Terminal #1']
+ ...
+ tarantool> s:insert{2,'Tuple inserted on Terminal #2'}
+ ---
+ - [2, 'Tuple inserted on Terminal #2']
+ ...
+ tarantool> 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> can't read row
+ 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 !> SystemError
+ unexpected EOF when reading from socket,
+ called on fd 10, aka 127.0.0.1:50884, peer of 127.0.0.1:3301: Broken pipe
+ 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> will retry every 1 second
diff --git a/doc/sphinx/book/replication/6-1.rst b/doc/sphinx/book/replication/6-1.rst
new file mode 100644
index 0000000000000000000000000000000000000000..cdcb79518dbbe64c2b91daa8a4e824d318db5c7c
--- /dev/null
+++ b/doc/sphinx/book/replication/6-1.rst
@@ -0,0 +1,21 @@
+.. code-block:: lua
+
+ ... ...
+ tarantool> s:insert{1,'Tuple inserted on Terminal #1'}
+ ---
+ - [1, 'Tuple inserted on Terminal #1']
+ ...
+ tarantool> os.exit()
+ 2014-10-13 11:45:20.455 [25585] main/101/relay/127.0.0.1:50884 I> done `./00000000000000000000.xlog'
+ 2014-10-13 11:45:20.531 [25020] main/101/spawner I> Exiting: master shutdown
+ 2014-10-13 11:45:20.531 [25020] main/101/spawner I> sending signal 15 to 1 children
+ 2014-10-13 11:45:20.531 [25020] main/101/spawner I> waiting for children for up to 5 seconds
+ ~/tarantool_test_node_1$ ls -l ~/tarantool_test_node_1
+ total 8
+ -rw-rw-r-- 1 1781 Oct 13 11:12 00000000000000000000.snap
+ -rw-rw-r-- 1 518 Oct 13 11:45 00000000000000000000.xlog
+ ~/tarantool_test_node_1$ ls -l ~/tarantool_test_node_2/
+ total 8
+ -rw-rw-r-- 1 1781 Oct 13 11:20 00000000000000000000.snap
+ -rw-rw-r-- 1 588 Oct 13 11:38 00000000000000000000.xlog
+ ~/tarantool_test_node_1$
diff --git a/doc/sphinx/book/replication/6-2.rst b/doc/sphinx/book/replication/6-2.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8e17263605377c6d0e91b093160befec82e68f8a
--- /dev/null
+++ b/doc/sphinx/book/replication/6-2.rst
@@ -0,0 +1,21 @@
+.. code-block:: lua
+
+ ... ...
+ tarantool> s:insert{2,'Tuple inserted on Terminal #2'}
+ ---
+ - [2, 'Tuple inserted on Terminal #2']
+ ...
+ tarantool> 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> can't read row
+ 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 !> SystemError
+ unexpected EOF when reading from socket,
+ called on fd 10, aka 127.0.0.1:50884, peer of 127.0.0.1:3301: Broken pipe
+ 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> will retry every 1 second
+ tarantool> box.space.tester:select({0},{iterator='GE'})
+ ---
+ - - [1, 'Tuple inserted on Terminal #1']
+ - [2, 'Tuple inserted on Terminal #2']
+ ...
+ tarantool> box.space.tester:insert{3,'Another'}
+ ---
+ - [3, 'Another']
+ ...
diff --git a/doc/sphinx/book/replication/7-1.rst b/doc/sphinx/book/replication/7-1.rst
new file mode 100644
index 0000000000000000000000000000000000000000..cdd2ddcd82ad965ad3dda567c7d6610c93e3f4d9
--- /dev/null
+++ b/doc/sphinx/book/replication/7-1.rst
@@ -0,0 +1,34 @@
+.. code-block:: lua
+
+ ... ...
+ tarantool> s:insert{1,'Tuple inserted on Terminal #1'}
+ ---
+ - [1, 'Tuple inserted on Terminal #1']
+ ...
+ tarantool> os.exit()
+ 2014-10-13 11:45:20.455 [25585] main/101/relay/127.0.0.1:50884 I> done `./00000000000000000000.xlog'
+ 2014-10-13 11:45:20.531 [25020] main/101/spawner I> Exiting: master shutdown
+ 2014-10-13 11:45:20.531 [25020] main/101/spawner I> sending signal 15 to 1 children
+ 2014-10-13 11:45:20.531 [25020] main/101/spawner I> waiting for children for up to 5 seconds
+ ~/tarantool_test_node_1$ ls -l ~/tarantool_test_node_1
+ total 8
+ -rw-rw-r-- 1 1781 Oct 13 11:12 00000000000000000000.snap
+ -rw-rw-r-- 1 518 Oct 13 11:45 00000000000000000000.xlog
+ ~/tarantool_test_node_1$ ls -l ~/tarantool_test_node_2/
+ total 8
+ -rw-rw-r-- 1 1781 Oct 13 11:20 00000000000000000000.snap
+ -rw-rw-r-- 1 588 Oct 13 11:38 00000000000000000000.xlog
+ ~/tarantool_test_node_1$ ~/tarantool/src/tarantool
+ /home/username/tarantool/src/tarantool: version 1.6.3-515-g0a06cce
+ type 'help' for interactive help
+ tarantool> box.cfg{listen=3301}
+ ... ...
+ ---
+ ...
+ tarantool> box.space.tester:select({0},{iterator='GE'})
+ 2014-10-13 12:01:55.615 [28989] main/101/spawner I> created a replication relay: pid = 28992
+ 2014-10-13 12:01:55.716 [28992] main/101/relay/127.0.0.1:51892 I> recover from `./00000000000000000000.xlog'
+ 2014-10-13 12:01:55.716 [28992] main/101/relay/127.0.0.1:51892 I> done `./00000000000000000000.xlog'
+ ---
+ - - [1, 'Tuple inserted on Terminal #1']
+ ...
diff --git a/doc/sphinx/book/replication/7-2.rst b/doc/sphinx/book/replication/7-2.rst
new file mode 100644
index 0000000000000000000000000000000000000000..43764599ef9b42e2d032a87e90b1274b981e769c
--- /dev/null
+++ b/doc/sphinx/book/replication/7-2.rst
@@ -0,0 +1,25 @@
+.. code-block:: lua
+
+ ... ...
+ tarantool> s:insert{2,'Tuple inserted on Terminal #2'}
+ ---
+ - [2, 'Tuple inserted on Terminal #2']
+ ...
+ tarantool> 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> can't read row
+ 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 !> SystemError
+ unexpected EOF when reading from socket,
+ called on fd 10, aka 127.0.0.1:50884, peer of 127.0.0.1:3301: Broken pipe
+ 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> will retry every 1 second
+ tarantool> box.space.tester:select({0},{iterator='GE'})
+ ---
+ - - [1, 'Tuple inserted on Terminal #1']
+ - [2, 'Tuple inserted on Terminal #2']
+ ...
+ tarantool> box.space.tester:insert{3,'Another'}
+ ---
+ - [3, 'Another']
+ ...
+ tarantool>
+ 2014-10-13 12:01:55.614 [25579] main/103/replica/localhost:3301 C> connected to 127.0.0.1:3301
+ 2014-10-13 12:01:55.614 [25579] main/103/replica/localhost:3301 I> authenticated
+
diff --git a/doc/sphinx/book/replication/8-1.rst b/doc/sphinx/book/replication/8-1.rst
new file mode 100644
index 0000000000000000000000000000000000000000..90e50fa595d5b38de6d39cdc8b2c6b0c3df90a5b
--- /dev/null
+++ b/doc/sphinx/book/replication/8-1.rst
@@ -0,0 +1,33 @@
+.. code-block:: lua
+
+ ... ...
+ ~/tarantool_test_node_1$ ~/tarantool/src/tarantool
+ ~/tarantool: version 1.6.3-1724-g033ed69
+ type 'help' for interactive help
+ tarantool> box.cfg{listen=3301}
+ ... ...
+ ---
+ ...
+ tarantool> box.space.tester:select({0},{iterator='GE'})
+ 2014-10-13 12:01:55.615 [28989] main/101/spawner I> created a replication relay: pid = 28992
+ 2014-10-13 12:01:55.716 [28992] main/101/relay/127.0.0.1:51892 I> recover from `./00000000000000000000.xlog'
+ 2014-10-13 12:01:55.716 [28992] main/101/relay/127.0.0.1:51892 I> done `./00000000000000000000.xlog'
+
+ ---
+ - - [1, 'Tuple inserted on Terminal #1']
+ ...
+ tarantool> box.cfg{replication_source='replicator:password@localhost:3302'}
+ 2014-10-13 12:10:21.485 [28987] main/101/interactive C> starting replication from localhost:3302
+ ---
+ ...
+ 2014-10-13 12:10:21.487 [28987] main/104/replica/localhost:3302 C> connected to 127.0.0.1:3302
+ 2014-10-13 12:10:21.487 [28987] main/104/replica/localhost:3302 I> authenticated
+ tarantool> box.space.tester:select({0},{iterator='GE'})
+ 2014-10-13 12:10:21.592 [28987] wal I> creating `./00000000000000000006.xlog.inprogress'
+ 2014-10-13 12:10:21.617 [28992] main/101/relay/127.0.0.1:51892 I> recover from `./00000000000000000006.xlog'
+ ---
+ - - [1, 'Tuple inserted on Terminal #1']
+ - [2, 'Tuple inserted on Terminal #2']
+ - [3, 'Another']
+ ...
+
diff --git a/doc/sphinx/book/replication/8-2.rst b/doc/sphinx/book/replication/8-2.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b3fc1924c639f48a2daf2f4cb22a159f1891ce7a
--- /dev/null
+++ b/doc/sphinx/book/replication/8-2.rst
@@ -0,0 +1,26 @@
+.. code-block:: lua
+
+ ... ...
+ tarantool> s:insert{2,'Tuple inserted on Terminal #2'}
+ ---
+ - [2, 'Tuple inserted on Terminal #2']
+ ...
+ tarantool> 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> can't read row
+ 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 !> SystemError
+ unexpected EOF when reading from socket,
+ called on fd 10, aka 127.0.0.1:50884, peer of 127.0.0.1:3301: Broken pipe
+ 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> will retry every 1 second
+ tarantool> box.space.tester:select({0},{iterator='GE'})
+ ---
+ - - [1, 'Tuple inserted on Terminal #1']
+ - [2, 'Tuple inserted on Terminal #2']
+ ...
+ tarantool> box.space.tester:insert{3,'Another'}
+ ---
+ - [3, 'Another']
+ ...
+ tarantool>
+ 2014-10-13 12:01:55.614 [25579] main/103/replica/localhost:3301 C> connected to 127.0.0.1:3301
+ 2014-10-13 12:01:55.614 [25579] main/103/replica/localhost:3301 I> authenticated
+ 2014-10-13 12:10:21.488 [25581] main/101/spawner I> created a replication relay: pid = 29632
+ 2014-10-13 12:10:21.592 [29632] main/101/relay/127.0.0.1:45908 I> recover from `./00000000000000000000.xlog'
diff --git a/doc/sphinx/book/replication/index.rst b/doc/sphinx/book/replication/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..5a02bef0e27c2bfa8220cafb1f9108cf6c6c691f
--- /dev/null
+++ b/doc/sphinx/book/replication/index.rst
@@ -0,0 +1,434 @@
+.. include:: /directives.rst
+.. highlight:: lua
+
+.. _box-replication:
+
+-------------------------------------------------------------------------------
+ Replication
+-------------------------------------------------------------------------------
+
+Replication allows multiple Tarantool servers to work on copies of the same
+databases. The databases are kept in synch because each server can communicate
+its changes to all the other servers. Servers which share the same databases
+are a "cluster". Each server in a cluster also has a numeric identifier which
+is unique within the cluster, known as the "server id".
+
+ To set up replication, it's necessary to set up the master servers which
+ make the original data-change requests, set up the replica servers which
+ copy data-change requests from masters, and establish procedures for
+ recovery from a degraded state.
+
+=====================================================================
+ Replication architecture
+=====================================================================
+
+A replica gets all updates from the master by continuously fetching and
+applying its write-ahead log (WAL). Each record in the WAL represents a
+single Tarantool data-change request such as INSERT or UPDATE or DELETE,
+and is assigned a monotonically growing log sequence number (LSN). In
+essence, Tarantool replication is row-based: each data change command is
+fully deterministic and operates on a single tuple.
+
+A stored program invocation is not written to the write-ahead log. Instead,
+log events for actual data-change requests, performed by the Lua code, are
+written to the log. This ensures that possible non-determinism of Lua does
+not cause replication to go out of sync.
+
+=====================================================================
+ Setting up the master
+=====================================================================
+
+To prepare the master for connections from the replica, it's only necessary
+to include "listen" in the initial ``box.cfg`` request, for example
+``box.cfg{listen=3301}``. A master with enabled "listen" URI can accept
+connections from as many replicas as necessary on that URI. Each replica
+has its own replication state.
+
+=====================================================================
+ Setting up a replica
+=====================================================================
+
+A server requires a valid snapshot (.snap) file. A snapshot file is created
+for a server the first time that ``box.cfg`` occurs for it. If this first
+``box.cfg`` request occurs without a "replication_source" clause, then the
+server is a master and starts its own new cluster with a new unique UUID.
+If this first ``box.cfg`` request occurs with a "replication_source" clause,
+then the server is a replica and its snapshot file, along with the cluster
+information, is constructed from the write-ahead logs of the master.
+Therefore, to start replication, specify :ref:`replication_source <replication_source>`
+in a ``box.cfg`` request. When a replica contacts a master for the first time,
+it becomes part of a cluster. On subsequent occasions, it should always contact
+a master in the same cluster.
+
+Once connected to the master, the replica requests all changes that happened
+after the latest local LSN. It is therefore necessary to keep WAL files on
+the master host as long as there are replicas that haven't applied them yet.
+A replica can be "re-seeded" by deleting all its files (the snapshot .snap
+file and the WAL .xlog files), then starting replication again - the replica
+will then catch up with the master by retrieving all the master's tuples.
+Again, this procedure works only if the master's WAL files are present.
+
+.. NOTE::
+
+ Replication parameters are "dynamic", which allows the replica to become
+ a master and vice versa with the help of the :func:`box.cfg` statement.
+
+.. NOTE::
+
+ The replica does not inherit the master's configuration parameters, such
+ as the ones that cause the :ref:`snapshot daemon` to run on the master. To get
+ the same behavior, one would have to set the relevant parameters explicitly
+ so that they are the same on both master and replica.
+
+=====================================================================
+ Recovering from a degraded state
+=====================================================================
+
+"Degraded state" is a situation when the master becomes unavailable - due to
+hardware or network failure, or due to a programming bug. There is no automatic
+way for a replica to detect that the master is gone for good, since sources of
+failure and replication environments vary significantly. So the detection of
+degraded state requires a human inspection.
+
+However, once a master failure is detected, the recovery is simple: declare
+that the replica is now the new master, by saying ``box.cfg{... listen=URI}``.
+Then, if there are updates on the old master that were not propagated before
+the old master went down, they would have to be re-applied manually.
+
+
+
+=====================================================================
+ Instructions for quick startup of a new two-server simple cluster
+=====================================================================
+
+Step 1. Start the first server thus:
+
+.. code-block:: lua
+
+ box.cfg{listen=uri#1}
+ -- replace with more restrictive request
+ box.schema.user.grant('guest','read,write,execute','universe')
+ box.snapshot()
+
+... Now a new cluster exists.
+
+Step 2. Check where the second server's files will go by looking at its
+directories (:ref:`snap_dir <snap_dir>` for snapshot files,
+:ref:`wal_dir <wal_dir>` for .xlog files).
+They must be empty - when the second server joins for the first time, it
+has to be working with a clean slate so that the initial copy of the first
+server's databases can happen without conflicts.
+
+Step 3. Start the second server thus:
+
+.. code-block:: lua
+
+ box.cfg{listen=uri#2, replication_source=uri#1}
+
+... where ``uri#1`` = the :ref:`URI` that the first server is listening on.
+
+That's all.
+
+In this configuration, the first server is the "master" and the second server
+is the "replica". Henceforth every change that happens on the master will be
+visible on the replica. A simple two-server cluster with the master on one
+computer and the replica on a different computer is very common and provides
+two benefits: FAILOVER (because if the master goes down then the replica can
+take over), or LOAD BALANCING (because clients can connect to either the master
+or the replica for select requests).
+
+=====================================================================
+ Master-Master Replication
+=====================================================================
+
+In the simple master-replica configuration, the master's changes are seen by
+the replica, but not vice versa, because the master was specified as the sole
+replication source. Starting with Tarantool 1.6, it's possible to go both ways.
+Starting with the simple configuration, the first server has to say:
+``box.cfg{replication_source=uri#2}``. This request can be performed at any time.
+
+In this configuration, both servers are "masters" and both servers are
+"replicas". Henceforth every change that happens on either server will
+be visible on the other. The failover benefit is still present, and the
+load-balancing benefit is enhanced (because clients can connect to either
+server for data-change requests as well as select requests).
+
+If two operations for the same tuple take place "concurrently" (which can
+involve a long interval because replication is asynchronous), and one of
+the operations is ``delete`` or ``replace``, there is a possibility that
+servers will end up with different contents.
+
+
+=====================================================================
+ All the "What If?" Questions
+=====================================================================
+
+:Q: What if there are more than two servers with master-master?
+:A: On each server, specify the replication_source for all the others. For
+ example, server #3 would have a request:
+ ``box.cfg{replication_source=uri#1, replication_source=uri#2}``.
+
+:Q: What if a a server should be taken out of the cluster?
+:A: Run ``box.cfg{}`` again specifying a blank replication source:
+ ``box.cfg{replication_source=''}``.
+
+:Q: What if a server leaves the cluster?
+:A: The other servers carry on. If the wayward server rejoins, it will receive
+ all the updates that the other servers made while it was away.
+
+:Q: What if two servers both change the same tuple?
+:A: The last changer wins. For example, suppose that server#1 changes the tuple,
+ then server#2 changes the tuple. In that case server#2's change overrides
+ whatever server#1 did. In order to keep track of who came last, Tarantool
+ implements a `vector clock`_.
+
+:Q: What if a master disappears and the replica must take over?
+:A: A message will appear on the replica stating that the connection is lost.
+ The replica must now become independent, which can be done by saying
+ ``box.cfg{replication_source=''}``.
+
+:Q: What if it's necessary to know what cluster a server is in?
+:A: The identification of the cluster is a UUID which is generated when the
+ first master starts for the first time. This UUID is stored in a tuple
+ of the :data:`box.space._cluster` system space, and in a tuple of the
+ :data:`box.space._schema` system space. So to see it, say:
+ ``box.space._schema:select{'cluster'}``
+
+:Q: What if one of the server's files is corrupted or deleted?
+:A: Stop the server, destroy all the database files (the ones with extension
+ "snap" or "xlog" or ".inprogress"), restart the server, and catch up with
+ the master by contacting it again (just say ``box.cfg{...replication_source=...}``).
+
+:Q: What if replication causes security concerns?
+:A: Prevent unauthorized replication sources by associating a password with
+ every user that has access privileges for the relevant spaces. That way,
+ the :ref:`URI` for the replication_source parameter will always have to have
+ the long form ``replication_source='username:password@host:port'``.
+
+.. _vector clock: https://en.wikipedia.org/wiki/Vector_clock
+
+=====================================================================
+ Hands-On Replication Tutorial
+=====================================================================
+
+After following the steps here, an administrator will have experience creating
+a cluster and adding a replica.
+
+Start two shells. Put them side by side on the screen.
+
+.. container:: table-wide
+
+ +----------------------+---------------------+
+ | Terminal #1 | Terminal #2 |
+ +======================+=====================+
+ | | |
+ | .. code-block:: lua | .. code-block:: lua |
+ | | |
+ | $ | $ |
+ | | |
+ +----------------------+---------------------+
+
+On the first shell, which we'll call Terminal #1, execute these commands:
+
+.. code-block:: bash
+
+ # Terminal 1
+ mkdir -p ~/tarantool_test_node_1
+ cd ~/tarantool_test_node_1
+ rm -R ~/tarantool_test_node_1/*
+ ~/tarantool/src/tarantool
+ box.cfg{listen=3301}
+ box.schema.user.create('replicator', {password = 'password'})
+ box.schema.user.grant('replicator','read,write','universe')
+ box.space._cluster:select({0},{iterator='GE'})
+
+The result is that a new cluster is set up, and the UUID is displayed.
+Now the screen looks like this: (except that UUID values are always different):
+
+
+.. container:: table-wide
+
+ +----------------------------------+----------------------------------+
+ | Terminal #1 | Terminal #2 |
+ +==================================+==================================+
+ | | |
+ | .. include:: 1-1.rst | .. include:: 1-2.rst |
+ | | |
+ +----------------------------------+----------------------------------+
+
+On the second shell, which we'll call Terminal #2, execute these commands:
+
+.. code-block:: bash
+
+ # Terminal 2
+ mkdir -p ~/tarantool_test_node_2
+ cd ~/tarantool_test_node_2
+ rm -R ~/tarantool_test_node_2/*
+ ~/tarantool/src/tarantool
+ box.cfg{listen=3302, replication_source='replicator:password@localhost:3301'}
+ box.space._cluster:select({0},{iterator='GE'})
+
+The result is that a replica is set up. Messages appear on Terminal #1
+confirming that the replica has connected and that the WAL contents have
+been shipped to the replica. Messages appear on Terminal #2 showing that
+replication is starting. Also on Terminal#2 the _cluster UUID value is
+displayed, and it is the same as the _cluster UUID value that was displayed
+on Terminal #1, because both servers are in the same cluster.
+
+
+.. container:: table-wide
+
+ +----------------------------------+----------------------------------+
+ | Terminal #1 | Terminal #2 |
+ +==================================+==================================+
+ | | |
+ | .. include:: 2-1.rst | .. include:: 2-2.rst |
+ | | |
+ +----------------------------------+----------------------------------+
+
+On Terminal #1, execute these requests:
+
+.. code-block:: lua
+
+ s = box.schema.space.create('tester')
+ i = s:create_index('primary', {})
+ s:insert{1,'Tuple inserted on Terminal #1'}
+
+Now the screen looks like this:
+
+.. container:: table-wide
+
+ +----------------------------------+----------------------------------+
+ | Terminal #1 | Terminal #2 |
+ +==================================+==================================+
+ | | |
+ | .. include:: 3-1.rst | .. include:: 3-2.rst |
+ | | |
+ +----------------------------------+----------------------------------+
+
+The creation and insertion were successful on Terminal #1.
+Nothing has happened on Terminal #2.
+
+On Terminal #2, execute these requests:
+
+.. code-block:: lua
+
+ s = box.space.tester
+ s:select({1},{iterator='GE'})
+ s:insert{2,'Tuple inserted on Terminal #2'}
+
+Now the screen looks like this:
+
+.. container:: table-wide
+
+ +----------------------------------+----------------------------------+
+ | Terminal #1 | Terminal #2 |
+ +==================================+==================================+
+ | | |
+ | .. include:: 4-1.rst | .. include:: 4-2.rst |
+ | | |
+ +----------------------------------+----------------------------------+
+
+The selection and insertion were successful on Terminal #2. Nothing has
+happened on Terminal #1.
+
+On Terminal #1, execute these Tarantool requests and shell commands:
+
+.. code-block:: lua
+
+ os.exit()
+ ls -l ~/tarantool_test_node_1
+ ls -l ~/tarantool_test_node_2
+
+Now Tarantool #1 is stopped. Messages appear on Terminal #2 announcing that fact.
+The "ls -l" commands show that both servers have made snapshots, which have the
+same size because they both contain the same tuples.
+
+.. container:: table-wide
+
+ +----------------------------------+----------------------------------+
+ | Terminal #1 | Terminal #2 |
+ +==================================+==================================+
+ | | |
+ | .. include:: 5-1.rst | .. include:: 5-2.rst |
+ | | |
+ +----------------------------------+----------------------------------+
+
+On Terminal #2, ignore the repeated messages saying "failed to connect",
+and execute these requests:
+
+.. code-block:: lua
+
+ box.space.tester:select({0},{iterator='GE'})
+ box.space.tester:insert{3,'Another'}
+
+Now the screen looks like this (ignoring the repeated messages saying
+"failed to connect"):
+
+.. container:: table-wide
+
+ +----------------------------------+----------------------------------+
+ | Terminal #1 | Terminal #2 |
+ +==================================+==================================+
+ | | |
+ | .. include:: 6-1.rst | .. include:: 6-2.rst |
+ | | |
+ +----------------------------------+----------------------------------+
+
+Terminal #2 has done a select and an insert, even though Terminal #1 is down.
+
+On Terminal #1 execute these commands:
+
+.. code-block:: lua
+
+ ~/tarantool/src/tarantool
+ box.cfg{listen=3301}
+ box.space.tester:select({0},{iterator='GE'})
+
+Now the screen looks like this (ignoring the repeated messages on terminal
+#2 saying "failed to connect"):
+
+.. container:: table-wide
+
+ +----------------------------------+----------------------------------+
+ | Terminal #1 | Terminal #2 |
+ +==================================+==================================+
+ | | |
+ | .. include:: 7-1.rst | .. include:: 7-2.rst |
+ | | |
+ +----------------------------------+----------------------------------+
+
+The master has reconnected to the cluster, and has NOT found what the replica
+wrote while the master was away. That is not a surprise -- the replica has not
+been asked to act as a replication source.
+
+On Terminal #1, say:
+
+.. code-block:: lua
+
+ box.cfg{replication_source='replicator:password@localhost:3302'}
+ box.space.tester:select({0},{iterator='GE'})
+
+The screen now looks like this:
+
+.. container:: table-wide
+
+ +----------------------------------+----------------------------------+
+ | Terminal #1 | Terminal #2 |
+ +==================================+==================================+
+ | | |
+ | .. include:: 8-1.rst | .. include:: 8-2.rst |
+ | | |
+ +----------------------------------+----------------------------------+
+
+This shows that the two servers are once again in synch, and that each server
+sees what the other server wrote.
+
+To clean up, say "``os.exit()``" on both Terminal #1 and Terminal #2, and then
+on either terminal say:
+
+.. code-block:: lua
+
+ cd ~
+ rm -R ~/tarantool_test_node_1
+ rm -R ~/tarantool_test_node_2
diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py
new file mode 100644
index 0000000000000000000000000000000000000000..617ae442c81f23b19eeda341f85110e6c4024041
--- /dev/null
+++ b/doc/sphinx/conf.py
@@ -0,0 +1,268 @@
+# -*- coding: utf-8 -*-
+#
+# Tarantool documentation build configuration file, created by
+# sphinx-quickstart on Mon Nov 24 15:29:04 2014.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+
+extensions = [
+ 'sphinx.ext.todo',
+ 'sphinx.ext.ifconfig',
+ 'ext.filters',
+ 'ext.lua'
+]
+primary_domain = 'lua'
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Tarantool'
+copyright = u'2015, http://tarantool.org'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The full version, including alpha/beta/rc tags.
+release = open('../../VERSION').read().strip()
+# The short X.Y version.
+version = '.'.join(release.split('.')[0:2])
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build', 'directives.rst', 'book/connectors/__*']
+exclude_patterns += [
+ 'book/replication/*-1.rst',
+ 'book/replication/*-2.rst'
+]
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+html_use_index = False
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Tarantooldoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ ('index', 'Tarantool.tex', u'Tarantool Documentation',
+ u'http://tarantool.org', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'tarantool', u'Tarantool Documentation',
+ [u'http://tarantool.org'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ ('index', 'Tarantool', u'Tarantool Documentation',
+ u'http://tarantool.org', 'Tarantool', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
diff --git a/doc/sphinx/dev_guide/.c-stule-guide.rst.swp b/doc/sphinx/dev_guide/.c-stule-guide.rst.swp
new file mode 100644
index 0000000000000000000000000000000000000000..b82e071a3d51854dc865b419aa126c126eb4150a
Binary files /dev/null and b/doc/sphinx/dev_guide/.c-stule-guide.rst.swp differ
diff --git a/doc/www/content/doc/box-protocol.rst b/doc/sphinx/dev_guide/box-protocol.rst
similarity index 89%
rename from doc/www/content/doc/box-protocol.rst
rename to doc/sphinx/dev_guide/box-protocol.rst
index 13e2c1c228dc46e3e213db5e36ccc566023af64f..708b558ad6f46eba2e6084e90bac746c701c25e0 100644
--- a/doc/www/content/doc/box-protocol.rst
+++ b/doc/sphinx/dev_guide/box-protocol.rst
@@ -2,12 +2,18 @@
:slug: box-protocol
:save_as: doc/box-protocol.html
:url: doc/box-protocol.html
-:template: old_documentation
+:template: documentation_rst
+
+.. _iproto protocol:
--------------------------------------------------------------------------------
- Notion in diagrams
+ IProto Protocol
--------------------------------------------------------------------------------
+================================================================================
+ Notion in diagrams
+================================================================================
+
.. code-block:: bash
0 X
@@ -37,15 +43,15 @@ MsgPack data types:
* **MP_OBJECT** - Any MsgPack object
---------------------------------------------------------------------------------
+================================================================================
Overview
---------------------------------------------------------------------------------
+================================================================================
IPROTO is a binary request/response protocol.
---------------------------------------------------------------------------------
- Greeting Package
---------------------------------------------------------------------------------
+================================================================================
+ Greeting Packet
+================================================================================
.. code-block:: bash
@@ -68,9 +74,9 @@ to the client. The first 64 bytes of the greeting contain server version. The
second 44 bytes contain a base64-encoded random string, to use in authentification
packet. And it ends with 20 bytes of spaces.
---------------------------------------------------------------------------------
- Unified package structure
---------------------------------------------------------------------------------
+================================================================================
+ Unified packet structure
+================================================================================
Once a greeting is read, the protocol becomes pure request/response and features
a complete access to Tarantool functionality, including:
@@ -156,9 +162,9 @@ They only differ in the allowed set of keys and values, the key defines the
type of value that follows. If a body has no keys, entire msgpack map for
the body may be missing. Such is the case, for example, in <ping> request.
---------------------------------------------------------------------------------
+================================================================================
Authentication
---------------------------------------------------------------------------------
+================================================================================
When a client connects to the server, the server responds with a 128-byte
text greeting message. Part of the greeting is base-64 encoded session salt -
@@ -201,9 +207,9 @@ and password, encrypted according to the specified mechanism. Authentication in
Tarantool is optional, if no authentication is performed, session user is 'guest'.
The server responds to authentication packet with a standard response with 0 tuples.
---------------------------------------------------------------------------------
+================================================================================
Requests
---------------------------------------------------------------------------------
+================================================================================
* SELECT: CODE - 0x01
Find tuples matching the search pattern
@@ -250,15 +256,20 @@ The server responds to authentication packet with a standard response with 0 tup
UPDATE BODY:
- +==================+==================+==================+=======================+
- | | | | +~~~~~~~~~~+ |
- | | | | | | |
- | | | | (TUPLE) | OP | |
- | 0x10: SPACE_ID | 0x11: INDEX_ID | 0x20: KEY | 0x21: | | |
- | MP_INT: MP_INT | MP_INT: MP_INT | MP_INT: MP_ARRAY | MP_INT: +~~~~~~~~~~+ |
- | | | | MP_ARRAY |
- +==================+==================+==================+=======================+
- MP_MAP
+ +==================+=======================+
+ | | |
+ | 0x10: SPACE_ID | 0x11: INDEX_ID |
+ | MP_INT: MP_INT | MP_INT: MP_INT |
+ | | |
+ +==================+=======================+
+ | | +~~~~~~~~~~+ |
+ | | | | |
+ | | (TUPLE) | OP | |
+ | 0x20: KEY | 0x21: | | |
+ | MP_INT: MP_ARRAY | MP_INT: +~~~~~~~~~~+ |
+ | | MP_ARRAY |
+ +==================+=======================+
+ MP_MAP
.. code-block:: bash
@@ -271,7 +282,8 @@ The server responds to authentication packet with a standard response with 0 tup
* Bitwise OR OP = '|' . space[key][field_no] |= argument
Works on any fields:
* Delete OP = '#'
- delete <argument> fields starting from <field_no> in the space[<key>]
+ delete <argument> fields starting
+ from <field_no> in the space[<key>]
0 2
+-----------+==========+==========+
@@ -366,9 +378,9 @@ It's an error to specify an argument of a type that differs from expected type.
MP_MAP
---------------------------------------------------------------------------------
+================================================================================
Response packet structure
---------------------------------------------------------------------------------
+================================================================================
We'll show whole packets here:
@@ -411,9 +423,9 @@ Convenience macros which define hexadecimal constants for return codes
can be found in `src/errcode.h
<https://github.com/tarantool/tarantool/blob/master/src/errcode.h>`_
---------------------------------------------------------------------------------
+================================================================================
Replication packet structure
---------------------------------------------------------------------------------
+================================================================================
.. code-block:: bash
@@ -447,8 +459,8 @@ can be found in `src/errcode.h
MP_MAP MP_MAP
Then server, which we connect to, will send last SNAP file by, simply,
- creating a number of INSERT's (with additional LSN and ServerID) (don't reply)
- Then it'll send a vclock's MP_MAP and close a socket.
+ creating a number of INSERT's (with additional LSN and ServerID)
+ (don't reply). Then it'll send a vclock's MP_MAP and close a socket.
+================+================++============================+
| | || +~~~~~~~~~~~~~~~~~+ |
@@ -465,13 +477,19 @@ can be found in `src/errcode.h
Then you must send SUBSCRIBE:
HEADER
- +================+================+===================+===================+
- | | | SERVER_UUID | CLUSTER_UUID |
- | 0x00: 0x41 | 0x01: SYNC | 0x24: UUID | 0x25: UUID |
- | MP_INT: MP_INT | MP_INT: MP_INT | MP_INT: MP_STRING | MP_INT: MP_STRING |
- | | | | |
- +================+================+===================+===================+
- MP_MAP
+ +===================+===================+
+ | | |
+ | 0x00: 0x41 | 0x01: SYNC |
+ | MP_INT: MP_INT | MP_INT: MP_INT |
+ | | |
+ +===================+===================+
+ | SERVER_UUID | CLUSTER_UUID |
+ | 0x24: UUID | 0x25: UUID |
+ | MP_INT: MP_STRING | MP_INT: MP_STRING |
+ | | |
+ +===================+===================+
+ MP_MAP
+
BODY
+================+
| |
@@ -484,9 +502,9 @@ can be found in `src/errcode.h
Then you must process every query that'll came through other masters.
Every request between masters will have Additional LSN and SERVER_ID.
---------------------------------------------------------------------------------
+================================================================================
XLOG / SNAP
---------------------------------------------------------------------------------
+================================================================================
XLOG and SNAP have the same format. They start with:
diff --git a/doc/sphinx/dev_guide/building_from_source.rst b/doc/sphinx/dev_guide/building_from_source.rst
new file mode 100644
index 0000000000000000000000000000000000000000..38f65176e27227c224f48398a2bc9165277a2142
--- /dev/null
+++ b/doc/sphinx/dev_guide/building_from_source.rst
@@ -0,0 +1,279 @@
+.. include:: ../directives.rst
+
+.. _building-from-source:
+
+-------------------------------------------------------------------------------
+ Building from source
+-------------------------------------------------------------------------------
+
+For downloading Tarantool source and building it, the platforms can differ and the
+preferences can differ. But the steps are always the same. Here in the manual we'll
+explain what the steps are, then on the Internet you can look at some example scripts.
+
+1. Get tools and libraries that will be necessary for building
+ and testing. The absolutely necessary ones are:
+
+ * A program for downloading source repositories. |br| In this case the necessary program
+ is ``git``. Although tarantool.org/dist has source tarballs (the files whose names
+ end in `-src.tar.gz`), the latest complete source downloads are on github.com, and
+ from github one gets with git.
+
+ * A C/C++ compiler. |br| Ordinarily the compiler is ``GCC`` version 4.6 or later, on
+ Mac OS X it should be ``Clang`` version 3.2 or later.
+
+ * A program for managing the build process. |br| This is always ``CMake``
+ for GNU/Linux and FreeBSD. The CMake version should be 2.8 or later.
+
+ Here are names of tools and libraries which may have to be installed in advance,
+ using ``sudo apt-get`` (for Ubuntu), ``sudo yum install`` (for CentOS), or the
+ equivalent on other platforms. Different platforms may use slightly different
+ names. Do not worry about the ones marked `optional, for build with -DENABLE_DOC`
+ unless you intend to work on the documentation.
+
+ * **binutils-dev** or **binutils-devel** # contains GNU BFD for printing stack traces
+ * **gcc or clang** # see above
+ * **git** # see above
+ * **cmake** # see above
+ * **libreadline-dev** # for interactive mode
+ * **libncurses5-dev** or **ncurses-devel** # see above
+ * **xsltproc** # optional, for build with -DENABLE_DOC
+ * **lynx** # optional, for build with -DENABLE_DOC
+ * **jing** # optional, for build with -DENABLE_DOC
+ * **libxml2-utils** # optional, for build with -DENABLE_DOC
+ * **docbook5-xml** # optional, for build with -DENABLE_DOC
+ * **docbook-xsl-ns** # optional, for build with -DENABLE_DOC
+ * **w3c-sgml-lib** # optional, for build with -DENABLE_DOC
+ * **libsaxon-java** # optional, for build with -DENABLE_DOC
+ * **libxml-commons-resolver1.1-java** # optional, for build with -DENABLE_DOC
+ * **libxerces2-java** # optional, for build with -DENABLE_DOC
+ * **libxslthl-java** # optional, for build with -DENABLE_DOC
+ * **autoconf** # optional, appears only in Mac OS scripts
+ * **zlib1g** or **zlib** # optional, appears only in Mac OS scripts
+
+2. Set up python modules for running the test suite or creating documentation.
+ This step is optional. Python modules are not necessary for building Tarantool
+ itself, unless one intends to use the ``-DENABLE_DOC`` option in step 6 or the
+ "Run the test suite" option in step 8. Say:
+
+ .. code-block:: bash
+
+ python --version
+
+ You should see that the python version is greater than 2.6 --
+ preferably 2.7 -- and less than 3.0
+
+ On Ubuntu you can get modules from the repository:
+
+ .. code-block:: bash
+
+ # For test suite
+ sudo apt-get install python-daemon python-yaml python-argparse
+ # For documentation
+ sudo apt-get install python-jinja2 python-markdown
+
+
+ On CentOS too you can get modules from the repository:
+
+ .. code-block:: bash
+
+ sudo yum install python26 python26-PyYAML python26-argparse
+
+ But in general it is best to set up the modules by getting a tarball and
+ doing the setup with ``python setup.py``, thus:
+
+ .. code-block:: bash
+
+ # python module for parsing YAML (pyYAML): For test suite:
+ # (If wget fails, check the http://pyyaml.org/wiki/PyYAML
+ # to see what the current version is.)
+ cd ~
+ wget http://pyyaml.org/download/pyyaml/PyYAML-3.10.tar.gz
+ tar -xzf PyYAML-3.10.tar.gz
+ cd PyYAML-3.10
+ sudo python setup.py install
+
+ # python module for helping programs become daemons (daemon):
+ # For test suite: (if wget fails, check the
+ # http://pypi.python.org/pypi/python-daemon
+ # to see what the current version is.)
+ cd ~
+ wget http://pypi.python.org/packages/source/p/python-daemon/python-daemon-1.5.5.tar.gz
+ tar -xzvf python-daemon-1.5.5.tar.gz
+ cd python-daemon-1.5.5
+ sudo python setup.py install
+
+ # python module for text-to-html conversion (markdown):
+ # For documentation: (If wget fails, check the
+ # http://pypi.python.org/pypi/Markdown/
+ # to see what the current version is.)
+ cd ~
+ wget https://pypi.python.org/packages/source/M/Markdown/Markdown-2.3.1.tar.gz
+ tar -xzvf Markdown-2.3.1.tar.gz
+ cd Markdown-2.3.1
+ sudo python setup.py install
+
+ # python module which includes Jinja2 template engine:
+ # For documentation:
+ sudo pip install pelican
+
+ # python module for HTML scraping: For documentation:
+ cd ~
+ wget http://www.crummy.com/software/BeautifulSoup/bs3/download//3.x/BeautifulSoup-3.2.1.tar.gz
+ tar -xzvf BeautifulSoup-3.2.1.tar.gz
+ cd BeautifulSoup-3.2.1
+ sudo python setup.py install
+
+5. Use ``git`` again so that third-party contributions will be seen as well.
+ This step is only necessary once, the first time you do a download. There
+ is an alternative -- say ``git clone --recursive`` in step 3 -- but we
+ prefer this method because it works with older versions of ``git``.
+
+ .. code-block:: bash
+
+ cd ~/tarantool
+ git submodule init
+ git submodule update
+ cd ../
+
+ On rare occasions, the submodules will need to be updated again with the
+ command: ``git submodule update --init``.
+
+6. Use CMake to initiate the build.
+
+ .. code-block: bash
+
+ cd ~/tarantool
+ make clean # unnecessary, added for good luck
+ rm CMakeCache.txt # unnecessary, added for good luck
+ cmake . # Start build with build type=Debug, no doc
+
+ The option for specifying build type is ``-DCMAKE_BUILD_TYPE=<type>`` where
+ ``type = <None | Debug | Release | RelWithDebInfo | MinSizeRel>`` and a
+ reasonable choice for production is ``-DCMAKE_BUILD_TYPE=RelWithDebInfo``
+ (``Debug`` is used only by project maintainers and ``Release`` is used only
+ when the highest performance is required).
+
+ The option for asking to build documentation is ``-DENABLE_DOC=<true|false>``
+ and the assumption is that only a minority will need to rebuild the
+ documentation (such as what you're reading now), so details about
+ documentation are in the developer manual, and the reasonable choice
+ is ``-DENABLE_DOC=false`` or just don't use the ``-DENABLE_DOC`` clause at all.
+
+7. Use make to complete the build.
+
+ .. code-block:: bash
+
+ make
+
+ It's possible to say ``make install`` too, but that's not generally done.
+
+8. Run the test suite. This step is optional. |br| Tarantool's developers always
+ run the test suite before they publish new versions. You should run the test
+ suite too, if you make any changes in the code. Assuming you downloaded to
+ ``~/tarantool``, the principal steps are:
+
+ .. code-block:: bash
+
+ # make a subdirectory named `bin`
+ mkdir ~/tarantool/bin
+ # link python to bin (this may require superuser privilege)
+ ln /usr/bin/python ~/tarantool/bin/python
+ # get on the test subdirectory
+ cd ~/tarantool/test
+ # run tests using python
+ PATH=~/tarantool/bin:$PATH ./test-run.py
+
+
+ The output should contain reassuring reports, for example:
+
+ .. code-block:: bash
+
+ ======================================================================
+ TEST RESULT
+ ------------------------------------------------------------
+ box/bad_trigger.test.py [ pass ]
+ box/call.test.py [ pass ]
+ box/iproto.test.py [ pass ]
+ box/xlog.test.py [ pass ]
+ box/admin.test.lua [ pass ]
+ box/auth_access.test.lua [ pass ]
+ ... etc.
+
+ There are more than 70 tests in the suite.
+
+ To prevent later confusion, clean up what's in the `bin`
+ subdirectory:
+
+ .. code-block:: bash
+
+ rm ~/tarantool/bin/python
+ rmdir ~/tarantool/bin
+
+
+9. Make an rpm. |br| This step is optional. It's only for people who want to
+ redistribute Tarantool. Package maintainers who want to build with rpmbuild
+ should consult the
+ :doc:`Tarantool Developer Guide <index>`
+
+This is the end of the list of steps to take for source downloads.
+
+For your added convenience, github.com has README files with example scripts:
+
+* `README.CentOS <https://github.com/tarantool/tarantool/blob/master/README.CentOS>`_
+ for CentOS 5.8,
+* `README.FreeBSD <https://github.com/tarantool/tarantool/blob/master/README.FreeBSD>`_
+ for FreeBSD 8.3,
+* `README.MacOSX <https://github.com/tarantool/tarantool/blob/master/README.MacOSX>`_
+ for Mac OS X `Lion`,
+* `README.md <https://github.com/tarantool/tarantool/blob/master/README.md>`_
+ for generic GNU/Linux.
+
+These example scripts assume that the intent is to download from the master
+branch, build the server (but not the documentation), and run tests after build.
+
+To build with SUSE 13.1, the steps are as described above, except that the
+appropriate YaST2 package names are: binutils-devel, cmake, ncurses-devel,
+lynx, jing, libxml2-devel, docbook_5, saxon, libxslt-devel. |br|
+The python connector can be installed with ``sudo easy_install pip`` and ``sudo pip install tarantool``.
+
+===========================================================
+ How to build the XML manual
+===========================================================
+
+To build XML manual, you'll need:
+
+* xsltproc
+* docbook5-xml
+* docbook-xsl-ns
+* w3c-sgml-lib
+* libsaxon-java (for saxon processing)
+* libxml-commons-resolver1.1-java
+* libxml2-utils
+* libxerces2-java
+* libxslthl-java
+* lynx
+* jing
+
+When all pre-requisites are met, you should run:
+
+.. code-block:: bash
+
+ $ cmake . -DENABLE_DOC=YES
+
+to enable documentation builder.
+
+If you want to make tarantool user guide, you should run the
+following command from tarantool root directory:
+
+.. code-block:: bash
+
+ $ make html
+
+or
+
+.. code-block:: bash
+
+ $ cd doc/user
+ $ make
+
+The html version of the user guide will be genreated in doc/www/content/doc
diff --git a/doc/sphinx/dev_guide/c_style_guide.rst b/doc/sphinx/dev_guide/c_style_guide.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8203a76a2203c9edd0fe1a6350db889f36f5215b
--- /dev/null
+++ b/doc/sphinx/dev_guide/c_style_guide.rst
@@ -0,0 +1,1026 @@
+.. |br| raw:: html
+
+ <br />
+
+-------------------------------------------------------------------------------
+ C Style Guide
+-------------------------------------------------------------------------------
+
+The project's coding style is based on a version of the Linux kernel coding style.
+
+The latest version of the Linux style can be found at:
+http://www.kernel.org/doc/Documentation/CodingStyle
+
+Since it is open for changes, the version of style that we follow,
+one from 2007-July-13, will be also copied later in this document.
+
+There are a few additional guidelines, either unique
+to Tarantool or deviating from the Kernel guidelines.
+
+A. Chapters 10 "Kconfig configuration files", 11 "Data structures",
+ 13 "Printing kernel messages", 14 "Allocating memory" and 17
+ "Don't re-invent the kernel macros" do not apply, since they are
+ specific to Linux kernel programming environment.
+
+B. The rest of Linux Kernel Coding Style is amended as follows:
+
+===========================================================
+ General guidelines
+===========================================================
+
+We use Git for revision control. The latest development is happening in the
+'master' branch. Our git repository is hosted on github, and can be checked
+out with git clone git://github.com/tarantool/tarantool.git # anonymous read-only access
+
+If you have any questions about Tarantool internals, please post them on the
+developer discussion list, tarantool-developers@lists.launchpad.net. However,
+please be warned: Launchpad silently deletes posts from non-subscribed members,
+thus please be sure to have subscribed to the list prior to posting. Additionally,
+some engineers are always present on #tarantool channel on irc.freenode.net.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Commenting style
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use Doxygen comment format, Javadoc flavor, i.e. `@tag` rather than `\tag`.
+The main tags in use are @param, @retval, @return, @see, @note and @todo.
+
+Every function, except perhaps a very short and obvious one, should have a
+comment. A sample function comment may look like below:
+
+.. code-block:: c
+
+ /** Write all data to a descriptor.
+ *
+ * This function is equivalent to 'write', except it would ensure
+ * that all data is written to the file unless a non-ignorable
+ * error occurs.
+ *
+ * @retval 0 Success
+ *
+ * @reval 1 An error occurred (not EINTR)
+ * /
+ static int
+ write_all(int fd, void \*data, size_t len)
+
+Public structures and important structure members should be commented as well.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Header files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use header guards. Put the header guard in the first line in the header,
+before the copyright or declarations. Use all-uppercase name for the header
+guard. Derive the header guard name from the file name, and append _INCLUDED
+to get a macro name. For example, core/log_io.h -> CORE_LOG_IO_H_INCLUDED. In
+.c (implementation) file, include the respective declaration header before all
+other headers, to ensure that the header is self- sufficient. Header "header.h"
+is self-sufficient if the following compiles without errors:
+
+.. code-block:: c
+
+ #include "header.h"
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Allocating memory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Prefer the supplied slab (salloc) and pool (palloc) allocators to malloc()/free()
+for any performance-intensive or large memory allocations. Repetitive use of
+malloc()/free() can lead to memory fragmentation and should therefore be avoided.
+
+Always free all allocated memory, even allocated at start-up. We aim at being
+valgrind leak-check clean, and in most cases it's just as easy to free() the
+allocated memory as it is to write a valgrind suppression. Freeing all allocated
+memory is also dynamic-load friendly: assuming a plug-in can be dynamically loaded
+and unloaded multiple times, reload should not lead to a memory leak.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Other
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Select GNU C99 extensions are acceptable. It's OK to mix declarations and statements,
+use true and false.
+
+The not-so-current list of all GCC C extensions can be found at:
+http://gcc.gnu.org/onlinedocs/gcc-4.3.5/gcc/C-Extensions.html
+
+===========================================================
+ Linux kernel coding style
+===========================================================
+
+This is a short document describing the preferred coding style for the
+linux kernel. Coding style is very personal, and I won't _force_ my
+views on anybody, but this is what goes for anything that I have to be
+able to maintain, and I'd prefer it for most other things too. Please
+at least consider the points made here.
+
+First off, I'd suggest printing out a copy of the GNU coding standards,
+and NOT read it. Burn them, it's a great symbolic gesture.
+
+Anyway, here goes:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 1: Indentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Tabs are 8 characters, and thus indentations are also 8 characters.
+There are heretic movements that try to make indentations 4 (or even 2!)
+characters deep, and that is akin to trying to define the value of PI to
+be 3.
+
+Rationale: The whole idea behind indentation is to clearly define where
+a block of control starts and ends. Especially when you've been looking
+at your screen for 20 straight hours, you'll find it a lot easier to see
+how the indentation works if you have large indentations.
+
+Now, some people will claim that having 8-character indentations makes
+the code move too far to the right, and makes it hard to read on a
+80-character terminal screen. The answer to that is that if you need
+more than 3 levels of indentation, you're screwed anyway, and should fix
+your program.
+
+In short, 8-char indents make things easier to read, and have the added
+benefit of warning you when you're nesting your functions too deep.
+Heed that warning.
+
+The preferred way to ease multiple indentation levels in a switch statement is
+to align the "switch" and its subordinate "case" labels in the same column
+instead of "double-indenting" the "case" labels. e.g.:
+
+.. code-block:: c
+
+ switch (suffix) {
+ case 'G':
+ case 'g':
+ mem <<= 30;
+ break;
+ case 'M':
+ case 'm':
+ mem <<= 20;
+ break;
+ case 'K':
+ case 'k':
+ mem <<= 10;
+ /* fall through */
+ default:
+ break;
+ }
+
+
+Don't put multiple statements on a single line unless you have
+something to hide:
+
+.. code-block:: c
+
+ if (condition) do_this;
+ do_something_everytime;
+
+Don't put multiple assignments on a single line either. Kernel coding style
+is super simple. Avoid tricky expressions.
+
+Outside of comments, documentation and except in Kconfig, spaces are never
+used for indentation, and the above example is deliberately broken.
+
+Get a decent editor and don't leave whitespace at the end of lines.
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 2: Breaking long lines and strings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Coding style is all about readability and maintainability using commonly
+available tools.
+
+The limit on the length of lines is 80 columns and this is a strongly
+preferred limit.
+
+Statements longer than 80 columns will be broken into sensible chunks.
+Descendants are always substantially shorter than the parent and are placed
+substantially to the right. The same applies to function headers with a long
+argument list. Long strings are as well broken into shorter strings. The
+only exception to this is where exceeding 80 columns significantly increases
+readability and does not hide information.
+
+.. code-block:: c
+
+ void fun(int a, int b, int c)
+ {
+ if (condition)
+ printk(KERN_WARNING "Warning this is a long printk with "
+ "3 parameters a: %u b: %u "
+ "c: %u \n", a, b, c);
+ else
+ next_statement;
+ }
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 3: Placing Braces and Spaces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The other issue that always comes up in C styling is the placement of
+braces. Unlike the indent size, there are few technical reasons to
+choose one placement strategy over the other, but the preferred way, as
+shown to us by the prophets Kernighan and Ritchie, is to put the opening
+brace last on the line, and put the closing brace first, thusly:
+
+.. code-block:: c
+
+ if (x is true) {
+ we do y
+ }
+
+This applies to all non-function statement blocks (if, switch, for,
+while, do). e.g.:
+
+.. code-block:: c
+
+ switch (action) {
+ case KOBJ_ADD:
+ return "add";
+ case KOBJ_REMOVE:
+ return "remove";
+ case KOBJ_CHANGE:
+ return "change";
+ default:
+ return NULL;
+ }
+
+However, there is one special case, namely functions: they have the
+opening brace at the beginning of the next line, thus:
+
+.. code-block:: c
+
+ int function(int x)
+ {
+ body of function
+ }
+
+Heretic people all over the world have claimed that this inconsistency
+is ... well ... inconsistent, but all right-thinking people know that
+(a) K&R are _right_ and (b) K&R are right. Besides, functions are
+special anyway (you can't nest them in C).
+
+Note that the closing brace is empty on a line of its own, _except_ in
+the cases where it is followed by a continuation of the same statement,
+ie a "while" in a do-statement or an "else" in an if-statement, like
+this:
+
+.. code-block:: c
+
+ do {
+ body of do-loop
+ } while (condition);
+
+and
+
+.. code-block:: c
+
+ if (x == y) {
+ ..
+ } else if (x > y) {
+ ...
+ } else {
+ ....
+ }
+
+Rationale: K&R.
+
+Also, note that this brace-placement also minimizes the number of empty
+(or almost empty) lines, without any loss of readability. Thus, as the
+supply of new-lines on your screen is not a renewable resource (think
+25-line terminal screens here), you have more empty lines to put
+comments on.
+
+Do not unnecessarily use braces where a single statement will do.
+
+.. code-block:: c
+
+ if (condition)
+ action();
+
+This does not apply if one branch of a conditional statement is a single
+statement. Use braces in both branches.
+
+.. code-block:: c
+
+ if (condition) {
+ do_this();
+ do_that();
+ } else {
+ otherwise();
+ }
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 3.1: Spaces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Linux kernel style for use of spaces depends (mostly) on
+function-versus-keyword usage. Use a space after (most) keywords. The
+notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
+somewhat like functions (and are usually used with parentheses in Linux,
+although they are not required in the language, as in: "sizeof info" after
+"struct fileinfo info;" is declared).
+
+So use a space after these keywords: if, switch, case, for, do, while
+but not with sizeof, typeof, alignof, or __attribute__. E.g.,
+
+.. code-block:: c
+
+ s = sizeof(struct file);
+
+Do not add spaces around (inside) parenthesized expressions. This example is
+**bad**:
+
+.. code-block:: c
+
+ s = sizeof( struct file );
+
+When declaring pointer data or a function that returns a pointer type, the
+preferred use of '*' is adjacent to the data name or function name and not
+adjacent to the type name. Examples:
+
+.. code-block:: c
+
+ char *linux_banner;
+ unsigned long long memparse(char *ptr, char **retptr);
+ char *match_strdup(substring_t *s);
+
+Use one space around (on each side of) most binary and ternary operators,
+such as any of these:
+
+ = + - < > * / % | & ^ <= >= == != ? :
+
+but no space after unary operators:
+
+ & * + - ~ ! sizeof typeof alignof __attribute__ defined
+
+no space before the postfix increment & decrement unary operators:
+
+ ++ --
+
+no space after the prefix increment & decrement unary operators:
+
+ ++ --
+
+and no space around the '.' and "->" structure member operators.
+
+Do not leave trailing whitespace at the ends of lines. Some editors with
+"smart" indentation will insert whitespace at the beginning of new lines as
+appropriate, so you can start typing the next line of code right away.
+However, some such editors do not remove the whitespace if you end up not
+putting a line of code there, such as if you leave a blank line. As a result,
+you end up with lines containing trailing whitespace.
+
+Git will warn you about patches that introduce trailing whitespace, and can
+optionally strip the trailing whitespace for you; however, if applying a series
+of patches, this may make later patches in the series fail by changing their
+context lines.
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 4: Naming
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+C is a Spartan language, and so should your naming be. Unlike Modula-2
+and Pascal programmers, C programmers do not use cute names like
+ThisVariableIsATemporaryCounter. A C programmer would call that
+variable "tmp", which is much easier to write, and not the least more
+difficult to understand.
+
+HOWEVER, while mixed-case names are frowned upon, descriptive names for
+global variables are a must. To call a global function "foo" is a
+shooting offense.
+
+GLOBAL variables (to be used only if you _really_ need them) need to
+have descriptive names, as do global functions. If you have a function
+that counts the number of active users, you should call that
+"count_active_users()" or similar, you should _not_ call it "cntusr()".
+
+Encoding the type of a function into the name (so-called Hungarian
+notation) is brain damaged - the compiler knows the types anyway and can
+check those, and it only confuses the programmer. No wonder MicroSoft
+makes buggy programs.
+
+LOCAL variable names should be short, and to the point. If you have
+some random integer loop counter, it should probably be called "i".
+Calling it "loop_counter" is non-productive, if there is no chance of it
+being mis-understood. Similarly, "tmp" can be just about any type of
+variable that is used to hold a temporary value.
+
+If you are afraid to mix up your local variable names, you have another
+problem, which is called the function-growth-hormone-imbalance syndrome.
+See chapter 6 (Functions).
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 5: Typedefs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Please don't use things like "vps_t".
+
+It's a _mistake_ to use typedef for structures and pointers. When you see a
+
+.. code-block:: c
+
+ vps_t a;
+
+in the source, what does it mean?
+
+In contrast, if it says
+
+.. code-block:: c
+
+ struct virtual_container *a;
+
+you can actually tell what "a" is.
+
+Lots of people think that typedefs "help readability". Not so. They are
+useful only for:
+
+(a) totally opaque objects (where the typedef is actively used to _hide_
+ what the object is).
+
+ Example: "pte_t" etc. opaque objects that you can only access using
+ the proper accessor functions.
+
+ NOTE! Opaqueness and "accessor functions" are not good in themselves.
+ The reason we have them for things like pte_t etc. is that there
+ really is absolutely _zero_ portably accessible information there.
+
+(b) Clear integer types, where the abstraction _helps_ avoid confusion
+ whether it is "int" or "long".
+
+ u8/u16/u32 are perfectly fine typedefs, although they fit into
+ category (d) better than here.
+
+ NOTE! Again - there needs to be a _reason_ for this. If something is
+ "unsigned long", then there's no reason to do
+
+ .. code-block:: c
+
+ typedef unsigned long myflags_t;
+
+ but if there is a clear reason for why it under certain circumstances
+ might be an "unsigned int" and under other configurations might be
+ "unsigned long", then by all means go ahead and use a typedef.
+
+(c) when you use sparse to literally create a _new_ type for
+ type-checking.
+
+(d) New types which are identical to standard C99 types, in certain
+ exceptional circumstances.
+
+ Although it would only take a short amount of time for the eyes and
+ brain to become accustomed to the standard types like 'uint32_t',
+ some people object to their use anyway.
+
+ Therefore, the Linux-specific 'u8/u16/u32/u64' types and their
+ signed equivalents which are identical to standard types are
+ permitted -- although they are not mandatory in new code of your
+ own.
+
+ When editing existing code which already uses one or the other set
+ of types, you should conform to the existing choices in that code.
+
+(e) Types safe for use in userspace.
+
+ In certain structures which are visible to userspace, we cannot
+ require C99 types and cannot use the 'u32' form above. Thus, we
+ use __u32 and similar types in all structures which are shared
+ with userspace.
+
+Maybe there are other cases too, but the rule should basically be to NEVER
+EVER use a typedef unless you can clearly match one of those rules.
+
+In general, a pointer, or a struct that has elements that can reasonably
+be directly accessed should **never** be a typedef.
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 6: Functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Functions should be short and sweet, and do just one thing. They should
+fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
+as we all know), and do one thing and do that well.
+
+The maximum length of a function is inversely proportional to the
+complexity and indentation level of that function. So, if you have a
+conceptually simple function that is just one long (but simple)
+case-statement, where you have to do lots of small things for a lot of
+different cases, it's OK to have a longer function.
+
+However, if you have a complex function, and you suspect that a
+less-than-gifted first-year high-school student might not even
+understand what the function is all about, you should adhere to the
+maximum limits all the more closely. Use helper functions with
+descriptive names (you can ask the compiler to in-line them if you think
+it's performance-critical, and it will probably do a better job of it
+than you would have done).
+
+Another measure of the function is the number of local variables. They
+shouldn't exceed 5-10, or you're doing something wrong. Re-think the
+function, and split it into smaller pieces. A human brain can
+generally easily keep track of about 7 different things, anything more
+and it gets confu/sed. You know you're brilliant, but maybe you'd like
+to understand what you did 2 weeks from now.
+
+In source files, separate functions with one blank line. If the function is
+exported, the EXPORT* macro for it should follow immediately after the closing
+function brace line. E.g.:
+
+.. code-block:: c
+
+ int system_is_up(void)
+ {
+ return system_state == SYSTEM_RUNNING;
+ }
+ EXPORT_SYMBOL(system_is_up);
+
+In function prototypes, include parameter names with their data types.
+Although this is not required by the C language, it is preferred in Linux
+because it is a simple way to add valuable information for the reader.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 7: Centralized exiting of functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Albeit deprecated by some people, the equivalent of the goto statement is
+used frequently by compilers in form of the unconditional jump instruction.
+
+The goto statement comes in handy when a function exits from multiple
+locations and some common work such as cleanup has to be done.
+
+The rationale is:
+
+- unconditional statements are easier to understand and follow
+- nesting is reduced
+- errors by not updating individual exit points when making
+ modifications are prevented
+- saves the compiler work to optimize redundant code away ;)
+
+.. code-block:: c
+
+ int fun(int a)
+ {
+ int result = 0;
+ char *buffer = kmalloc(SIZE);
+
+ if (buffer == NULL)
+ return -ENOMEM;
+
+ if (condition1) {
+ while (loop1) {
+ ...
+ }
+ result = 1;
+ goto out;
+ }
+ ...
+ out:
+ kfree(buffer);
+ return result;
+ }
+
+ Chapter 8: Commenting
+
+Comments are good, but there is also a danger of over-commenting. NEVER
+try to explain HOW your code works in a comment: it's much better to
+write the code so that the _working_ is obvious, and it's a waste of
+time to explain badly written code.
+
+Generally, you want your comments to tell WHAT your code does, not HOW.
+Also, try to avoid putting comments inside a function body: if the
+function is so complex that you need to separately comment parts of it,
+you should probably go back to chapter 6 for a while. You can make
+small comments to note or warn about something particularly clever (or
+ugly), but try to avoid excess. Instead, put the comments at the head
+of the function, telling people what it does, and possibly WHY it does
+it.
+
+When commenting the kernel API functions, please use the kernel-doc format.
+See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc
+for details.
+
+Linux style for comments is the C89 `"/\* ... \*/"` style.
+Don't use C99-style `"// ..."` comments.
+
+The preferred style for long (multi-line) comments is:
+
+.. code-block:: c
+
+ /*
+ * This is the preferred style for multi-line
+ * comments in the Linux kernel source code.
+ * Please use it consistently.
+ *
+ * Description: A column of asterisks on the left side,
+ * with beginning and ending almost-blank lines.
+ */
+
+It's also important to comment data, whether they are basic types or derived
+types. To this end, use just one data declaration per line (no commas for
+multiple data declarations). This leaves you room for a small comment on each
+item, explaining its use.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 9: You've made a mess of it
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+That's OK, we all do. You've probably been told by your long-time Unix
+user helper that "GNU emacs" automatically formats the C sources for
+you, and you've noticed that yes, it does do that, but the defaults it
+uses are less than desirable (in fact, they are worse than random
+typing - an infinite number of monkeys typing into GNU emacs would never
+make a good program).
+
+So, you can either get rid of GNU emacs, or change it to use saner
+values. To do the latter, you can stick the following in your .emacs file:
+
+.. code-block:: c
+
+ (defun c-lineup-arglist-tabs-only (ignored)
+ "Line up argument lists by tabs, not spaces"
+ (let* ((anchor (c-langelem-pos c-syntactic-element))
+ (column (c-langelem-2nd-pos c-syntactic-element))
+ (offset (- (1+ column) anchor))
+ (steps (floor offset c-basic-offset)))
+ (* (max steps 1)
+ c-basic-offset)))
+
+ (add-hook 'c-mode-common-hook
+ (lambda ()
+ ;; Add kernel style
+ (c-add-style
+ "linux-tabs-only"
+ '("linux" (c-offsets-alist
+ (arglist-cont-nonempty
+ c-lineup-gcc-asm-reg
+ c-lineup-arglist-tabs-only))))))
+
+ (add-hook 'c-mode-hook
+ (lambda ()
+ (let ((filename (buffer-file-name)))
+ ;; Enable kernel mode for the appropriate files
+ (when (and filename
+ (string-match (expand-file-name "~/src/linux-trees")
+ filename))
+ (setq indent-tabs-mode t)
+ (c-set-style "linux-tabs-only")))))
+
+This will make emacs go better with the kernel coding style for C
+files below ~/src/linux-trees.
+
+But even if you fail in getting emacs to do sane formatting, not
+everything is lost: use "indent".
+
+Now, again, GNU indent has the same brain-dead settings that GNU emacs
+has, which is why you need to give it a few command line options.
+However, that's not too bad, because even the makers of GNU indent
+recognize the authority of K&R (the GNU people aren't evil, they are
+just severely misguided in this matter), so you just give indent the
+options "-kr -i8" (stands for "K&R, 8 character indents"), or use
+"scripts/Lindent", which indents in the latest style.
+
+"indent" has a lot of options, and especially when it comes to comment
+re-formatting you may want to take a look at the man page. But
+remember: "indent" is not a fix for bad programming.
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 10: Kconfig configuration files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For all of the Kconfig* configuration files throughout the source tree,
+the indentation is somewhat different. Lines under a "config" definition
+are indented with one tab, while help text is indented an additional two
+spaces. Example:
+
+.. code-block:: c
+
+ config AUDIT
+ bool "Auditing support"
+ depends on NET
+ help
+ Enable auditing infrastructure that can be used with another
+ kernel subsystem, such as SELinux (which requires this for
+ logging of avc messages output). Does not do system-call
+ auditing without CONFIG_AUDITSYSCALL.
+
+Features that might still be considered unstable should be defined as
+dependent on "EXPERIMENTAL":
+
+.. code-block:: c
+
+ config SLUB
+ depends on EXPERIMENTAL && !ARCH_USES_SLAB_PAGE_STRUCT
+ bool "SLUB (Unqueued Allocator)"
+ ...
+
+while seriously dangerous features (such as write support for certain
+filesystems) should advertise this prominently in their prompt string:
+
+.. code-block:: c
+
+ config ADFS_FS_RW
+ bool "ADFS write support (DANGEROUS)"
+ depends on ADFS_FS
+ ...
+
+For full documentation on the configuration files, see the file
+Documentation/kbuild/kconfig-language.txt.
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 11: Data structures
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Data structures that have visibility outside the single-threaded
+environment they are created and destroyed in should always have
+reference counts. In the kernel, garbage collection doesn't exist (and
+outside the kernel garbage collection is slow and inefficient), which
+means that you absolutely _have_ to reference count all your uses.
+
+Reference counting means that you can avoid locking, and allows multiple
+users to have access to the data structure in parallel - and not having
+to worry about the structure suddenly going away from under them just
+because they slept or did something else for a while.
+
+Note that locking is _not_ a replacement for reference counting.
+Locking is used to keep data structures coherent, while reference
+counting is a memory management technique. Usually both are needed, and
+they are not to be confused with each other.
+
+Many data structures can indeed have two levels of reference counting,
+when there are users of different "classes". The subclass count counts
+the number of subclass users, and decrements the global count just once
+when the subclass count goes to zero.
+
+Examples of this kind of "multi-level-reference-counting" can be found in
+memory management ("struct mm_struct": mm_users and mm_count), and in
+filesystem code ("struct super_block": s_count and s_active).
+
+Remember: if another thread can find your data structure, and you don't
+have a reference count on it, you almost certainly have a bug.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 12: Macros, Enums and RTL
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Names of macros defining constants and labels in enums are capitalized.
+
+.. code-block:: c
+
+ #define CONSTANT 0x12345
+
+Enums are preferred when defining several related constants.
+
+CAPITALIZED macro names are appreciated but macros resembling functions
+may be named in lower case.
+
+Generally, inline functions are preferable to macros resembling functions.
+
+Macros with multiple statements should be enclosed in a do - while block:
+
+.. code-block:: c
+
+ #define macrofun(a, b, c) \
+ do { \
+ if (a == 5) \
+ do_this(b, c); \
+ } while (0)
+
+Things to avoid when using macros:
+
+1. macros that affect control flow:
+
+ .. code-block:: c
+
+ #define FOO(x) \
+ do { \
+ if (blah(x) < 0) \
+ return -EBUGGERED; \
+ } while(0)
+
+ is a _very_ bad idea. It looks like a function call but exits the "calling"
+ function; don't break the internal parsers of those who will read the code.
+
+2. macros that depend on having a local variable with a magic name:
+
+ .. code-block:: c
+
+ #define FOO(val) bar(index, val)
+
+ might look like a good thing, but it's confusing as hell when one reads the
+ code and it's prone to breakage from seemingly innocent changes.
+
+3. macros with arguments that are used as l-values: FOO(x) = y; will
+ bite you if somebody e.g. turns FOO into an inline function.
+
+4. forgetting about precedence: macros defining constants using expressions
+ must enclose the expression in parentheses. Beware of similar issues with
+ macros using parameters.
+
+ .. code-block:: c
+
+ #define CONSTANT 0x4000
+ #define CONSTEXP (CONSTANT | 3)
+
+ The cpp manual deals with macros exhaustively. The gcc internals manual also
+ covers RTL which is used frequently with assembly language in the kernel.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 13: Printing kernel messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Kernel developers like to be seen as literate. Do mind the spelling
+of kernel messages to make a good impression. Do not use crippled
+words like "dont"; use "do not" or "don't" instead. Make the messages
+concise, clear, and unambiguous.
+
+Kernel messages do not have to be terminated with a period.
+
+Printing numbers in parentheses (%d) adds no value and should be avoided.
+
+There are a number of driver model diagnostic macros in <linux/device.h>
+which you should use to make sure messages are matched to the right device
+and driver, and are tagged with the right level: dev_err(), dev_warn(),
+dev_info(), and so forth. For messages that aren't associated with a
+particular device, <linux/kernel.h> defines pr_debug() and pr_info().
+
+Coming up with good debugging messages can be quite a challenge; and once
+you have them, they can be a huge help for remote troubleshooting. Such
+messages should be compiled out when the DEBUG symbol is not defined (that
+is, by default they are not included). When you use dev_dbg() or pr_debug(),
+that's automatic. Many subsystems have Kconfig options to turn on -DDEBUG.
+A related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to the
+ones already enabled by DEBUG.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 14: Allocating memory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The kernel provides the following general purpose memory allocators:
+kmalloc(), kzalloc(), kcalloc(), and vmalloc(). Please refer to the API
+documentation for further information about them.
+
+The preferred form for passing a size of a struct is the following:
+
+.. code-block:: c
+
+ p = kmalloc(sizeof(*p), ...);
+
+The alternative form where struct name is spelled out hurts readability and
+introduces an opportunity for a bug when the pointer variable type is changed
+but the corresponding sizeof that is passed to a memory allocator is not.
+
+Casting the return value which is a void pointer is redundant. The conversion
+from void pointer to any other pointer type is guaranteed by the C programming
+language.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 15: The inline disease
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There appears to be a common misperception that gcc has a magic "make me
+faster" speedup option called "inline". While the use of inlines can be
+appropriate (for example as a means of replacing macros, see Chapter 12), it
+very often is not. Abundant use of the inline keyword leads to a much bigger
+kernel, which in turn slows the system as a whole down, due to a bigger
+icache footprint for the CPU and simply because there is less memory
+available for the pagecache. Just think about it; a pagecache miss causes a
+disk seek, which easily takes 5 milliseconds. There are a LOT of cpu cycles
+that can go into these 5 milliseconds.
+
+A reasonable rule of thumb is to not put inline at functions that have more
+than 3 lines of code in them. An exception to this rule are the cases where
+a parameter is known to be a compiletime constant, and as a result of this
+constantness you *know* the compiler will be able to optimize most of your
+function away at compile time. For a good example of this later case, see
+the kmalloc() inline function.
+
+Often people argue that adding inline to functions that are static and used
+only once is always a win since there is no space tradeoff. While this is
+technically correct, gcc is capable of inlining these automatically without
+help, and the maintenance issue of removing the inline when a second user
+appears outweighs the potential value of the hint that tells gcc to do
+something it would have done anyway.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 16: Function return values and names
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Functions can return values of many different kinds, and one of the
+most common is a value indicating whether the function succeeded or
+failed. Such a value can be represented as an error-code integer
+(-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure,
+non-zero = success).
+
+Mixing up these two sorts of representations is a fertile source of
+difficult-to-find bugs. If the C language included a strong distinction
+between integers and booleans then the compiler would find these mistakes
+for us... but it doesn't. To help prevent such bugs, always follow this
+convention:
+
+::
+
+ If the name of a function is an action or an imperative command,
+ the function should return an error-code integer. If the name
+ is a predicate, the function should return a "succeeded" boolean.
+
+For example, "add work" is a command, and the add_work() function returns 0
+for success or -EBUSY for failure. In the same way, "PCI device present" is
+a predicate, and the pci_dev_present() function returns 1 if it succeeds in
+finding a matching device or 0 if it doesn't.
+
+All EXPORTed functions must respect this convention, and so should all
+public functions. Private (static) functions need not, but it is
+recommended that they do.
+
+Functions whose return value is the actual result of a computation, rather
+than an indication of whether the computation succeeded, are not subject to
+this rule. Generally they indicate failure by returning some out-of-range
+result. Typical examples would be functions that return pointers; they use
+NULL or the ERR_PTR mechanism to report failure.
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 17: Don't re-invent the kernel macros
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The header file include/linux/kernel.h contains a number of macros that
+you should use, rather than explicitly coding some variant of them yourself.
+For example, if you need to calculate the length of an array, take advantage
+of the macro
+
+.. code-block:: c
+
+ #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
+
+Similarly, if you need to calculate the size of some structure member, use
+
+.. code-block:: c
+
+ #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
+
+There are also min() and max() macros that do strict type checking if you
+need them. Feel free to peruse that header file to see what else is already
+defined that you shouldn't reproduce in your code.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Chapter 18: Editor modelines and other cruft
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some editors can interpret configuration information embedded in source files,
+indicated with special markers. For example, emacs interprets lines marked
+like this:
+
+.. code-block:: c
+
+ -*- mode: c -*-
+
+Or like this:
+
+.. code-block:: c
+
+ /*
+ Local Variables:
+ compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
+ End:
+ */
+
+Vim interprets markers that look like this:
+
+.. code-block:: c
+
+ /* vim:set sw=8 noet */
+
+Do not include any of these in source files. People have their own personal
+editor configurations, and your source files should not override them. This
+includes markers for indentation and mode configuration. People may use their
+own custom mode, or may have some other magic method for making indentation
+work correctly.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Appendix I: References
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* `The C Programming Language, Second Edition <http://cm.bell-labs.com/cm/cs/cbook/>`_
+ by Brian W. Kernighan and Dennis M. Ritchie. |br|
+ Prentice Hall, Inc., 1988. |br|
+ ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
+
+* `The Practice of Programming <http://cm.bell-labs.com/cm/cs/tpop/>`_
+ by Brian W. Kernighan and Rob Pike. |br|
+ Addison-Wesley, Inc., 1999. |br|
+ ISBN 0-201-61586-X.
+
+* `GNU manuals <http://www.gnu.org/manual/>`_ - where in compliance with K&R and this text - for **cpp**, **gcc**,
+ **gcc internals** and **indent**
+
+* `WG14 International standardization workgroup for the programming
+ language C <http://www.open-std.org/JTC1/SC22/WG14/>`_
+
+* `Kernel CodingStyle, by greg@kroah.com at OLS 2002
+ <http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/>`_
diff --git a/doc/coding-style.txt b/doc/sphinx/dev_guide/coding-style.txt
similarity index 100%
rename from doc/coding-style.txt
rename to doc/sphinx/dev_guide/coding-style.txt
diff --git a/doc/sphinx/dev_guide/developer_guidelines.rst b/doc/sphinx/dev_guide/developer_guidelines.rst
new file mode 100644
index 0000000000000000000000000000000000000000..22703e431f4d0e37ec2e9eecc8bdae0965a5a148
--- /dev/null
+++ b/doc/sphinx/dev_guide/developer_guidelines.rst
@@ -0,0 +1,26 @@
+-------------------------------------------------------------------------------
+ Developer guidelines
+-------------------------------------------------------------------------------
+
+===========================================================
+ How to work on a bug
+===========================================================
+
+Any defect, even minor, if it changes the user-visible server behavior, needs
+a bug report. Report a bug at http://github.com/tarantool/tarantool/issues.
+
+When reporting a bug, try to come up with a test case right away. Set the
+current maintenance milestone for the bug fix, and specify the series.
+Assign the bug to yourself. Put the status to 'In progress' Once the patch is
+ready, put the bug the bug to 'In review' and solicit a review for the fix.
+
+Once there is a positive code review, push the patch and set the status to 'Closed'
+
+Patches for bugs should contain a reference to the respective Launchpad bug page or
+at least bug id. Each patch should have a test, unless coming up with one is
+difficult in the current framework, in which case QA should be alerted.
+
+There are two things you need to do when your patch makes it into the master:
+
+* put the bug to 'fix committed',
+* delete the remote branch.
diff --git a/doc/sphinx/dev_guide/index.rst b/doc/sphinx/dev_guide/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..6b26fe9bdedb18d2522d4ec75635b8ed13fa2c6f
--- /dev/null
+++ b/doc/sphinx/dev_guide/index.rst
@@ -0,0 +1,14 @@
+-------------------------------------------------------------------------------
+ Contributing
+-------------------------------------------------------------------------------
+
+.. toctree::
+ :maxdepth: 1
+
+ intro
+ building_from_source
+ developer_guidelines
+ box-protocol
+ c_style_guide
+ python_style_guide
+ release_management
diff --git a/doc/sphinx/dev_guide/intro.rst b/doc/sphinx/dev_guide/intro.rst
new file mode 100644
index 0000000000000000000000000000000000000000..2c6e71a701a5ab2b968a13ca9c8f9badce1758db
--- /dev/null
+++ b/doc/sphinx/dev_guide/intro.rst
@@ -0,0 +1,12 @@
+-------------------------------------------------------------------------------
+ What documentation there is
+-------------------------------------------------------------------------------
+
+Tarantool documentation consists of:
+
+* a user guide
+* developer guide (you're reading it)
+* coding stryle guide for C, Python (for other connectors,
+ we use conventions of the connector programming language community)
+
+
diff --git a/doc/sphinx/dev_guide/python_style_guide.rst b/doc/sphinx/dev_guide/python_style_guide.rst
new file mode 100644
index 0000000000000000000000000000000000000000..676dc9685476c55fc6ad66e30df47393bd6e5336
--- /dev/null
+++ b/doc/sphinx/dev_guide/python_style_guide.rst
@@ -0,0 +1,805 @@
+-------------------------------------------------------------------------------
+ Python Style Guide
+-------------------------------------------------------------------------------
+
+===========================================================
+ Introduction
+===========================================================
+
+This document gives coding conventions for the Python code comprising
+the standard library in the main Python distribution. Please see the
+companion informational PEP describing style guidelines for the C code
+in the C implementation of Python [1]_.
+
+This document and PEP 257 (Docstring Conventions) were adapted from
+Guido's original Python Style Guide essay, with some additions from
+Barry's style guide [2]_.
+
+
+===========================================================
+ A Foolish Consistency is the Hobgoblin of Little Minds
+===========================================================
+
+One of Guido's key insights is that code is read much more often than
+it is written. The guidelines provided here are intended to improve
+the readability of code and make it consistent across the wide
+spectrum of Python code. As PEP 20 says, "Readability counts".
+
+A style guide is about consistency. Consistency with this style guide
+is important. Consistency within a project is more important.
+Consistency within one module or function is the most important.
+
+But most importantly: know when to be inconsistent -- sometimes the
+style guide just doesn't apply. When in doubt, use your best
+judgment. Look at other examples and decide what looks best. And
+don't hesitate to ask!
+
+Two good reasons to break a particular rule:
+
+1. When applying the rule would make the code less readable, even for
+ someone who is used to reading code that follows the rules.
+
+2. To be consistent with surrounding code that also breaks it (maybe
+ for historic reasons) -- although this is also an opportunity to
+ clean up someone else's mess (in true XP style).
+
+
+======================================================
+ Code lay-out
+======================================================
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Indentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use 4 spaces per indentation level.
+
+For really old code that you don't want to mess up, you can continue
+to use 8-space tabs.
+
+Continuation lines should align wrapped elements either vertically
+using Python's implicit line joining inside parentheses, brackets and
+braces, or using a hanging indent. When using a hanging indent the
+following considerations should be applied; there should be no
+arguments on the first line and further indentation should be used to
+clearly distinguish itself as a continuation line.
+
+Yes::
+
+ # Aligned with opening delimiter
+ foo = long_function_name(var_one, var_two,
+ var_three, var_four)
+
+ # More indentation included to distinguish this from the rest.
+ def long_function_name(
+ var_one, var_two, var_three,
+ var_four):
+ print(var_one)
+
+No::
+
+ # Arguments on first line forbidden when not using vertical alignment
+ foo = long_function_name(var_one, var_two,
+ var_three, var_four)
+
+ # Further indentation required as indentation is not distinguishable
+ def long_function_name(
+ var_one, var_two, var_three,
+ var_four):
+ print(var_one)
+
+Optional::
+
+ # Extra indentation is not necessary.
+ foo = long_function_name(
+ var_one, var_two,
+ var_three, var_four)
+
+The closing brace/bracket/parenthesis on multi-line constructs may
+either line up under the first non-whitespace character of the last
+line of list, as in::
+
+ my_list = [
+ 1, 2, 3,
+ 4, 5, 6,
+ ]
+ result = some_function_that_takes_arguments(
+ 'a', 'b', 'c',
+ 'd', 'e', 'f',
+ )
+
+or it may be lined up under the first character of the line that
+starts the multi-line construct, as in::
+
+ my_list = [
+ 1, 2, 3,
+ 4, 5, 6,
+ ]
+ result = some_function_that_takes_arguments(
+ 'a', 'b', 'c',
+ 'd', 'e', 'f',
+ )
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Tabs or Spaces?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Never mix tabs and spaces.
+
+The most popular way of indenting Python is with spaces only. The
+second-most popular way is with tabs only. Code indented with a
+mixture of tabs and spaces should be converted to using spaces
+exclusively. When invoking the Python command line interpreter with
+the ``-t`` option, it issues warnings about code that illegally mixes
+tabs and spaces. When using ``-tt`` these warnings become errors.
+These options are highly recommended!
+
+For new projects, spaces-only are strongly recommended over tabs.
+Most editors have features that make this easy to do.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Maximum Line Length
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Limit all lines to a maximum of 79 characters.
+
+There are still many devices around that are limited to 80 character
+lines; plus, limiting windows to 80 characters makes it possible to
+have several windows side-by-side. The default wrapping on such
+devices disrupts the visual structure of the code, making it more
+difficult to understand. Therefore, please limit all lines to a
+maximum of 79 characters. For flowing long blocks of text (docstrings
+or comments), limiting the length to 72 characters is recommended.
+
+The preferred way of wrapping long lines is by using Python's implied
+line continuation inside parentheses, brackets and braces. Long lines
+can be broken over multiple lines by wrapping expressions in
+parentheses. These should be used in preference to using a backslash
+for line continuation.
+
+Backslashes may still be appropriate at times. For example, long,
+multiple ``with``-statements cannot use implicit continuation, so
+backslashes are acceptable::
+
+ with open('/path/to/some/file/you/want/to/read') as file_1, \
+ open('/path/to/some/file/being/written', 'w') as file_2:
+ file_2.write(file_1.read())
+
+Another such case is with ``assert`` statements.
+
+Make sure to indent the continued line appropriately. The preferred
+place to break around a binary operator is *after* the operator, not
+before it. Some examples::
+
+ class Rectangle(Blob):
+
+ def __init__(self, width, height,
+ color='black', emphasis=None, highlight=0):
+ if (width == 0 and height == 0 and
+ color == 'red' and emphasis == 'strong' or
+ highlight > 100):
+ raise ValueError("sorry, you lose")
+ if width == 0 and height == 0 and (color == 'red' or
+ emphasis is None):
+ raise ValueError("I don't think so -- values are %s, %s" %
+ (width, height))
+ Blob.__init__(self, width, height,
+ color, emphasis, highlight)
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Blank Lines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Separate top-level function and class definitions with two blank
+lines.
+
+Method definitions inside a class are separated by a single blank
+line.
+
+Extra blank lines may be used (sparingly) to separate groups of
+related functions. Blank lines may be omitted between a bunch of
+related one-liners (e.g. a set of dummy implementations).
+
+Use blank lines in functions, sparingly, to indicate logical sections.
+
+Python accepts the control-L (i.e. ^L) form feed character as
+whitespace; Many tools treat these characters as page separators, so
+you may use them to separate pages of related sections of your file.
+Note, some editors and web-based code viewers may not recognize
+control-L as a form feed and will show another glyph in its place.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Encodings (PEP 263)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Code in the core Python distribution should always use the ASCII or
+Latin-1 encoding (a.k.a. ISO-8859-1). For Python 3.0 and beyond,
+UTF-8 is preferred over Latin-1, see PEP 3120.
+
+Files using ASCII should not have a coding cookie. Latin-1 (or UTF-8)
+should only be used when a comment or docstring needs to mention an
+author name that requires Latin-1; otherwise, using ``\x``, ``\u`` or
+``\U`` escapes is the preferred way to include non-ASCII data in
+string literals.
+
+For Python 3.0 and beyond, the following policy is prescribed for the
+standard library (see PEP 3131): All identifiers in the Python
+standard library MUST use ASCII-only identifiers, and SHOULD use
+English words wherever feasible (in many cases, abbreviations and
+technical terms are used which aren't English). In addition, string
+literals and comments must also be in ASCII. The only exceptions are
+(a) test cases testing the non-ASCII features, and
+(b) names of authors. Authors whose names are not based on the
+latin alphabet MUST provide a latin transliteration of their
+names.
+
+Open source projects with a global audience are encouraged to adopt a
+similar policy.
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Imports
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Imports should usually be on separate lines, e.g.::
+
+ Yes: import os
+ import sys
+
+ No: import sys, os
+
+ It's okay to say this though::
+
+ from subprocess import Popen, PIPE
+
+- Imports are always put at the top of the file, just after any module
+ comments and docstrings, and before module globals and constants.
+
+ Imports should be grouped in the following order:
+
+ 1. standard library imports
+ 2. related third party imports
+ 3. local application/library specific imports
+
+ You should put a blank line between each group of imports.
+
+ Put any relevant ``__all__`` specification after the imports.
+
+- Relative imports for intra-package imports are highly discouraged.
+ Always use the absolute package path for all imports. Even now that
+ PEP 328 is fully implemented in Python 2.5, its style of explicit
+ relative imports is actively discouraged; absolute imports are more
+ portable and usually more readable.
+
+- When importing a class from a class-containing module, it's usually
+ okay to spell this::
+
+ from myclass import MyClass
+ from foo.bar.yourclass import YourClass
+
+ If this spelling causes local name clashes, then spell them ::
+
+ import myclass
+ import foo.bar.yourclass
+
+ and use "myclass.MyClass" and "foo.bar.yourclass.YourClass".
+
+
+=================================================
+ Whitespace in Expressions and Statements
+=================================================
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Pet Peeves
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Avoid extraneous whitespace in the following situations:
+
+- Immediately inside parentheses, brackets or braces. ::
+
+ Yes: spam(ham[1], {eggs: 2})
+ No: spam( ham[ 1 ], { eggs: 2 } )
+
+- Immediately before a comma, semicolon, or colon::
+
+ Yes: if x == 4: print x, y; x, y = y, x
+ No: if x == 4 : print x , y ; x , y = y , x
+
+- Immediately before the open parenthesis that starts the argument
+ list of a function call::
+
+ Yes: spam(1)
+ No: spam (1)
+
+- Immediately before the open parenthesis that starts an indexing or
+ slicing::
+
+ Yes: dict['key'] = list[index]
+ No: dict ['key'] = list [index]
+
+- More than one space around an assignment (or other) operator to
+ align it with another.
+
+ Yes::
+
+ x = 1
+ y = 2
+ long_variable = 3
+
+ No::
+
+ x = 1
+ y = 2
+ long_variable = 3
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Other Recommendations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Always surround these binary operators with a single space on either
+ side: assignment (``=``), augmented assignment (``+=``, ``-=``
+ etc.), comparisons (``==``, ``<``, ``>``, ``!=``, ``<>``, ``<=``,
+ ``>=``, ``in``, ``not in``, ``is``, ``is not``), Booleans (``and``,
+ ``or``, ``not``).
+
+- If operators with different priorities are used, consider adding
+ whitespace around the operators with the lowest priority(ies). Use
+ your own judgement; however, never use more than one space, and
+ always have the same amount of whitespace on both sides of a binary
+ operator.
+
+ Yes::
+
+ i = i + 1
+ submitted += 1
+ x = x*2 - 1
+ hypot2 = x*x + y*y
+ c = (a+b) * (a-b)
+
+ No::
+
+ i=i+1
+ submitted +=1
+ x = x * 2 - 1
+ hypot2 = x * x + y * y
+ c = (a + b) * (a - b)
+
+- Don't use spaces around the ``=`` sign when used to indicate a
+ keyword argument or a default parameter value.
+
+ Yes::
+
+ def complex(real, imag=0.0):
+ return magic(r=real, i=imag)
+
+ No::
+
+ def complex(real, imag = 0.0):
+ return magic(r = real, i = imag)
+
+- Compound statements (multiple statements on the same line) are
+ generally discouraged.
+
+ Yes::
+
+ if foo == 'blah':
+ do_blah_thing()
+ do_one()
+ do_two()
+ do_three()
+
+ Rather not::
+
+ if foo == 'blah': do_blah_thing()
+ do_one(); do_two(); do_three()
+
+- While sometimes it's okay to put an if/for/while with a small body
+ on the same line, never do this for multi-clause statements. Also
+ avoid folding such long lines!
+
+ Rather not::
+
+ if foo == 'blah': do_blah_thing()
+ for x in lst: total += x
+ while t < 10: t = delay()
+
+ Definitely not::
+
+ if foo == 'blah': do_blah_thing()
+ else: do_non_blah_thing()
+
+ try: something()
+ finally: cleanup()
+
+ do_one(); do_two(); do_three(long, argument,
+ list, like, this)
+
+ if foo == 'blah': one(); two(); three()
+
+=================================================
+ Comments
+=================================================
+
+Comments that contradict the code are worse than no comments. Always
+make a priority of keeping the comments up-to-date when the code
+changes!
+
+Comments should be complete sentences. If a comment is a phrase or
+sentence, its first word should be capitalized, unless it is an
+identifier that begins with a lower case letter (never alter the case
+of identifiers!).
+
+If a comment is short, the period at the end can be omitted. Block
+comments generally consist of one or more paragraphs built out of
+complete sentences, and each sentence should end in a period.
+
+You should use two spaces after a sentence-ending period.
+
+When writing English, Strunk and White apply.
+
+Python coders from non-English speaking countries: please write your
+comments in English, unless you are 120% sure that the code will never
+be read by people who don't speak your language.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Block Comments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Block comments generally apply to some (or all) code that follows
+them, and are indented to the same level as that code. Each line of a
+block comment starts with a ``#`` and a single space (unless it is
+indented text inside the comment).
+
+Paragraphs inside a block comment are separated by a line containing a
+single ``#``.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Inline Comments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use inline comments sparingly.
+
+An inline comment is a comment on the same line as a statement.
+Inline comments should be separated by at least two spaces from the
+statement. They should start with a # and a single space.
+
+Inline comments are unnecessary and in fact distracting if they state
+the obvious. Don't do this::
+
+ x = x + 1 # Increment x
+
+But sometimes, this is useful::
+
+ x = x + 1 # Compensate for border
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Documentation Strings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Conventions for writing good documentation strings
+(a.k.a. "docstrings") are immortalized in PEP 257.
+
+- Write docstrings for all public modules, functions, classes, and
+ methods. Docstrings are not necessary for non-public methods, but
+ you should have a comment that describes what the method does. This
+ comment should appear after the ``def`` line.
+
+- PEP 257 describes good docstring conventions. Note that most
+ importantly, the ``"""`` that ends a multiline docstring should be
+ on a line by itself, and preferably preceded by a blank line, e.g.::
+
+ """Return a foobang
+
+ Optional plotz says to frobnicate the bizbaz first.
+
+ """
+
+- For one liner docstrings, it's okay to keep the closing ``"""`` on
+ the same line.
+
+
+=================================================
+ Version Bookkeeping
+=================================================
+
+If you have to have Subversion, CVS, or RCS crud in your source file,
+do it as follows. ::
+
+ __version__ = "$Revision$"
+ # $Source$
+
+These lines should be included after the module's docstring, before
+any other code, separated by a blank line above and below.
+
+
+=================================================
+ Naming Conventions
+=================================================
+
+The naming conventions of Python's library are a bit of a mess, so
+we'll never get this completely consistent -- nevertheless, here are
+the currently recommended naming standards. New modules and packages
+(including third party frameworks) should be written to these
+standards, but where an existing library has a different style,
+internal consistency is preferred.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Descriptive: Naming Styles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are a lot of different naming styles. It helps to be able to
+recognize what naming style is being used, independently from what
+they are used for.
+
+The following naming styles are commonly distinguished:
+
+- ``b`` (single lowercase letter)
+- ``B`` (single uppercase letter)
+- ``lowercase``
+- ``lower_case_with_underscores``
+- ``UPPERCASE``
+- ``UPPER_CASE_WITH_UNDERSCORES``
+- ``CapitalizedWords`` (or CapWords, or CamelCase -- so named because
+ of the bumpy look of its letters [3]_). This is also sometimes known
+ as StudlyCaps.
+
+ Note: When using abbreviations in CapWords, capitalize all the
+ letters of the abbreviation. Thus HTTPServerError is better than
+ HttpServerError.
+- ``mixedCase`` (differs from CapitalizedWords by initial lowercase
+ character!)
+- ``Capitalized_Words_With_Underscores`` (ugly!)
+
+There's also the style of using a short unique prefix to group related
+names together. This is not used much in Python, but it is mentioned
+for completeness. For example, the ``os.stat()`` function returns a
+tuple whose items traditionally have names like ``st_mode``,
+``st_size``, ``st_mtime`` and so on. (This is done to emphasize the
+correspondence with the fields of the POSIX system call struct, which
+helps programmers familiar with that.)
+
+The X11 library uses a leading X for all its public functions. In
+Python, this style is generally deemed unnecessary because attribute
+and method names are prefixed with an object, and function names are
+prefixed with a module name.
+
+In addition, the following special forms using leading or trailing
+underscores are recognized (these can generally be combined with any
+case convention):
+
+- ``_single_leading_underscore``: weak "internal use" indicator.
+ E.g. ``from M import *`` does not import objects whose name starts
+ with an underscore.
+
+- ``single_trailing_underscore_``: used by convention to avoid
+ conflicts with Python keyword, e.g. ::
+
+ Tkinter.Toplevel(master, class_='ClassName')
+
+- ``__double_leading_underscore``: when naming a class attribute,
+ invokes name mangling (inside class FooBar, ``__boo`` becomes
+ ``_FooBar__boo``; see below).
+
+- ``__double_leading_and_trailing_underscore__``: "magic" objects or
+ attributes that live in user-controlled namespaces.
+ E.g. ``__init__``, ``__import__`` or ``__file__``. Never invent
+ such names; only use them as documented.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Prescriptive: Naming Conventions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+#######################################
+ Names to Avoid
+#######################################
+
+Never use the characters 'l' (lowercase letter el), 'O' (uppercase
+letter oh), or 'I' (uppercase letter eye) as single character variable
+names.
+
+In some fonts, these characters are indistinguishable from the
+numerals one and zero. When tempted to use 'l', use 'L' instead.
+
+#######################################
+ Package and Module Names
+#######################################
+
+Modules should have short, all-lowercase names. Underscores can be
+used in the module name if it improves readability. Python packages
+should also have short, all-lowercase names, although the use of
+underscores is discouraged.
+
+Since module names are mapped to file names, and some file systems are
+case insensitive and truncate long names, it is important that module
+names be chosen to be fairly short -- this won't be a problem on Unix,
+but it may be a problem when the code is transported to older Mac or
+Windows versions, or DOS.
+
+When an extension module written in C or C++ has an accompanying
+Python module that provides a higher level (e.g. more object oriented)
+interface, the C/C++ module has a leading underscore
+(e.g. ``_socket``).
+
+#######################################
+ Class Names
+#######################################
+
+Almost without exception, class names use the CapWords convention.
+Classes for internal use have a leading underscore in addition.
+
+#######################################
+ Exception Names
+#######################################
+
+Because exceptions should be classes, the class naming convention
+applies here. However, you should use the suffix "Error" on your
+exception names (if the exception actually is an error).
+
+#######################################
+ Global Variable Names
+#######################################
+
+(Let's hope that these variables are meant for use inside one module
+only.) The conventions are about the same as those for functions.
+
+Modules that are designed for use via ``from M import *`` should use
+the ``__all__`` mechanism to prevent exporting globals, or use the
+older convention of prefixing such globals with an underscore (which
+you might want to do to indicate these globals are "module
+non-public").
+
+#######################################
+ Function Names
+#######################################
+
+Function names should be lowercase, with words separated by
+underscores as necessary to improve readability.
+
+mixedCase is allowed only in contexts where that's already the
+prevailing style (e.g. threading.py), to retain backwards
+compatibility.
+
+#######################################
+ Function and method arguments
+#######################################
+
+Always use ``self`` for the first argument to instance methods.
+
+Always use ``cls`` for the first argument to class methods.
+
+If a function argument's name clashes with a reserved keyword, it is
+generally better to append a single trailing underscore rather than
+use an abbreviation or spelling corruption. Thus ``class_`` is better
+than ``clss``. (Perhaps better is to avoid such clashes by using a
+synonym.)
+
+#######################################
+ Method Names and Instance Variables
+#######################################
+
+Use the function naming rules: lowercase with words separated by
+underscores as necessary to improve readability.
+
+Use one leading underscore only for non-public methods and instance
+variables.
+
+To avoid name clashes with subclasses, use two leading underscores to
+invoke Python's name mangling rules.
+
+Python mangles these names with the class name: if class Foo has an
+attribute named ``__a``, it cannot be accessed by ``Foo.__a``. (An
+insistent user could still gain access by calling ``Foo._Foo__a``.)
+Generally, double leading underscores should be used only to avoid
+name conflicts with attributes in classes designed to be subclassed.
+
+Note: there is some controversy about the use of __names (see below).
+
+#######################################
+ Constants
+#######################################
+
+Constants are usually defined on a module level and written in all
+capital letters with underscores separating words. Examples include
+``MAX_OVERFLOW`` and ``TOTAL``.
+
+#######################################
+ Designing for inheritance
+#######################################
+
+Always decide whether a class's methods and instance variables
+(collectively: "attributes") should be public or non-public. If in
+doubt, choose non-public; it's easier to make it public later than to
+make a public attribute non-public.
+
+Public attributes are those that you expect unrelated clients of your
+class to use, with your commitment to avoid backward incompatible
+changes. Non-public attributes are those that are not intended to be
+used by third parties; you make no guarantees that non-public
+attributes won't change or even be removed.
+
+We don't use the term "private" here, since no attribute is really
+private in Python (without a generally unnecessary amount of work).
+
+Another category of attributes are those that are part of the
+"subclass API" (often called "protected" in other languages). Some
+classes are designed to be inherited from, either to extend or modify
+aspects of the class's behavior. When designing such a class, take
+care to make explicit decisions about which attributes are public,
+which are part of the subclass API, and which are truly only to be
+used by your base class.
+
+With this in mind, here are the Pythonic guidelines:
+
+- Public attributes should have no leading underscores.
+
+- If your public attribute name collides with a reserved keyword,
+ append a single trailing underscore to your attribute name. This is
+ preferable to an abbreviation or corrupted spelling. (However,
+ not withstanding this rule, 'cls' is the preferred spelling for any
+ variable or argument which is known to be a class, especially the
+ first argument to a class method.)
+
+ Note 1:
+ See the argument name recommendation above for class methods.
+
+- For simple public data attributes, it is best to expose just the
+ attribute name, without complicated accessor/mutator methods. Keep
+ in mind that Python provides an easy path to future enhancement,
+ should you find that a simple data attribute needs to grow
+ functional behavior. In that case, use properties to hide
+ functional implementation behind simple data attribute access
+ syntax.
+
+ Note 1:
+ Properties only work on new-style classes.
+
+ Note 2:
+ Try to keep the functional behavior side-effect free,
+ although side-effects such as caching are generally fine.
+
+ Note 3:
+ Avoid using properties for computationally expensive operations;
+ the attribute notation makes the caller believe that access is
+ (relatively) cheap.
+
+- If your class is intended to be subclassed, and you have attributes
+ that you do not want subclasses to use, consider naming them with
+ double leading underscores and no trailing underscores. This
+ invokes Python's name mangling algorithm, where the name of the
+ class is mangled into the attribute name. This helps avoid
+ attribute name collisions should subclasses inadvertently contain
+ attributes with the same name.
+
+ Note 1:
+ Note that only the simple class name is used in the mangled
+ name, so if a subclass chooses both the same class name and
+ attribute name, you can still get name collisions.
+
+ Note 2:
+ Name mangling can make certain uses, such as debugging and
+ ``__getattr__()``, less convenient. However the name mangling
+ algorithm is well documented and easy to perform manually.
+
+ Note 3:
+ Not everyone likes name mangling. Try to balance the
+ need to avoid accidental name clashes with potential use by
+ advanced callers.
+
+=======================================
+ References
+=======================================
+
+.. [1] `PEP 7, Style Guide for C Code, van Rossum <https://www.python.org/dev/peps/pep-0007/>`_
+.. [2] `Barry's GNU Mailman style guide <http://barry.warsaw.us/software/STYLEGUIDE.txt>`_
+.. [3] `CamelCase Wikipedia page <http://www.wikipedia.com/wiki/CamelCase>`_
+
+=======================================
+ Copyright
+=======================================
+
+Author:
+
+* Guido van Rossum <guido@python.org>
+* Barry Warsaw <barry@python.org>
diff --git a/doc/sphinx/dev_guide/release_management.rst b/doc/sphinx/dev_guide/release_management.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f5435fe7b841ef49affe63ee9d34918bf3dc6e6e
--- /dev/null
+++ b/doc/sphinx/dev_guide/release_management.rst
@@ -0,0 +1,23 @@
+-------------------------------------------------------------------------------
+ Release management
+-------------------------------------------------------------------------------
+===========================================================
+ How to make a minor release
+===========================================================
+
+.. code-block:: bash
+
+ $ git tag -a 1.4.4 -m "Next minor in 1.4 series"
+ $ vim CMakeLists.txt # edit CPACK_PACKAGE_VERSION_PATCH
+ $ git push --tags
+
+Update the Web site in doc/www
+
+Update all issues, upload the ChangeLog based on ``git log`` output.
+The ChangeLog must only include items which are mentioned as issues
+on github. If anything significant is there, which is not mentioned,
+something went wrong in release planning and the release should be
+held up until this is cleared.
+
+Click 'Release milestone'. Create a milestone for the next minor release.
+Alert the driver to target bugs and blueprints to the new milestone.
diff --git a/doc/sphinx/directives.rst b/doc/sphinx/directives.rst
new file mode 100644
index 0000000000000000000000000000000000000000..1fa03a5e0c15bedd9fc19ca27dddf7ab2c1b72c2
--- /dev/null
+++ b/doc/sphinx/directives.rst
@@ -0,0 +1,5 @@
+:orphan:
+
+.. |br| raw:: html
+
+ <br />
diff --git a/doc/sphinx/ext/__init__.py b/doc/sphinx/ext/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/doc/sphinx/ext/filters.py b/doc/sphinx/ext/filters.py
new file mode 100644
index 0000000000000000000000000000000000000000..97c0c73b21ecb5170aeb8c91e0d6e89852b18e81
--- /dev/null
+++ b/doc/sphinx/ext/filters.py
@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+"""
+ .ext.filters
+ ~~~~~~~~~~~~
+"""
+
+import xml.etree.ElementTree as ET
+
+def add_jinja_filters(app):
+ app.builder.templates.environment.filters['cleantitle'] = (lambda x: ''.join(ET.fromstring('<p>'+x+'</p>').itertext()))
+
+def setup(app):
+ '''
+ Adds extra jinja filters.
+ '''
+ app.connect("builder-inited", add_jinja_filters)
+ return {'version': '0.0.1', 'parallel_read_safe': True}
diff --git a/doc/sphinx/ext/lua.py b/doc/sphinx/ext/lua.py
new file mode 100644
index 0000000000000000000000000000000000000000..a38fb526ddf510eee3fb59f1f4e6a313477a0b9e
--- /dev/null
+++ b/doc/sphinx/ext/lua.py
@@ -0,0 +1,847 @@
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+# Previously Haka Domain (https://github.com/haka-security/haka)
+# Written by Haka team
+
+import re
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+
+from sphinx import addnodes
+from sphinx.roles import XRefRole
+from sphinx.locale import l_, _
+from sphinx.domains import Domain, ObjType, Index
+from sphinx.directives import ObjectDescription
+from sphinx.util.nodes import make_refnode
+from sphinx.util.compat import Directive
+from sphinx.util.docfields import Field, GroupedField, TypedField
+from sphinx.writers.html import HTMLTranslator
+
+
+# Fix parameter display when using something different than '()'
+
+def new_visit_desc_parameterlist(self, node):
+ if hasattr(node, 'param_class'):
+ param_class = ' class="param_start_%s"' % node.param_class
+ else:
+ param_class = ''
+
+ if hasattr(node, 'param_start'):
+ value = node.param_start
+ else:
+ value = '('
+
+ self.body.append('<big%s>%s</big>' % (param_class, value))
+ self.first_param = 1
+ self.optional_param_level = 0
+ # How many required parameters are left.
+ self.required_params_left = sum([isinstance(c, addnodes.desc_parameter)
+ for c in node.children])
+ self.param_separator = node.child_text_separator
+
+def new_depart_desc_parameterlist(self, node):
+ if hasattr(node, 'param_class'):
+ param_class = ' class="param_end_%s"' % node.param_class
+ else:
+ param_class = ''
+
+ if hasattr(node, 'param_end'):
+ value = node.param_end
+ else:
+ value = ')'
+
+ self.body.append('<big%s>%s</big>' % (param_class, value))
+
+HTMLTranslator.visit_desc_parameterlist = new_visit_desc_parameterlist
+HTMLTranslator.depart_desc_parameterlist = new_depart_desc_parameterlist
+
+def _desc_parameterlist(argstart, argend):
+ node = addnodes.desc_parameterlist()
+ node.param_start = argstart
+ node.param_end = argend
+ return node
+
+def _pseudo_parse_arglist(signode, argstart, arglist, argend):
+ """"Parse" a list of arguments separated by commas.
+
+ Arguments can have "optional" annotations given by enclosing them in
+ brackets. Currently, this will split at any comma, even if it's inside a
+ string literal (e.g. default argument value).
+ """
+ paramlist = _desc_parameterlist(argstart, argend)
+ stack = [paramlist]
+ for argument in arglist.split(','):
+ argument = argument.strip()
+ ends_open = ends_close = 0
+ while argument.startswith('['):
+ stack.append(addnodes.desc_optional())
+ stack[-2] += stack[-1]
+ argument = argument[1:].strip()
+
+ while argument.startswith(']'):
+ stack.pop()
+ argument = argument[1:].strip()
+
+ while argument.endswith(']'):
+ ends_close += 1
+ argument = argument[:-1].strip()
+
+ while argument.endswith('['):
+ ends_open += 1
+ argument = argument[:-1].strip()
+
+ if argument:
+ stack[-1] += addnodes.desc_parameter(argument, argument)
+ while ends_open:
+ stack.append(addnodes.desc_optional())
+ stack[-2] += stack[-1]
+ ends_open -= 1
+
+ while ends_close:
+ stack.pop()
+ ends_close -= 1
+
+ if len(stack) != 1:
+ raise IndexError
+
+ signode += paramlist
+
+
+# Lua objects
+
+class LuaObject(ObjectDescription):
+ """
+ Description of a general Lua object.
+ """
+ option_spec = {
+ 'noindex': directives.flag,
+ 'annotation': directives.unchanged,
+ 'module': directives.unchanged,
+ 'objtype': directives.unchanged,
+ 'idxtype': directives.unchanged,
+ 'idxctx': directives.unchanged,
+ }
+
+ lua_signature_re = re.compile(
+ r'''^ ([\w\.\:/\-]+[:.])? # class name(s)
+ ([<>\w/\-/]+) \s* # thing name
+ (?: ([({])(.*)([)}]))? # optional: arguments
+ (?:\s* -> \s* (.*))? # optional: return annotation
+ $ # and nothing more
+ ''', re.VERBOSE)
+
+ def needs_arglist(self):
+ """May return true if an empty argument list is to be generated even if
+ the document contains none."""
+ return False
+
+ def needs_module(self):
+ """May return true if the module name should be displayed."""
+ return self.context == None
+
+ def needs_class(self):
+ """May return true if the module name should be displayed."""
+ return self.context == None
+
+ def build_objtype(self):
+ return self.options.get('objtype') or "%s" % (self.__class__.typename)
+
+ def build_context(self, context):
+ if context:
+ return context[:-1], context[-1]
+ else:
+ return None, None
+
+ def parse_signature(self, sig):
+ m = self.__class__.lua_signature_re.match(sig)
+ if m is None:
+ raise ValueError
+
+ return m.groups()
+
+ def build_parameters(self, signode):
+ if not self.arglist:
+ if self.needs_arglist():
+ # for callables, add an empty parameter list
+ listnode = _desc_parameterlist(self.argstart, self.argend)
+ signode += listnode
+ else:
+ _pseudo_parse_arglist(signode, self.argstart, self.arglist, self.argend)
+
+ def build_signode(self, signode):
+ if self.context:
+ context = self.context + self.contextsep
+ signode += addnodes.desc_addname(context, context)
+
+ signode += addnodes.desc_name(self.name, self.name)
+ self.build_parameters(signode)
+
+ if self.retann:
+ signode += addnodes.desc_returns(self.retann, self.retann)
+
+ def handle_signature(self, sig, signode):
+ context, name, argstart, arglist, argend, retann = self.parse_signature(sig)
+
+ self.context, self.contextsep = self.build_context(context)
+ self.module = self.options.get('module', self.env.temp_data.get('lua:module'))
+ self.clsname = self.options.get('class', self.env.temp_data.get('lua:class'))
+ self.objtype = self.build_objtype()
+ self.idxtype = self.options.get('idxtype') or self.options.get('objtype')
+ self.name = name
+ self.argstart = argstart
+ self.arglist = arglist
+ self.argend = argend
+ self.retann = retann
+
+ add_module = True
+ fullname = name
+
+ signode['module'] = self.module
+ signode['class'] = self.context
+ signode['fullname'] = fullname
+
+ prefix = "%s " % (self.objtype)
+ signode += addnodes.desc_annotation(prefix, prefix)
+
+ if self.clsname and self.needs_class():
+ clsname = '%s:' % (self.clsname)
+ signode += addnodes.desc_addname(clsname, clsname)
+ elif self.module and self.needs_module():
+ modname = '%s.' % (self.module)
+ signode += addnodes.desc_addname(modname, modname)
+
+ self.build_signode(signode)
+
+ anno = self.options.get('annotation')
+ if anno:
+ signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
+
+ return {'fullname': fullname, 'context': self.context,
+ 'objtype': self.objtype, 'idxctx': self.options.get('idxctx') or ""}
+
+ def add_target_and_index(self, names, sig, signode):
+ idxctx = self.options.get('idxctx')
+
+ ids = ['lua-%s' % (self.__class__.typename)]
+ if idxctx: ids.append(idxctx)
+ if self.context: ids.append(self.context)
+ elif self.clsname and self.needs_class(): ids.append(self.clsname)
+ elif self.module and self.needs_module(): ids.append(self.module)
+ ids.append(names['fullname'])
+
+ fullid = '.'.join(ids)
+# self.state_machine.reporter.warning(fullid)
+
+ fullname = []
+ if self.clsname and self.needs_class(): fullname.append(self.clsname)
+ elif self.module and self.needs_module(): fullname.append(self.module)
+ if self.context: fullname.append(self.context)
+ fullname.append(names['fullname'])
+ fullname = '.'.join(fullname)
+
+ # We need to escape the '<>' to avoid display issue in HTML
+ fullname = fullname.replace("<", "<")
+ fullname = fullname.replace(">", ">")
+
+ if fullid not in self.state.document.ids:
+ objtype = self.objtype
+ if objtype == "": objtype = "%s" % (self.__class__.typename)
+
+ signode['names'].append(fullname)
+ signode['ids'].append(fullid)
+ signode['first'] = (not self.names)
+ self.state.document.note_explicit_target(signode)
+ objects = self.env.domaindata['lua']['objects']
+ objects[fullname] = (self.env.docname, objtype, fullid)
+
+ indextext = self.get_index_text(names)
+ if indextext:
+ self.indexnode['entries'].append(('single', indextext,
+ fullid, ''))
+
+ def get_index_name(self, names):
+ return names['fullname']
+
+ def get_index_type(self):
+ return None
+
+ def get_index_text(self, names):
+ ret = []
+
+ idxtype = self.idxtype or self.get_index_type()
+ if idxtype: ret.append(idxtype)
+
+ if self.context: ret.append("in %s" % (self.context))
+ if self.module and self.needs_module(): ret.append("in module %s" % (self.module))
+
+ return "%s (%s)" % (self.get_index_name(names), ' '.join(ret))
+
+
+class LuaClass(LuaObject):
+ doc_field_types = [
+ Field('extend', label=l_('Extends'), has_arg=False,
+ names=('extend',)),
+ ]
+
+ typename = l_("object")
+
+ def get_index_type(self):
+ return "%s" % (self.__class__.typename)
+
+ def before_content(self):
+ LuaObject.before_content(self)
+ if self.names:
+ self.env.temp_data['lua:class'] = self.names[0]['fullname']
+
+ def after_content(self):
+ LuaObject.after_content(self)
+ if self.names:
+ self.env.temp_data['lua:class'] = None
+
+class LuaFunction(LuaObject):
+ typename = l_("function")
+
+ doc_field_types = [
+ TypedField('parameter', label=l_('Parameters'),
+ names=('param', 'parameter', 'arg', 'argument'),
+ typerolename='obj', typenames=('paramtype', 'type', 'ptype')),
+ TypedField('returnvalues', label=l_('Returns'),
+ names=('return', 'ret'), typerolename='obj',
+ typenames=('rtype', 'type')),
+ Field('returnvalue', label=l_('Returns'), has_arg=False,
+ names=('returns')),
+ Field('returntype', label=l_('Return type'), has_arg=False,
+ names=('returntype',)),
+ ]
+
+ def build_objtype(self):
+ return self.options.get('objtype') or ""
+
+ def needs_arglist(self):
+ return True
+
+ def get_index_name(self, names):
+ return '%s()' % (names['fullname'])
+
+class LuaMethod(LuaFunction):
+ option_spec = dict(
+ abstract=directives.flag,
+ **LuaObject.option_spec
+ )
+
+ def build_objtype(self):
+ if 'abstract' in self.options:
+ return "abstract %s" % (self.options.get('objtype') or "")
+ else:
+ return self.options.get('objtype') or ""
+
+
+ def build_context(self, context):
+ if context:
+ return "%s" % (context[:-1]), context[-1]
+ else:
+ return None, None
+
+class LuaData(LuaObject):
+ typename = l_("data")
+
+ option_spec = dict(
+ readonly=directives.flag,
+ **LuaObject.option_spec
+ )
+
+ doc_field_types = [
+ Field('type', label=l_('Type'), has_arg=False,
+ names=('type',)),
+ ]
+
+ def build_objtype(self):
+ if 'readonly' in self.options:
+ return "const %s" % (self.options.get('objtype') or "")
+ else:
+ return self.options.get('objtype') or ""
+
+class LuaAttribute(LuaData):
+ typename = l_("attribute")
+
+ lua_class_re = re.compile(
+ r'''([\w\./\-]+):([\w\./\-]+)?
+ ''', re.VERBOSE)
+
+ def build_context(self, context):
+ if context:
+ m = LuaAttribute.lua_class_re.match(context[:-1])
+ if m:
+ classname, subcontext = m.groups()
+ if subcontext:
+ return "<%s>.%s" % (classname, subcontext), '.'
+ else:
+ return "<%s>" % (classname), '.'
+ else:
+ return "<%s>" % (context[:-1]), '.'
+ else:
+ return None, None
+
+class LuaOperator(LuaObject):
+ typename = l_("operator")
+
+ doc_field_types = [
+ TypedField('parameter', label=l_('Parameters'),
+ names=('param', 'parameter', 'arg', 'argument'),
+ typerolename='obj', typenames=('paramtype', 'type', 'ptype')),
+ TypedField('returnvalues', label=l_('Returns'),
+ names=('return', 'ret'), typerolename='obj',
+ typenames=('rtype', 'type')),
+ Field('returnvalue', label=l_('Returns'), has_arg=False,
+ names=('returns')),
+ Field('returntype', label=l_('Return type'), has_arg=False,
+ names=('returntype',)),
+ ]
+
+ lua_signature_unary_re = re.compile(
+ r'''^ ([\+\-\*/<>=\#]+) \s* # operator
+ ([\w\./\-]+) # class name(s)
+ (?:\s* -> \s* (.*))? # optional: return annotation
+ $ # and nothing more
+ ''', re.VERBOSE)
+
+ lua_signature_binary_re = re.compile(
+ r'''^ ([\w\./\-]+) # class name(s)
+ \s* ([\+\-\*/<>=]+) \s* # operator
+ ([\w\./\-]+)? # class name(s)
+ (?:\s* -> \s* (.*))? # optional: return annotation
+ $ # and nothing more
+ ''', re.VERBOSE)
+
+ lua_signature_index_re = re.compile(
+ r'''^ ([\w\./\-]+) # class name(s)
+ (\[)(.*)(\]) # arguments
+ (?:\s* -> \s* (.*))? # optional: return annotation
+ $ # and nothing more
+ ''', re.VERBOSE)
+
+ lua_signature_newindex_re = re.compile(
+ r'''^ ([\w\./\-]+) # class name(s)
+ (\[)(.*)(\]) # arguments
+ \s* = \s* (.*) # return annotation
+ $ # and nothing more
+ ''', re.VERBOSE)
+
+ lua_signature_convert_re = re.compile(
+ r'''^ ([\w/\-/]+) \s* # thing name
+ \( ([\w\./\-]+) \) # class name(s)
+ (?:\s* -> \s* (.*))? # optional: return annotation
+ $ # and nothing more
+ ''', re.VERBOSE)
+
+ def parse_signature(self, sig):
+ m = LuaOperator.lua_signature_unary_re.match(sig)
+ if m:
+ name, context, retann = m.groups()
+ self.type = 'unary'
+ return context, name, None, None, None, retann
+
+ m = LuaOperator.lua_signature_binary_re.match(sig)
+ if m:
+ context, name, _, retann = m.groups()
+ self.type = 'binary'
+ return context, name, None, None, None, retann
+
+ m = LuaOperator.lua_signature_index_re.match(sig)
+ if m:
+ context, argstart, arglist, argend, retann = m.groups()
+ self.type = 'index'
+ return context, '[]', argstart, arglist, argend, retann
+
+ m = LuaOperator.lua_signature_newindex_re.match(sig)
+ if m:
+ context, argstart, arglist, argend, retann = m.groups()
+ self.type = 'newindex'
+ return context, '[]', argstart, arglist, argend, retann
+
+ m = LuaOperator.lua_signature_convert_re.match(sig)
+ if m:
+ name, context, retann = m.groups()
+ self.type = 'convert'
+ return context, name, None, None, None, retann
+
+ raise ValueError
+
+ def build_context(self, context):
+ if context:
+ return "<%s>" % (context), ''
+ else:
+ return None, None
+
+ def build_objtype(self):
+ return self.options.get('objtype') or ""
+
+ def build_signode(self, signode):
+ if self.type == 'unary':
+ signode += addnodes.desc_name(self.name, self.name)
+
+ context = self.context + self.contextsep
+ signode += addnodes.desc_addname(context, context)
+
+ if self.retann:
+ signode += addnodes.desc_returns(self.retann, self.retann)
+
+ elif self.type == 'binary':
+ context = self.context + self.contextsep
+ name = " %s " % (self.name)
+
+ signode += addnodes.desc_addname(context, context)
+ signode += addnodes.desc_name(name, name)
+ signode += addnodes.desc_addname(context, context)
+
+ if self.retann:
+ signode += addnodes.desc_returns(self.retann, self.retann)
+
+ elif self.type == 'index' or self.type == 'newindex':
+ context = self.context + self.contextsep
+ signode += addnodes.desc_addname(context, context)
+
+ self.build_parameters(signode)
+
+ if self.retann:
+ if self.type == 'newindex':
+ retann = " = %s" % (self.retann)
+ signode += addnodes.desc_type(retann, retann)
+ else:
+ signode += addnodes.desc_returns(self.retann, self.retann)
+
+ elif self.type == 'convert':
+ context = self.context + self.contextsep
+
+ signode += addnodes.desc_name(self.name, self.name)
+
+ paramlist = _desc_parameterlist('(', ')')
+ paramlist.append(addnodes.desc_addname(context, context))
+ signode.append(paramlist)
+
+ if self.retann:
+ signode += addnodes.desc_returns(self.retann, self.retann)
+
+
+
+class LuaModule(Directive):
+ """
+ Directive to mark description of a new module.
+ """
+
+ has_content = False
+ required_arguments = 1
+ optional_arguments = 0
+ final_argument_whitespace = False
+ option_spec = {
+ 'platform': lambda x: x,
+ 'synopsis': lambda x: x,
+ 'noindex': directives.flag,
+ 'deprecated': directives.flag,
+ }
+
+ def run(self):
+ env = self.state.document.settings.env
+ modname = self.arguments[0].strip()
+ noindex = 'noindex' in self.options
+ env.temp_data['lua:module'] = modname
+ ret = []
+ if not noindex:
+ env.domaindata['lua']['modules'][modname] = \
+ (env.docname, self.options.get('synopsis', ''),
+ self.options.get('platform', ''), 'deprecated' in self.options)
+
+ ids = "lua-module.%s" % (modname)
+
+ # make a duplicate entry in 'objects' to facilitate searching for
+ # the module in LuaDomain.find_obj()
+ env.domaindata['lua']['objects'][modname] = (env.docname, 'module', ids)
+ targetnode = nodes.target('', '', ids=[ids],
+ ismod=True)
+ self.state.document.note_explicit_target(targetnode)
+ # the platform and synopsis aren't printed; in fact, they are only
+ # used in the modindex currently
+ ret.append(targetnode)
+ indextext = _('%s (module)') % modname
+ inode = addnodes.index(entries=[('single', indextext,
+ ids, '')])
+ ret.append(inode)
+ return ret
+
+class LuaCurrentModule(Directive):
+ """
+ This directive is just to tell Sphinx that we're documenting
+ stuff in module foo, but links to module foo won't lead here.
+ """
+ has_content = False
+ required_arguments = 1
+ optional_arguments = 0
+ final_argument_whitespace = False
+ option_spec = {}
+
+ def run(self):
+ env = self.state.document.settings.env
+ modname = self.arguments[0].strip()
+ if modname == 'None':
+ env.temp_data['lua:module'] = None
+ else:
+ env.temp_data['lua:module'] = modname
+ return []
+
+
+class LuaXRefRole(XRefRole):
+ def process_link(self, env, refnode, has_explicit_title, title, target):
+ refnode['lua:module'] = env.temp_data.get('lua:module')
+ refnode['lua:class'] = env.temp_data.get('lua:class')
+ if not has_explicit_title:
+ title = title.lstrip('.') # only has a meaning for the target
+ target = target.lstrip('~') # only has a meaning for the title
+ # if the first character is a tilde, don't display the module/class
+ # parts of the contents
+ if title[0:1] == '~':
+ title = title[1:]
+ dot = max(title.rfind('.'), title.rfind(':'))
+ if dot != -1:
+ title = title[dot+1:]
+ # if the first character is a dot, search more specific namespaces first
+ # else search builtins first
+ if target[0:1] == '.':
+ target = target[1:]
+ refnode['refspecific'] = True
+ return title, target
+
+class LuaModuleIndex(Index):
+ """
+ Index subclass to provide the Lua module index.
+ """
+ name = 'modindex'
+ localname = l_('Lua Module Index')
+ shortname = l_('modules')
+
+ def generate(self, docnames=None):
+ content = {}
+ # list of prefixes to ignore
+ ignores = self.domain.env.config['modindex_common_prefix']
+ ignores = sorted(ignores, key=len, reverse=True)
+ # list of all modules, sorted by module name
+ modules = sorted(self.domain.data['modules'].items(),
+ key=lambda x: x[0].lower())
+ # sort out collapsable modules
+ prev_modname = ''
+ num_toplevels = 0
+ for modname, (docname, synopsis, platforms, deprecated) in modules:
+ if docnames and docname not in docnames:
+ continue
+
+ for ignore in ignores:
+ if modname.startswith(ignore):
+ modname = modname[len(ignore):]
+ stripped = ignore
+ break
+ else:
+ stripped = ''
+
+ # we stripped the whole module name?
+ if not modname:
+ modname, stripped = stripped, ''
+
+ entries = content.setdefault(modname[0].lower(), [])
+
+ package = modname.split('.')[0]
+ if package != modname:
+ # it's a submodule
+ if prev_modname == package:
+ # first submodule - make parent a group head
+ entries[-1][1] = 1
+ elif not prev_modname.startswith(package):
+ # submodule without parent in list, add dummy entry
+ entries.append([stripped + package, 1, '', '', '', '', ''])
+ subtype = 2
+ else:
+ num_toplevels += 1
+ subtype = 0
+
+ qualifier = deprecated and _('Deprecated') or ''
+ entries.append([stripped + modname, subtype, docname,
+ 'module-' + stripped + modname, platforms,
+ qualifier, synopsis])
+ prev_modname = modname
+
+ # apply heuristics when to collapse modindex at page load:
+ # only collapse if number of toplevel modules is larger than
+ # number of submodules
+ collapse = len(modules) - num_toplevels < num_toplevels
+
+ # sort by first letter
+ content = sorted(content.items())
+
+ return content, collapse
+
+
+# Lua domain
+
+class LuaDomain(Domain):
+ """Lua language domain."""
+ name = 'lua'
+ label = 'Lua'
+ object_types = {
+ 'class': ObjType(l_('class'), 'class', 'obj'),
+ 'attribute': ObjType(l_('attribute'), 'data', 'obj'),
+ 'function': ObjType(l_('function'), 'func', 'obj'),
+ 'method': ObjType(l_('method'), 'func', 'obj'),
+ 'operator': ObjType(l_('operator'), 'func', 'obj'),
+ 'module': ObjType(l_('module'), 'mod', 'obj'),
+ 'data': ObjType(l_('data'), 'data', 'obj'),
+ }
+
+ directives = {
+ 'class': LuaClass,
+ 'function': LuaFunction,
+ 'method': LuaMethod,
+ 'operator': LuaOperator,
+ 'data': LuaData,
+ 'attribute': LuaAttribute,
+ 'module': LuaModule,
+ 'currentmodule': LuaCurrentModule,
+ }
+ roles = {
+ 'data': LuaXRefRole(),
+ 'func': LuaXRefRole(fix_parens=True),
+ 'class': LuaXRefRole(),
+ 'mod': LuaXRefRole(),
+ }
+ initial_data = {
+ 'objects': {}, # fullname -> docname, objtype
+ 'modules': {}, # modname -> docname, synopsis, platform, deprecated
+ 'inheritance': {}, # class -> [ derived ]
+ }
+ indices = [
+ LuaModuleIndex,
+ ]
+
+ def clear_doc(self, docname):
+ for fullname, (fn, _, _) in list(self.data['objects'].items()):
+ if fn == docname:
+ del self.data['objects'][fullname]
+ for modname, (fn, _, _, _) in list(self.data['modules'].items()):
+ if fn == docname:
+ del self.data['modules'][modname]
+
+ def find_obj(self, env, modname, classname, name, type, searchmode=0):
+ # skip parens
+ if name[-2:] == '()':
+ name = name[:-2]
+
+ if not name:
+ return []
+
+ name = name.replace("<", "<")
+ name = name.replace(">", ">")
+
+ objects = self.data['objects']
+ matches = []
+
+ newname = None
+ if searchmode == 1:
+ objtypes = self.objtypes_for_role(type)
+ if modname and classname:
+ fullname = modname + '.' + classname + '.' + name
+ if fullname in objects and objects[fullname][1] in objtypes:
+ newname = fullname
+ if not newname:
+ if modname and modname + '.' + name in objects and \
+ objects[modname + '.' + name][1] in objtypes:
+ newname = modname + '.' + name
+ elif name in objects and objects[name][1] in objtypes:
+ newname = name
+ else:
+ # "fuzzy" searching mode
+ searchname = '.' + name
+ matches = [(oname, objects[oname]) for oname in objects
+ if oname.endswith(searchname)
+ and objects[oname][1] in objtypes]
+ else:
+ # NOTE: searching for exact match, object type is not considered
+ if name in objects:
+ newname = name
+ elif type == 'mod':
+ # only exact matches allowed for modules
+ return []
+ elif classname and classname + '.' + name in objects:
+ newname = classname + '.' + name
+ elif modname and modname + '.' + name in objects:
+ newname = modname + '.' + name
+ elif modname and classname and \
+ modname + '.' + classname + '.' + name in objects:
+ newname = modname + '.' + classname + '.' + name
+ # special case: builtin exceptions have module "exceptions" set
+ elif type == 'exc' and '.' not in name and \
+ 'exceptions.' + name in objects:
+ newname = 'exceptions.' + name
+ # special case: object methods
+ elif type in ('func', 'meth') and '.' not in name and \
+ 'object.' + name in objects:
+ newname = 'object.' + name
+ if newname is not None:
+ matches.append((newname, objects[newname]))
+ return matches
+
+ def resolve_xref(self, env, fromdocname, builder,
+ type, target, node, contnode):
+
+ modname = node.get('lua:module')
+ clsname = node.get('lua:class')
+ searchmode = node.hasattr('refspecific') and 1 or 0
+ matches = self.find_obj(env, modname, clsname, target,
+ type, searchmode)
+
+ if not matches:
+ # If type is 'obj', we don't want to display any WARNING.
+ # Otherwise, we have too many due to unknown type used
+ # as parameter type in function description (number, string...).
+ if type != "obj":
+ env.warn_node(
+ 'no target found for cross-reference '
+ '%r' % (target), node)
+ return None
+ elif len(matches) > 1:
+ env.warn_node(
+ 'more than one target found for cross-reference '
+ '%r: %s' % (target, ', '.join(match[0] for match in matches)),
+ node)
+ name, obj = matches[0]
+
+ return make_refnode(builder, fromdocname, obj[0], obj[2],
+ contnode, name)
+
+ def get_objects(self):
+ for modname, info in self.data['modules'].items():
+ yield (modname, modname, 'module', info[0], 'module-' + modname, 0)
+ for refname, (docname, type, id) in self.data['objects'].items():
+ yield (refname, refname, type, docname, id, 1)
+
+
+def setup(app):
+ app.add_domain(LuaDomain)
diff --git a/doc/sphinx/faq.rst b/doc/sphinx/faq.rst
new file mode 100644
index 0000000000000000000000000000000000000000..54161b0faaf2b9e878eb57d1e5a384a5322e93d9
--- /dev/null
+++ b/doc/sphinx/faq.rst
@@ -0,0 +1,57 @@
+:title: FAQ's
+:slug: faq
+:save_as: doc/faq.html
+:template: documentation_rst
+
+-------------------------------------------------------------------------------
+ FAQ
+-------------------------------------------------------------------------------
+.. container:: faq
+
+ :Q: Why Tarantool?
+ :A: Tarantool is a result of a long trial and error process within Mail.Ru. It's
+ the Nth generation of a family of custom in-memory data servers, developed for
+ various web applications. Besides, when Tarantool development started (2008)
+ there were no stable and sufficiently functional open source alternative.
+
+
+ :Q: Why Lua?
+ :A: Lua is a ligthweight, fast, extensible multi-paradigm language. Lua also happens
+ to be very easy to embed. Lua coroutines relate very closely to Tarantool fibers,
+ and Lua architecture works well with Tarantool internals. Lua is the first, but,
+ hopefully, not the last stored program language for Tarantool.
+
+
+ :Q: What's the key advantage of Tarantool?
+ :A: Tarantool provides a rich database feature set (HASH, TREE, RTREE, BITSET indexes,
+ secondary indexes, composite indexes, transactions, triggres, asynchronous replication)
+ in a flexible environment of a Lua interpreter.
+
+ These two properties make it possible to code fast, atomic and reliable in-memory
+ data servers which handle non-trivial application-specific logic. The win over
+ traditional SQL servers is in performance: low-overhead, lock-free architecture
+ means Tarantool can serve an order of magnitude more requests per second, on
+ comparable hardware. The win over NoSQL alternatives is in flexibility: Lua
+ allows flexible processing of data stored in a compact, denormalized format.
+
+
+ :Q: What are your development plans?
+ :A: We continuously improve server performance. On the feature front, automatic
+ sharding and online upgrade are the two major goals of 2015.
+
+
+ :Q: Who is developing Tarantool?
+ :A: There is a small engineering team employed by Mail.ru -- check out our commit
+ logs on github. The development is fully open, and most of the connectors
+ authors and maintainers in different distributions are from the community.
+
+
+ :Q: How serious is Mail.Ru about Tarantool?
+ :A: Tarantool is an open source project, distributed under a BSD license, and as
+ such does not depend on any one sponsor. However, it is currently and integral
+ part of Mail.Ru backbone, so it gets a lot of support from Mail.ru.
+
+
+ :Q: What happens when Tarantool runs out of memory?
+ :A: The server stops accepting updates until more memory is available. Read and
+ delete requests are served just fine.
diff --git a/doc/sphinx/getting_started.rst b/doc/sphinx/getting_started.rst
new file mode 100644
index 0000000000000000000000000000000000000000..47c3ade6ea6b31e9388fb4f8437737894527713d
--- /dev/null
+++ b/doc/sphinx/getting_started.rst
@@ -0,0 +1,316 @@
+-------------------------------------------------------------------------------
+ Getting started
+-------------------------------------------------------------------------------
+
+
+This chapter shows how to download, how to install, and how to start Tarantool
+for the first time.
+
+For production, if possible, you should download a binary (executable) package.
+This will ensure that you have the same build of the same version that the
+developers have. That makes analysis easier if later you need to report a problem,
+and avoids subtle problems that might happen if you used different tools or
+different parameters when building from source. The section about binaries is
+“`Downloading and installing a binary package`_â€.
+
+For development, you will want to download a source package and make the binary
+by yourself using a C/C++ compiler and common tools. Although this is a bit harder,
+it gives more control. And the source packages include additional files, for example
+the Tarantool test suite. The section about source is “:ref:`building-from-source` â€
+
+If the installation has already been done, then you should try it out. So we've
+provided some instructions that you can use to make a temporary “sandboxâ€. In a
+few minutes you can start the server and type in some database-manipulation
+statements. The section about sandbox is “`Starting Tarantool and making your first database`_â€.
+
+=====================================================================
+ Downloading and installing a binary package
+=====================================================================
+
+The repositories for the “stable†release are at tarantool.org/dist/stable.
+The repositories for the “master†release are at tarantool.org/dist/master.
+Since this is the manual for the “master†release, all instructions use
+tarantool.org/dist/master.
+
+An automatic build system creates, tests and publishes packages for every
+push into the master branch. Therefore if you looked at
+tarantool.org/dist/master you would see that there are source files and
+subdirectories for the packages that will be described in this section.
+
+To download and install the package that's appropriate for your environment,
+start a shell (terminal) and enter one of the following sets of command-line
+instructions.
+
+More advice for binary downloads is at http://tarantool.org/download.html.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Debian GNU/Linux
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is always an up-to-date Debian repository at
+http://tarantool.org/dist/master/debian The repository contains builds for
+Debian unstable "Sid", stable "Wheezy", forthcoming "Jessie". Add the
+tarantool.org repository to your apt sources list. $release is an environment
+variable which will contain the Debian version code e.g. "Wheezy":
+
+.. code-block:: bash
+
+ wget http://tarantool.org/dist/public.key
+ sudo apt-key add ./public.key
+ release=`lsb_release -c -s`
+ # append two lines to a list of source repositories
+ echo "deb http://tarantool.org/dist/master/debian/ $release main" | \
+ sudo tee -a /etc/apt/sources.list.d/tarantool.list
+ echo "deb-src http://tarantool.org/dist/master/debian/ $release main" | \
+ sudo tee -a /etc/apt/sources.list.d/tarantool.list
+ # install
+ sudo apt-get update
+ sudo apt-get install tarantool
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Ubuntu
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is always an up-to-date Ubuntu repository at
+http://tarantool.org/dist/master/ubuntu The repository contains builds for
+Ubuntu 12.04 "precise", 13.10 "saucy", and 14.04 "trusty". Add the tarantool.org
+repository to your apt sources list $release is an environment variable which
+will contain the Ubuntu version code e.g. "precise". If you want the version
+that comes with Ubuntu, start with the lines that follow the '# install' comment:
+
+.. code-block:: lua
+
+ cd ~
+ wget http://tarantool.org/dist/public.key
+ sudo apt-key add ./public.key
+ release=`lsb_release -c -s`
+ # append two lines to a list of source repositories
+ echo "deb http://tarantool.org/dist/master/ubuntu/ $release main" | \
+ sudo tee -a /etc/apt/sources.list.d/tarantool.list
+ echo "deb-src http://tarantool.org/dist/master/ubuntu/ $release main" | \
+ sudo tee -a /etc/apt/sources.list.d/tarantool.list
+ # install
+ sudo apt-get update
+ sudo apt-get install tarantool
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CentOS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These instructions are applicable for CentOS version 6 or 7, and RHEL version
+6 or 7. Pick the CentOS repository which fits your CentOS/RHEL version and
+your x86 platform:
+
+* http://tarantool.org/dist/master/centos/6/os/i386 for version 6, x86-32
+* http://tarantool.org/dist/master/centos/6/os/x86_64 for version 6, x86-64
+* http://tarantool.org/dist/master/centos/7/os/x86_64 for version 7, x86-64
+
+Add the following section to your yum repository list
+(``/etc/yum.repos.d/tarantool.repo``) (in the following instructions, ``$releasever``
+i.e. CentOS release version must be either 6 or 7 and ``$basearch`` i.e. base
+architecture must be either i386 or x86_64):
+
+.. code-block:: ini
+
+ # [tarantool]
+ name=CentOS-$releasever - Tarantool
+ baseurl=http://tarantool.org/dist/master/centos/$releasever/os/$basearch/
+ enabled=1
+ gpgcheck=0
+
+For example, if you have CentOS version 6 and x86-64, you can add the new section thus:
+
+.. code-block:: bash
+
+ echo "[tarantool]" | \
+ sudo tee /etc/yum.repos.d/tarantool.repo
+ echo "name=CentOS-6 - Tarantool"| sudo tee -a /etc/yum.repos.d/tarantool.repo
+ echo "baseurl=http://tarantool.org/dist/master/centos/6/os/x86_64/" | \
+ sudo tee -a /etc/yum.repos.d/tarantool.repo
+ echo "enabled=1" | sudo tee -a /etc/yum.repos.d/tarantool.repo
+ echo "gpgcheck=0" | sudo tee -a /etc/yum.repos.d/tarantool.repo
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Fedora
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These instructions are applicable for Fedora 19, 20 or rawhide. Pick the Fedora
+repository, for example http://tarantool.org/dist/master/fedora/20/x86_64 for
+version 20, x86-64. Add the following section to your yum repository list
+(``/etc/yum.repos.d/tarantool.repo``) (in the following instructions,
+``$releasever`` i.e. Fedora release version must be 19, 20 or rawhide and
+``$basearch`` i.e. base architecture must be x86_64):
+
+.. code-block:: ini
+
+ [tarantool]
+ name=Fedora-$releasever - Tarantool
+ baseurl=http://tarantool.org/dist/master/fedora/$releasever$basearch/
+ enabled=1
+ gpgcheck=0
+
+For example, if you have Fedora version 20, you can add the new section thus:
+
+.. code-block:: bash
+
+ echo "[tarantool]" | \
+ sudo tee /etc/yum.repos.d/tarantool.repo
+ echo "name=Fedora-20 - Tarantool"| sudo tee -a /etc/yum.repos.d/tarantool.repo
+ echo "baseurl=http://tarantool.org/dist/master/fedora/20/x86_64/" | \
+ sudo tee -a /etc/yum.repos.d/tarantool.repo
+ echo "enabled=1" | sudo tee -a /etc/yum.repos.d/tarantool.repo
+ echo "gpgcheck=0" | sudo tee -a /etc/yum.repos.d/tarantool.repo
+ Then install with sudo yum install tarantool.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Gentoo
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+available from tarantool portage overlay. Use layman to add the overlay to your system:
+
+.. code-block:: bash
+
+ layman -S
+ layman -a tarantool
+ emerge dev-db/tarantool -av
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ FreeBSD
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With your browser go to the FreeBSD ports page
+http://www.freebsd.org/ports/index.html. Enter the search term: tarantool.
+Choose the package you want.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Mac OS X
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is actually a “homebrew†recipe so it's not a true binary download,
+some source code is involved. First upgrade Clang (the C compiler) to version 3.2
+or later using Command Line Tools for Xcode disk image version 4.6+ from Apple
+Developer web-site. Then download the recipe file from
+build.tarantool.org/tarantool.rb. Make the file executable, execute it,
+and the script in the file should handle the necessary steps with cmake, make,
+and make install.
+
+.. _first database:
+
+=====================================================================
+ Starting Tarantool and making your first database
+=====================================================================
+
+Here is how to create a simple test database after installing.
+
+1. Create a new directory. It's just for tests, you can delete it when
+ the tests are over.
+
+ .. code-block:: bash
+
+ mkdir ~/tarantool_sandbox
+ cd ~/tarantool_sandbox
+
+2. Start the server. The server name is tarantool.
+
+ .. code-block:: bash
+
+ #if you downloaded a binary with apt-get or yum, say this:
+ /usr/bin/tarantool
+ #if you downloaded and untarred a binary tarball to ~/tarantool, say this:
+ ~/tarantool/bin/tarantool
+ #if you built from a source download, say this:
+ ~/tarantool/src/tarantool
+
+ The server starts in interactive mode and outputs a command prompt.
+ To turn on the database, :mod:`configure <box.cfg>` it:
+
+ .. code-block:: lua
+
+ tarantool> box.cfg{listen=3301}
+
+ (this minimal example is sufficient).
+
+ If all goes well, you will see the server displaying progress as it
+ initializes, something like this:
+
+ .. code-block:: bash
+
+ tarantool> box.cfg{listen=3301}
+ 2014-08-07 09:41:41.077 ... version 1.6.3-439-g7e1011b
+ 2014-08-07 09:41:41.077 ... log level 5
+ 2014-08-07 09:41:41.078 ... mapping 1073741824 bytes for a shared arena...
+ 2014-08-07 09:41:41.079 ... initialized
+ 2014-08-07 09:41:41.081 ... initializing an empty data directory
+ 2014-08-07 09:41:41.095 ... creating './00000000000000000000.snap.inprogress'
+ 2014-08-07 09:41:41.095 ... saving snapshot './00000000000000000000.snap.inprogress'
+ 2014-08-07 09:41:41.127 ... done
+ 2014-08-07 09:41:41.128 ... primary: bound to 0.0.0.0:3301
+ 2014-08-07 09:41:41.128 ... ready to accept requests
+
+ Now that the server is up, you could start up a different shell
+ and connect to its primary port with
+
+ .. code-block:: bash
+
+ telnet 0 3301
+
+ but for example purposes it is simpler to just leave the server
+ running in "interactive mode". On production machines the
+ interactive mode is just for administrators, but because it's
+ convenient for learning it will be used for most examples in
+ this manual. Tarantool is waiting for the user to type instructions.
+
+ To create the first space and the first :mod:`box.index`, try this:
+
+ .. code-block:: lua
+
+ tarantool> s = box.schema.space.create('tester')
+ tarantool> i = s:create_index('primary', {type = 'hash', parts = {1, 'NUM'}})
+
+ To insert three “tuples†(our name for “recordsâ€) into the first “space†of the database try this:
+
+ .. code-block:: lua
+
+ tarantool> t = s:insert({1})
+ tarantool> t = s:insert({2, 'Music'})
+ tarantool> t = s:insert({3, 'Length', 93})
+
+ To select a tuple from the first space of the database, using the first defined key, try this:
+
+ .. code-block:: lua
+
+ tarantool> s:select{3}
+
+ Your terminal screen should now look like this:
+
+ .. code-block:: lua
+
+ tarantool> s = box.schema.space.create('tester')
+ 2014-06-10 12:04:18.158 ... creating './00000000000000000002.xlog.inprogress'
+ ---
+ ...
+ tarantool> s:create_index('primary', {type = 'hash', parts = {1, 'NUM'}})
+ ---
+ ...
+ tarantool> t = s:insert{1}
+ ---
+ ...
+ tarantool> t = s:insert{2, 'Music'}
+ ---
+ ...
+ tarantool> t = s:insert{3, 'Length', 93}
+ ---
+ ...
+ tarantool> s:select{3}
+ ---
+ - - [3, 'Length', 93]
+ ...
+
+ tarantool>
+
+ Now, to prepare for the example in the next section, try this:
+
+ .. code-block:: lua
+
+ tarantool> box.schema.user.grant('guest','read,write,execute','universe')
diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..12f415790c47c4467125aa17425cc8b184a439cc
--- /dev/null
+++ b/doc/sphinx/index.rst
@@ -0,0 +1,13 @@
+-------------------------------------------------------------------------------
+ Documentation
+-------------------------------------------------------------------------------
+
+.. toctree::
+ :maxdepth: 1
+
+ intro.rst
+ faq.rst
+ getting_started
+ book/index.rst
+ reference/index.rst
+ dev_guide/index.rst
diff --git a/doc/sphinx/intro.rst b/doc/sphinx/intro.rst
new file mode 100644
index 0000000000000000000000000000000000000000..ca69eeb2b2f723b3aec0463231b4c367b9a1e7b0
--- /dev/null
+++ b/doc/sphinx/intro.rst
@@ -0,0 +1,98 @@
+-------------------------------------------------------------------------------
+ Overview
+-------------------------------------------------------------------------------
+
+
+Tarantool is a Lua application server integrated with a database management system.
+It has a "fiber" model which means that many applications can run simultaneously on
+a single thread, while the Tarantool server can run multiple threads for input-output
+and background maintenance. It integrates the LuaJIT -- "Just In Time" -- Lua compiler,
+Lua libraries for most common applications, and the Tarantool Database Server which
+is an established NoSQL DBMS. Thus it serves all the purposes that have made node.js
+and Twisted popular in other environments, with the additional twist that it has a
+data persistence level.
+
+The code is free. The open-source license is *`BSD license`_*. The supported platforms
+are GNU/Linux, Mac OS and FreeBSD.
+
+Tarantool database is deeply integrated with the application server. On
+the surface, Tarantool is simply a Lua language interpreter, and the database
+is one of many built-in Lua packages. But the exposed database API not only
+allows to persist Lua objects to disk, but to manage object collections, create
+or drop secondary keys, configure and monitor replication, perform controlled
+fail-over, execute Lua code upon database events.
+Remote database instances are accessible transparently via remote
+procedure invocation API.
+
+Unlike popular application development frameworks based on a "reactor" pattern,
+networking in server-side Lua is sequential, yet very efficient, as it is built
+on top of the **cooperative multitasking** environment that Tarantool itself
+uses. A key feature is that the functions can access and modify databases
+atomically. Thus some developers look at it as a DBMS with a popular stored
+procedure language, while others look at it as a replacement for multiple
+components of multi-tier Web application architectures. Performance is a few
+thousand transactions per second on a laptop, scalable upwards or outwards to
+server farms.
+
+===============================================================================
+ Key features
+===============================================================================
+
+Tarantool data storage is built around **storage engine** concept, when
+different sets of algorithms and data structures can be used for different
+collections of objects. Two storage engines are built-in: in-memory engine,
+which represents 100% of data and indexes in RAM, and a two-level B-tree,
+for data sets exceeding the amount of available RAM from 10 to up to 1000
+times. All storage engines in Tarantool support transactions and
+replication by using a common **write ahead log**. This ensures consistency
+and crash safety of the persistent state. The logging subsystem supports
+group commit.
+
+**Tarantool in-memory engine is lock-free**. Instead of the operating system's
+concurrency primitives, such as mutexes, it uses cooperative multitasking to
+handle thousands of connections simultaneously. There is a fixed number of
+independent execution threads. The threads do not share state. Instead they
+exchange data using low-overhead message queues. While this approach limits the
+number of cores that the server will use, it removes competition for the memory
+bus and ensures peak scalability of memory access and network throughput. CPU
+utilization of a typical highly-loaded Tarantool server is under 10%.
+
+**Tarantool disk-based engine** is a fusion of ideas from modern filesystems,
+log-structured merge trees and classical B-trees. All data is organized
+into **branches**, each branch is represented by a file on disk. Branch
+size is a configuration option and normally is around 64MB. Each
+branch is a collection of pages, serving different purposes. Pages
+in a fully merged branch contain non-overlapping ranges of keys. A branch
+can be partially merged if there were a lot of changes in its key range
+recently. In that case some pages represent new keys and values in the
+branch. The disk-based engine is append only: new data never overwrites
+the old.
+
+Unlike most NoSQL DBMSs, Tarantool supports **secondary index keys** as well as
+primary keys, and **multi-part index keys**. The possible index types are HASH,
+TREE, BITSET, and RTREE.
+
+Tarantool supports **asynchronous replication**, locally or to remote hosts.
+The replication architecture can be **master-master**, that is, many nodes may
+both handle the loads and receive what others have handled, for the same data
+sets.
+
+===============================================================================
+ How stable is the software?
+===============================================================================
+
+**The software is production-ready**. Tarantool has been created and is actively
+used at `Mail.Ru`_, one of the leading Russian web content providers. At `Mail.Ru`_,
+the software serves the **"hottest"** data, such as online users and their
+sessions, online application properties, mapping between users and their
+serving shards, and so on.
+
+Outside `Mail.Ru`_ the software is used by a growing number of projects in online
+gaming, digital marketing, social media industries. While product development
+is sponsored by `Mail.Ru`_, the roadmap, bugs database and the development process
+are fully open. The software incorporates patches from dozens of community
+contributors, and most of the programming language drivers are written and
+supported by the community.
+
+.. _BSD license: http://www.gnu.org/licenses/license-list.html#ModifiedBSD
+.. _Mail.Ru: http://api.mail.ru
diff --git a/doc/sphinx/reference/console.rst b/doc/sphinx/reference/console.rst
new file mode 100644
index 0000000000000000000000000000000000000000..224d5e1ed22246838c3535bec406214f77d13710
--- /dev/null
+++ b/doc/sphinx/reference/console.rst
@@ -0,0 +1,75 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `console`
+-------------------------------------------------------------------------------
+
+The console package allows one Tarantool server to access another Tarantool
+server, and allows one Tarantool server to start listening on an administrative
+host/port.
+
+.. module:: console
+
+.. function:: connect(uri [, options])
+
+ Connect to the server at :ref:`URI`, change the prompt from 'tarantool' to
+ 'host:port', and act henceforth as a client until the user ends the
+ session or types ``control-D``.
+
+ The console.connect function allows one Tarantool server, in interactive
+ mode, to access another Tarantool server over a TCP connection. Subsequent
+ requests will appear to be handled locally, but in reality the requests
+ are being sent to the remote server and the local server is acting as a
+ client. Once connection is successful, the prompt will change and
+ subsequent requests are sent to, and executed on, the remote server.
+ Results are displayed on the local server. To return to local mode,
+ enter ``control-D``.
+
+ There are no restrictions on the types of requests that can be entered,
+ except those which are due to privilege restrictions -- by default the
+ login to the remote server is done with user name = 'guest'. The remote
+ server could allow for this by granting at least one privilege:
+ ``box.schema.user.grant('guest','execute','universe')``.
+
+ :param string uri:
+ :param table options: The options may be necessary if the Tarantool
+ server at host:port requires authentication.
+ In such a case the connection might look
+ something like:
+ ``console.connect('netbox:123@127.0.0.1'})``
+
+ :return: nil
+ :except: the connection will fail if the target Tarantool server
+ was not initiated with ``box.cfg{listen=...}``.
+
+ .. code-block:: lua
+
+ tarantool> console = require('console')
+ ---
+ ...
+ tarantool> console.connect('198.18.44.44:3301')
+ ---
+ ...
+ 198.18.44.44:3301> -- prompt is telling us that server is remote
+
+.. function:: listen(host, port)
+
+ Listen on host:port. The primary way of listening for incoming requests
+ is via the host and port, or :ref:`URI`, specified in ``box.cfg{listen=...}``.
+ The alternative way of listening is via the host and port, or URI,
+ specified in ``console.listen(...)``. This alternative way is called
+ "administrative" or simply "admin port".
+ The listening is usually over a local host with a Unix socket,
+ specified as host = 'unix/', port = 'path/to/something.sock'.
+
+ :param string host:
+ :param number port:
+
+ The "admin" address is the port or :ref:`URI` to listen on for administrative
+ connections. It has no default value, so it must be specified if
+ connections will occur via telnet. It is not used unless assigned a
+ value. The parameters may be expressed with :ref:`URI` = Universal Resource
+ Identifier format, for example "unix://unix_domain_socket", or as a
+ numeric TCP port. Connections are often made with telnet.
+ A typical port value is 3313.
diff --git a/doc/sphinx/reference/digest.rst b/doc/sphinx/reference/digest.rst
new file mode 100644
index 0000000000000000000000000000000000000000..19a1907b06364cbe1372537243f88bd8476768ed
--- /dev/null
+++ b/doc/sphinx/reference/digest.rst
@@ -0,0 +1,170 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `digest`
+-------------------------------------------------------------------------------
+
+A "digest" is a value which is returned by a `Cryptographic hash function`_ applied
+against a string. Tarantool supports five types of cryptographic hash functions
+(MD4_, MD5_, SHA-0_, SHA-1_, SHA-2_) as well as a checksum function (CRC32_) and two
+functions for base64_. The functions in digest are:
+
+.. module:: digest
+
+.. function:: crc32(string)
+ crc32_update(number, string)
+
+ Returns 32-bit checksum made with CRC32. |br|
+ Returns update of a checksum calculated with CRC32.
+
+ .. NOTE::
+
+ This function uses the `CRC-32C (Castagnoli)`_ polynomial
+ value: 0x11EDC6F41 / 4812730177. If it is necessary to be
+ compatible with other checksum functions in other
+ programming languages, ensure that the other functions use
+ the same polynomial value. |br| For example, in Python,
+ install the crcmod package and say:
+
+ .. code-block:: python
+
+ >>> import crcmod
+ >>> fun = crcmod.mkCrcFun('4812730177')
+ >>> fun('string')
+ 3304160206L
+
+.. _CRC-32C (Castagnoli): https://en.wikipedia.org/wiki/Cyclic_redundancy_check#Standards_and_common_use
+
+.. function:: sha(string)
+ sha_hex(string)
+
+ Returns 160-bit digest made with SHA-0. Not recommended. |br|
+ Returns hexadecimal of a digest calculated with sha.
+
+.. function:: sha1(string)
+ sha1_hex(string)
+
+ Returns 160-bit digest made with SHA-1. |br|
+ Returns hexadecimal of a digest calculated with sha1.
+
+.. function:: sha224(string)
+ sha224_hex(string)
+
+ Returns 224-bit digest made with SHA-2. |br|
+ Returns hexadecimal of a digest calculated with sha224.
+
+.. function:: sha256(string)
+ sha256_hex(string)
+
+ Returns 256-bit digest made with SHA-2. |br|
+ Returns hexadecimal of a digest calculated with sha256.
+
+.. function:: sha384(string)
+ sha384_hex(string)
+
+ Returns 384-bit digest made with SHA-2. |br|
+ Returns hexadecimal of a digest calculated with sha384.
+
+.. function:: sha512(string)
+ sha512_hex(string)
+
+ Returns 512-bit digest made with SHA-2. |br|
+ Returns hexadecimal of a digest calculated with sha512.
+
+.. function:: md4(string)
+ md4_hex(string)
+
+ Returns 128-bit digest made with MD4. |br|
+ Returns hexadecimal of a digest calculated with md4.
+
+.. function:: md5(string)
+ md5_hex(string)
+
+ Returns 256-bit digest made with MD5. |br|
+ Returns hexadecimal of a digest calculated with md5.
+
+.. function:: base64_encode(string)
+ base64_decode(string)
+
+ Returns base64 encoding from a regular string. |br|
+ Returns a regular string from a base64 encoding.
+
+.. function:: urandom(integer)
+
+ Returns array of random bytes with length = integer.
+
+.. function:: guava(integer, integer)
+
+ Returns a number made with consistent hash.
+
+ .. NOTE::
+
+ This function uses the `Consistent Hashing`_ algorithm of
+ the Google guava library. The first parameter should be a
+ hash code; the second parameter should be the number of
+ buckets; the returned value will be an integer between 0
+ and the number of buckets. For example,
+
+ .. code-block:: lua
+
+ localhost> digest.guava(10863919174838991, 11)
+ 8
+
+=================================================
+ Example
+=================================================
+
+In the following example, the user creates two functions, ``password_insert()``
+which inserts a SHA-1_ digest of the word "**^S^e^c^ret Wordpass**" into a tuple
+set, and ``password_check()`` which requires input of a password.
+
+.. code-block:: lua
+
+ localhost> digest = require('digest')
+ localhost> -- this means ignore line feeds until next '!'
+ localhost> console = require('console'); console.delimiter('!')
+ localhost> function password_insert()
+ -> box.space.tester:insert{12345,
+ -> digest.sha1('^S^e^c^ret Wordpass')}
+ -> return 'OK'
+ -> end!
+ ---
+ ...
+ localhost> function password_check(password)
+ -> local t
+ -> t=box.space.tester:select{12345}
+ -> if (digest.sha1(password)==t[2]) then
+ -> print('Password is valid')
+ -> else
+ -> print('Password is not valid')
+ -> end
+ -> end!
+ ---
+ ...
+ localhost> password_insert()!
+ Call OK, 1 rows affected
+ ['OK']
+ localhost> -- back to normal: commands end with line feed!
+ localhost> console.delimiter('')
+
+If a later user calls the ``password_check()`` function and enters
+the wrong password, the result is an error.
+
+.. code-block:: lua
+
+ localhost> password_check ('Secret Password')
+ ---
+ Password is not valid
+ ...
+
+.. _MD4: https://en.wikipedia.org/wiki/Md4
+.. _MD5: https://en.wikipedia.org/wiki/Md5
+.. _SHA-0: https://en.wikipedia.org/wiki/Sha-0
+.. _SHA-1: https://en.wikipedia.org/wiki/Sha-1
+.. _SHA-2: https://en.wikipedia.org/wiki/Sha-2
+.. _CRC32: https://en.wikipedia.org/wiki/Cyclic_redundancy_check
+.. _base64: https://en.wikipedia.org/wiki/Base64
+.. _Cryptographic hash function: https://en.wikipedia.org/wiki/Cryptographic_hash_function
+.. _Consistent Hashing: https://en.wikipedia.org/wiki/Consistent_hashing
+.. _CRC-32C (Castagnoli): https://en.wikipedia.org/wiki/Cyclic_redundancy_check#Standards_and_common_use
diff --git a/doc/sphinx/reference/expirationd.rst b/doc/sphinx/reference/expirationd.rst
new file mode 100644
index 0000000000000000000000000000000000000000..c6025ab125847d3344cbcf5a2f18c45f34e5341e
--- /dev/null
+++ b/doc/sphinx/reference/expirationd.rst
@@ -0,0 +1,108 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `expirationd`
+-------------------------------------------------------------------------------
+
+For a commercial-grade example of a Lua rock that works with Tarantool, let us
+look at expirationd, which Tarantool supplies on GitHub_ with an Artistic license.
+The expirationd.lua program is lengthy (about 500 lines), so here we will only
+highlight the matters that will be enhanced by studying the full source later.
+
+.. code-block:: lua
+
+ task.worker_fiber = fiber.create(worker_loop, task)
+ log.info("expiration: task %q restarted", task.name)
+ ...
+ fiber.sleep(expirationd.constants.check_interval)
+ ...
+
+Whenever one hears "daemon" in Tarantool, one should suspect it's being done
+with :doc:`fiber`. The program is making a fiber and turning control over to it so
+it runs occasionally, goes to sleep, then comes back for more.
+
+.. code-block:: lua
+
+ for _, tuple in scan_space.index[0]:pairs(nil, {iterator = box.index.ALL}) do
+ ...
+ if task.is_tuple_expired(task.args, tuple) then
+ task.expired_tuples_count = task.expired_tuples_count + 1
+ task.process_expired_tuple(task.space_id, task.args, tuple)
+ ...
+
+The "for" instruction can be translated as "iterate through the index of the
+space that is being scanned", and within it, if the tuple is "expired" (that
+is, if the tuple has a timestamp field which is less than the current time),
+process the tuple as an expired tuple.
+
+.. code-block:: lua
+
+ -- put expired tuple in archive
+ local function put_tuple_to_archive(space_id, args, tuple)
+ -- delete expired tuple
+ box.space[space_id]:delete{tuple[1]}
+ local email = get_field(tuple, 2)
+ if args.archive_space_id ~= nil and email ~= nil then
+ box.space[args.archive_space_id]:replace{email, os.time()}
+ end
+ end
+
+Ultimately the tuple-expiry process leads to ``put_tuple_to_archive()``
+which does a "delete" of a tuple from its original space, and an "insert"
+of the same tuple into another space. Tarantool's "replace" function is
+the same as an "insert" function without an error message if a tuple with
+the same content already exists in the target space.
+
+.. code-block:: lua
+
+ function expirationd.do_test(space_id, archive_space_id)
+ ...
+
+At this point, if the above explanation is worthwhile, it's clear that
+``expirationd.lua`` starts a background routine (fiber) which iterates through
+all the tuples in a space, sleeps cooperatively so that other fibers can
+operate at the same time, and - whenever it finds a tuple that has expired
+- deletes it from this space and puts it in another space. Now the
+"``do_test()``" function can be used to create some sample spaces, let the
+daemon run for a while, and print results.
+
+For those who like to see things run, here are the exact steps to get
+expirationd through the test.
+
+1. Get ``expirationd.lua``. There are standard ways - it is after all part
+ of a standard rock - but for this purpose just copy the contents of
+ expirationd.lua_ to a default directory.
+2. Start the Tarantool server as described before.
+3. Execute these requests:
+
+.. code-block:: lua
+
+ box.cfg{}
+ a = box.schema.space.create('origin')
+ a:create_index('first', {type = 'tree', parts = {1, 'NUM'}})
+ b = box.schema.space.create('archive')
+ b:create_index('first', {type = 'tree', parts = {1, 'STR'}})
+ expd = require('expirationd')
+ expd._debug = true
+ expd.do_test('origin', 'archive')
+ os.exit()
+
+The database-specific requests (``cfg``, ``space.create``, ``create_index``)
+should already be familiar. The key for getting the rock rolling is
+``expd = require('expirationd')``. The "``require``" function is what reads in
+the program; it will appear in many later examples in this manual, when it's
+necessary to get a package that's not part of the Tarantool kernel. After the
+Lua variable expd has been assigned the value of the expirationd package, it's
+possible to invoke the package's ``do_test()`` function.
+
+After a while, when the task has had time to do its iterations through the spaces,
+``do_test()`` will print out a report showing the tuples that were originally in
+the original space, the tuples that have now been moved to the archive space, and
+some statistics. Of course, expirationd can be customized to do different things
+by passing different parameters, which will be evident after looking in more detail
+at the source code.
+
+.. _rock: http://rocks.tarantool.org/
+.. _expirationd.lua: https://github.com/tarantool/expirationd/blob/master/expirationd.lua
+.. _GitHub: https://github.com/tarantool/expirationd/blob/master/expirationd.lua
diff --git a/doc/sphinx/reference/fiber-ipc.rst b/doc/sphinx/reference/fiber-ipc.rst
new file mode 100644
index 0000000000000000000000000000000000000000..6b89ed1985b7154b061df06660d1874feb60f988
--- /dev/null
+++ b/doc/sphinx/reference/fiber-ipc.rst
@@ -0,0 +1,177 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `fiber-ipc`
+-------------------------------------------------------------------------------
+
+The ``fiber-ipc`` package allows sending and receiving messages between
+different processes. The words "different processes" in this context
+mean different connections, different sessions, or different fibers.
+
+Call ``fiber.channel()`` to allocate space and get a channel object,
+which will be called channel for examples in this section. Call the
+other ``fiber-ipc`` routines, via channel, to send messages, receive
+messages, or check ipc status. Message exchange is synchronous. The
+channel is garbage collected when no one is using it, as with any
+other Lua object. Use object-oriented syntax, for example
+``channel:put(message)`` rather than ``fiber.channel.put(message)``.
+
+.. module:: fiber
+
+.. function:: channel([capacity])
+
+ Create a new communication channel.
+
+ :param int capacity: positive integer as great as the maximum number of
+ slots (spaces for get or put or broadcast messages)
+ that might be pending at any given time.
+
+ :return: new channel.
+ :rtype: userdata
+
+.. class:: channel_object
+
+ .. method:: put(message[, timeout])
+
+ Send a message using a channel. If the channel is full,
+ ``channel:put()`` blocks until there is a free slot in the channel.
+
+ :param lua_object message:
+ :param timeout:
+ :return: If timeout is provided, and the channel doesn't become empty for
+ the duration of the timeout, ``channel:put()`` returns false.
+ Otherwise it returns true.
+ :rtype: boolean
+
+ .. method:: close()
+
+ Close the channel. All waiters in the channel will be woken up.
+ All following ``channel:put()`` or ``channel:get()`` operations will
+ return an error (``nil``).
+
+ .. method:: get([timeout])
+
+ Fetch a message from a channel. If the channel is empty,
+ ``channel:get()`` blocks until there is a message.
+
+ :param timeout:
+ :return: the value placed on the channel by an earlier
+ ``channel:put()`` or ``channel:broadcast()``.
+ :rtype: lua_object
+
+ .. method:: broadcast(message)
+
+ If the channel is empty, ``channel:broadcast()`` is equivalent to
+ ``channel:put()``. Otherwise, ``channel:broadcast()`` sends the
+ message to all readers of the channel.
+
+ :param message:
+
+ .. method:: is_empty()
+
+ Check whether the specified channel is empty (has no messages).
+
+ :return: true if the specified channel is empty
+ :rtype: boolean
+
+ .. method:: count()
+
+ Find out how many messages are on the channel. The answer is 0 if the channel is empty.
+
+ :return: the number of messages.
+ :rtype: number
+
+ .. method:: is_full()
+
+ Check whether the specified channel is full.
+
+ :return: true if the specified channel is full (has no room for a new message).
+ :rtype: boolean
+
+ .. method:: has_readers()
+
+ Check whether the specified channel is empty and has readers waiting for
+ a message (because they have issued ``channel:get()`` and then blocked).
+
+ :return: true if blocked users are waiting. Otherwise false.
+ :rtype: boolean
+
+ .. method:: has_writers()
+
+ Check whether the specified channel is full and has writers waiting
+ (because they have issued ``channel:put()`` and then blocked due to lack of room).
+
+ :return: true if blocked users are waiting. Otherwise false.
+ :rtype: boolean
+
+ .. method:: is_closed()
+
+ :return: true if the specified channel is already closed. Otherwise false.
+ :rtype: boolean
+
+=================================================
+ Example
+=================================================
+
+.. code-block:: lua
+
+ fiber = require('fiber')
+ channel = fiber.channel(10)
+ function consumer_fiber()
+ while true do
+ local task = channel:get()
+ ...
+ end
+ end
+
+ function consumer2_fiber()
+ while true do
+ -- 10 seconds
+ local task = channel:get(10)
+ if task ~= nil then
+ ...
+ else
+ -- timeout
+ end
+ end
+ end
+
+ function producer_fiber()
+ while true do
+ task = box.space...: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 are waiting for data
+ end
+ ...
+
+ if channel:has_writers() then
+ -- there are some fibers
+ -- that are waiting for readers
+ end
+ channel:put(task)
+ end
+ end
+
+ function producer2_fiber()
+ while true do
+ task = box.space...select{...}
+ -- 10 seconds
+ if channel:put(task, 10) then
+ ...
+ else
+ -- timeout
+ end
+ end
+ end
diff --git a/doc/sphinx/reference/fiber.rst b/doc/sphinx/reference/fiber.rst
new file mode 100644
index 0000000000000000000000000000000000000000..1b7a105a463d60c9943a1bc7fd7903b61e36332f
--- /dev/null
+++ b/doc/sphinx/reference/fiber.rst
@@ -0,0 +1,262 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `fiber`
+-------------------------------------------------------------------------------
+
+The ``fiber`` package allows for creating, running and managing *fibers*.
+
+A fiber is a set of instructions which are executed with cooperative
+multitasking. Fibers managed by the fiber package are associated with
+a user-supplied function called the *fiber function*.
+A fiber has three possible states: **running**, **suspended** or **dead**.
+When a fiber is created with ``fiber.create()``, it is running.
+When a fiber yields control with ``fiber.sleep()``, it is suspended.
+When a fiber ends (because the fiber function ends), it is dead.
+
+All fibers are part of the fiber registry. This registry can be searched
+(``fiber.find()``) - via fiber id (fid), which is numeric.
+
+A runaway fiber can be stopped with ``fiber_object:cancel()``. However,
+``fiber_object:cancel()`` is advisory — it works only if the runaway fiber
+calls ``fiber.testcancel()`` once in a while. Most box.* functions, such
+as ``box.space...delete()`` or ``box.space...update()``, do call
+``fiber.testcancel()`` but ``box.space...select{}`` does not. In practice,
+a runaway fiber can only become unresponsive if it does many computations
+and does not check whether it's been canceled.
+
+The other potential problem comes from fibers which never get scheduled,
+because they are not subscribed to any events, or because no relevant
+events occur. Such morphing fibers can be killed with ``fiber.cancel()``
+at any time, since ``fiber.cancel()`` sends an asynchronous wakeup event
+to the fiber, and ``fiber.testcancel()`` is checked whenever such an event occurs.
+
+Like all Lua objects, dead fibers are garbage collected. The garbage collector
+frees pool allocator memory owned by the fiber, resets all fiber data, and
+returns the fiber (now called a fiber carcass) to the fiber pool. The carcass
+can be reused when another fiber is created.
+
+.. module:: fiber
+
+.. function:: create(function [, function-arguments])
+
+ Create and start a fiber. The fiber is created and begins to run immediately.
+
+ :param function: the function to be associated with the fiber
+ :param function-arguments: what will be passed to function
+ :return: created fiber object
+ :rtype: userdata
+
+ .. code-block:: lua
+
+ fiber_object = fiber.create(function_name)
+
+.. function:: self()
+
+ :return: fiber object for the currently scheduled fiber.
+ :rtype: userdata
+
+.. function:: find(id)
+
+ :param id: scalar value to find thread by.
+ :return: fiber object for the specified fiber.
+ :rtype: userdata
+
+.. function:: sleep(time)
+
+ Yield control to the scheduler and sleep for the specified number
+ of seconds. Only the current fiber can be made to sleep.
+
+ :param time: number of seconds to sleep.
+
+.. function:: yield()
+
+ Yield control to the scheduler. Equivalent to ``fiber.sleep(0)``.
+
+.. function:: status()
+
+ Return the status of the current fiber.
+
+ :return: the status of ``fiber``. One of:
+ “deadâ€, “suspendedâ€, or “runningâ€.
+ :rtype: string
+
+.. function:: info()
+
+ Return information about all fibers.
+
+ :return: the name, id, and backtrace of all fibers.
+ :rtype: table
+
+.. function:: kill(id)
+
+ Locate a fiber by its numeric id and cancel it. In other words,
+ ``fiber.kill()`` combines ``fiber.find()`` and ``fiber_object:cancel()``.
+
+ :param id: the id of the fiber to be canceled.
+ :exception: the specified fiber does not exist or cancel is not permitted.
+
+.. function:: testcancel()
+
+ Check if the current fiber has been canceled
+ and throw an exception if this is the case.
+
+.. class:: fiber_object
+
+ .. method:: id()
+
+ :param self: fiber object, for example the fiber
+ object returned by ``fiber.create``
+ :return: id of the fiber.
+ :rtype: number
+
+ .. method:: name()
+
+ :param self: fiber object, for example the fiber
+ object returned by ``fiber.create``
+ :return: name of the fiber.
+ :rtype: number
+
+ .. method:: name(name)
+
+ Change the fiber name. By default the Tarantool server's
+ interactive-mode fiber is named 'interactive' and new
+ fibers created due to ``fiber.create`` are named 'lua'.
+ Giving fibers distinct names makes it easier to
+ distinguish them when using ``fiber.info``.
+
+ :param self: fiber object, for example the fiber
+ object returned by ``fiber.create``
+ :param string name: the new name of the fiber.
+ :return: nil
+
+ .. method:: status()
+
+ Return the status of the specified fiber.
+
+ :param self: fiber object, for example the fiber
+ object returned by ``fiber.create``
+ :return: the status of fiber. One of: “deadâ€,
+ “suspendedâ€, or “runningâ€.
+ :rtype: string
+
+ .. method:: cancel()
+
+ Cancel a fiber. Running and suspended fibers can be canceled.
+ After a fiber has been canceled, attempts to operate on it will
+ cause errors, for example ``fiber_object:id()`` will cause
+ "error: the fiber is dead".
+
+ :param self: fiber object, for example the fiber
+ object returned by ``fiber.create``
+ :return: nil
+
+ :exception: cancel is not permitted for the specified fiber object.
+
+.. function:: time()
+
+ :return: current system time (in seconds since the epoch) 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.
+ :rtype: num
+
+ .. code-block:: lua
+
+ tarantool> fiber = require('fiber')
+ ---
+ ...
+ tarantool> fiber.time(), fiber.time()
+ ---
+ - 1385758759.2591
+ - 1385758759.2591
+ ...
+
+.. function:: time64()
+
+ :return: current system time (in microseconds since the epoch)
+ as a 64-bit integer. The time is taken from the event
+ loop clock.
+ :rtype: num
+
+ .. code-block:: lua
+
+ tarantool> fiber = require('fiber')
+ ---
+ ...
+ tarantool> fiber.time(), fiber.time64()
+ ---
+ - 1385758828.9825
+ - 1385758828982485
+ ...
+
+=================================================
+ Example
+=================================================
+
+Make the function which will be associated with the fiber. This function
+contains an infinite loop ("while 0 == 0" is always true). Each iteration
+of the loop adds 1 to a global variable named gvar, then goes to sleep for
+2 seconds. The sleep causes an implicit ``fiber.yield()``.
+
+.. code-block:: lua
+
+ tarantool> fiber = require('fiber')
+ tarantool> console = require('console'); console.delimiter('!')
+ tarantool> function function_x()
+ -> gvar = 0
+ -> while 0 == 0 do
+ -> gvar = gvar + 1
+ -> fiber.sleep(2)
+ -> end
+ -> end!
+ ---
+ ...
+ tarantool> console.delimiter('')!
+
+Make a fiber, associate function_x with the fiber, and start function_x.
+It will immediately "detach" so it will be running independently of the caller.
+
+.. code-block:: lua
+
+ tarantool> fiber_of_x = fiber.create(function_x)
+ ---
+ ...
+
+Get the id of the fiber (fid), to be used in later displays.
+
+.. code-block:: lua
+
+ tarantool> fid = fiber_of_x:id()
+ ---
+ ...
+
+Pause for a while, while the detached function runs. Then ... Display the fiber
+id, the fiber status, and gvar (gvar will have gone up a bit depending how long
+the pause lasted). The status is suspended because the fiber spends almost all
+its time sleeping or yielding.
+
+.. code-block:: lua
+
+ tarantool> print('#',fid,'. ',fiber_of_x:status(),'. gvar=',gvar)
+ # 102 . suspended . gvar= 399
+ ---
+ ...
+
+Pause for a while, while the detached function runs. Then ... Cancel the fiber.
+Then, once again ... Display the fiber id, the fiber status, and gvar (gvar
+will have gone up a bit more depending how long the pause lasted). This time
+the status is dead because the cancel worked.
+
+.. code-block:: lua
+
+ tarantool> fiber_of_x:cancel()
+ ... fiber `lua' has been cancelled
+ ... fiber `lua': exiting
+ ---
+ ...
+ tarantool> print('#',fid,'. ',fiber_of_x:status(),'. gvar=',gvar)
+ # 102 . dead . gvar= 421
+ ---
+ ...
diff --git a/doc/sphinx/reference/fio.rst b/doc/sphinx/reference/fio.rst
new file mode 100644
index 0000000000000000000000000000000000000000..79b740565e9306a395a428f4cb68e32e720d3dc0
--- /dev/null
+++ b/doc/sphinx/reference/fio.rst
@@ -0,0 +1,431 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `fio`
+-------------------------------------------------------------------------------
+
+Tarantool supports file input/output with an API that is similar to POSIX
+syscalls. All operations are performed asynchronously. Multiple fibers can
+access the same file simultaneously.
+
+.. module:: fio
+
+=================================================
+ Common pathname manipulations
+=================================================
+
+.. function:: pathjoin(partial-string [, partial-string ...])
+
+ Concatenate partial string, separated by '/' to form a path name.
+
+ :param string partial-string: one or more strings to be concatenated.
+ :return: path name
+ :rtype: string
+
+ .. code-block:: lua
+
+ tarantool> fio.pathjoin('/etc', 'default', 'myfile')
+ ---
+ - /etc/default/myfile
+ ...
+
+.. function:: basename(path-name[, suffix])
+
+ Given a full path name, remove all but the final part (the file name).
+ Also remove the suffix, if it is passed.
+
+ :param string path-name: path name
+ :param string suffix: suffix
+
+ :return: file name
+ :rtype: string
+
+ .. code-block:: lua
+
+ tarantool> fio.basename('/path/to/my.lua', '.lua')
+ ---
+ - my
+ ...
+
+.. function:: dirname(path-name)
+
+ Given a full path name, remove the final part (the file name).
+
+ :param string path-name: path name
+
+ :return: directory name, that is, path name except for file name.
+ :rtype: string
+
+ .. code-block:: lua
+
+ tarantool> fio.dirname('/path/to/my.lua')
+ ---
+ - /path/to/
+ ...
+
+=================================================
+ Common file manipulations
+=================================================
+
+.. function:: umask(mask-bits)
+
+ Set the mask bits used when creating files or directories. For a detailed
+ description type "man 2 umask".
+
+ :param number mask-bits: mask bits.
+ :return: previous mask bits.
+ :rtype: number
+
+ .. code-block:: lua
+
+ tarantool> fio.umask(tonumber('755', 8)) -- pass 755 octal
+ ---
+ - 493
+ ...
+
+.. function:: lstat(path-name)
+ stat(path-name)
+
+ Returns information about a file object. For details type "man 2 lstat" or
+ "man 2 stat".
+
+ :param string path-name: path name of file.
+ :return: fields which describe the file's block size, creation time, size,
+ and other attributes.
+ :rtype: table
+
+ .. code-block:: lua
+
+ tarantool> fio.lstat('/etc')
+ ---
+ - inode: 1048577
+ rdev: 0
+ size: 12288
+ atime: 1421340698
+ mode: 16877
+ mtime: 1424615337
+ nlink: 160
+ uid: 0
+ blksize: 4096
+ gid: 0
+ ctime: 1424615337
+ dev: 2049
+ blocks: 24
+ ...
+
+.. function:: mkdir(path-name)
+ rmdir(path-name)
+
+ Create or delete a directory. For details type
+ "man 2 mkdir" or "man 2 rmdir".
+
+ :param string path-name: path of directory.
+ :return: true if success, false if failure.
+ :rtype: boolean
+
+ .. code-block:: lua
+
+ tarantool> fio.mkdir('/etc')
+ ---
+ - false
+ ...
+
+
+.. function:: glob(path-name)
+
+ Return a list of files that match an input string. The list is constructed
+ with a single flag that controls the behavior of the function: GLOB_NOESCAPE.
+ For details type "man 3 glob".
+
+ :param string path-name: path-name, which may contain wildcard characters.
+ :return: list of files whose names match the input string
+ :rtype: table
+ :except: nil on failure.
+
+ .. code-block:: lua
+
+ tarantool> fio.glob('/etc/x*')
+ ---
+ - - /etc/xdg
+ - /etc/xml
+ - /etc/xul-ext
+ ...
+
+
+.. function:: tempdir()
+
+ Return the name of a directory that can be used to store temporary files.
+
+ .. code-block:: lua
+
+ tarantool> fio.tempdir()
+ ---
+ - /tmp/lG31e7
+ ...
+
+.. function:: link (src , dst)
+ symlink (src , dst)
+ readlink (src)
+ unlink (src)
+
+ Functions to create and delete links. For details type "man readlink",
+ "man 2 link", "man 2 symlink", "man 2 unlink"..
+
+ :param string src: existing file name.
+ :param string dst: linked name.
+
+ :return: ``fio.link`` and ``fio.symlink`` and ``fio.unlink`` return true if
+ success, false if failure. ``fio.readlink`` returns the link value
+ if success, nil if failure.
+
+ .. code-block:: lua
+
+ tarantool> fio.link('/home/username/tmp.txt', '/home/username/tmp.txt2')
+ ---
+ - true
+ ...
+ tarantool> fio.unlink('/home/pgulutzan/tmp.txt2')
+ ---
+ - true
+ ...
+
+.. function:: rename(path-name, new-path-name)
+
+ Rename a file or directory. For details type "man 2 rename".
+
+ :param string path-name: original name.
+ :param string new-path-name: new name.
+
+ :return: true if success, false if failure.
+ :rtype: boolean
+
+ .. code-block:: lua
+
+ tarantool> fio.rename('/home/username/tmp.txt', '/home/username/tmp.txt2')
+ ---
+ - true
+ ...
+
+.. function:: chown(path-name, owner-user, owner-group)
+ chmod(path-name, new-rights)
+
+ Manage the rights to file objects, or ownership of file objects.
+ For details type "man 2 chown" or "man 2 chmod".
+
+ :param string owner-user: new user uid.
+ :param string owner-group: new group uid.
+ :param number new-rights: new permissions
+
+ .. code-block:: lua
+
+ tarantool> fio.chmod('/home/username/tmp.txt', tonumber('0755', 8))
+ ---
+ - true
+ ...
+ fio.chown('/home/username/tmp.txt', 'username', 'username')
+ ---
+ - true
+ ...
+
+.. function:: truncate(path-name, new-size)
+
+ Reduce file size to a specified value. For details type "man 2 truncate".
+
+ :param string path-name:
+ :param number new-size:
+
+ :return: true if success, false if failure.
+ :rtype: boolean
+
+ .. code-block:: lua
+
+ tarantool> fio.truncate('/home/username/tmp.txt', 99999)
+ ---
+ - true
+ ...
+
+.. function:: sync()
+
+ Ensure that changes are written to disk. For details type "man 2 sync".
+
+ :return: true if success, false if failure.
+ :rtype: boolean
+
+ .. code-block:: lua
+
+ tarantool> fio.sync()
+ ---
+ - true
+ ...
+
+.. function:: open(path-name [, flags])
+
+ Open a file in preparation for reading or writing or seeking.
+
+ :param string path-name:
+ :param number flags: Flags can be passed as a number or as string
+ constants, for example '``O_RDONLY``',
+ '``O_WRONLY``', '``O_RDWR``'. Flags can be
+ combined by enclosing them in braces.
+ :return: file handle (later - fh)
+ :rtype: userdata
+ :except: nil
+
+ .. code-block:: lua
+
+ tarantool> fh = fio.open('/home/username/tmp.txt', {'O_RDWR', 'O_APPEND'})
+ ---
+ ...
+ tarantool> fh -- display file handle returned by fio.open
+ ---
+ - fh: 11
+ ...
+
+.. class:: file-handle
+
+ .. method:: close()
+
+ Close a file that was opened with ``fio.open``. For details type "man 2 close".
+
+ :param userdata fh: file-handle as returned by ``fio.open()``.
+ :return: true if success, false on failure.
+ :rtype: boolean
+
+ .. code-block:: lua
+
+ tarantool> fh:close() -- where fh = file-handle
+ ---
+ - true
+ ...
+
+ .. method:: pread(count, offset)
+ pwrite(new-string, offset)
+
+ Perform read/write random-access operation on a file, without affecting
+ the current seek position of the file.
+ For details type "man 2 pread" or "man 2 pwrite".
+
+ :param userdata fh: file-handle as returned by ``fio.open()``.
+ :param number count: number of bytes to read
+ :param string new-string: value to write
+ :param number offset: offset within file where reading or writing begins
+ :return: ``fh:pwrite`` returns true if success, false if failure.
+ ``fh:pread`` returns the data that was read, or nil if failure.
+
+ .. code-block:: lua
+
+ tarantool> fh:pread(25, 25)
+ ---
+ - |-
+ elete from t8//
+ insert in
+ ...
+
+ .. method:: read(count)
+ write(new-string)
+
+ Perform non-random-access read or write on a file. For details type
+ "man 2 read" or "man 2 write".
+
+ .. NOTE::
+
+ ``fh:read`` and ``fh:write`` affect the seek position within the
+ file, and this must be taken into account when working on the same
+ file from multiple fibers. It is possible to limit or prevent file
+ access from other fibers with ``fiber.ipc``.
+
+ :param userdata fh: file-handle as returned by ``fio.open()``.
+ :param number count: number of bytes to read
+ :param string new-string: value to write
+ :return: ``fh:write`` returns true if success, false if failure.
+ ``fh:read`` returns the data that was read, or nil if failure.
+
+ .. code-block:: lua
+
+ tarantool> fh:write('new data')
+ ---
+ - true
+ ...
+
+ .. method:: truncate(new-size)
+
+ Change the size of an open file. Differs from ``fio.truncate``, which
+ changes the size of a closed file.
+
+ :param userdata fh: file-handle as returned by ``fio.open()``.
+ :return: true if success, false if failure.
+ :rtype: boolean
+
+ .. code-block:: lua
+
+ tarantool> fh:truncate(0)
+ ---
+ - true
+ ...
+
+ .. method:: seek(position [, offset-from])
+
+ Shift position in the file to the specified position. For details type
+ "man 2 seek".
+
+ :param userdata fh: file-handle as returned by ``fio.open()``.
+ :param number position: position to seek to
+ :param string offset-from: '``SEEK_END``' = end of file, '``SEEK_CUR``'
+ = current position, '``SEEK_SET``' = start of file.
+ :return: the new position if success
+ :rtype: number
+ :except: nil
+
+ .. code-block:: lua
+
+ tarantool> fh:seek(20, 'SEEK_SET')
+ ---
+ - 20
+ ...
+
+
+ .. method:: stat()
+
+ Return statistics about an open file. This differs from ``fio.stat``
+ which return statistics about a closed file. For details type "man 2 stat".
+
+ :param userdata fh: file-handle as returned by ``fio.open()``.
+ :return: details about the file.
+ :rtype: table
+
+ .. code-block:: lua
+
+ tarantool> fh:stat()
+ ---
+ - inode: 729866
+ rdev: 0
+ size: 100
+ atime: 1409429855
+ mode: 33261
+ mtime: 1409430660
+ nlink: 1
+ uid: 1000
+ blksize: 4096
+ gid: 1000
+ ctime: 1409430660
+ dev: 2049
+ blocks: 8
+ ...
+
+ .. method:: fsync()
+ fdatasync()
+
+ Ensure that file changes are written to disk, for an open file.
+ Compare ``fio.sync``, which is for all files. For details type
+ "man 2 fsync" or "man 2 fdatasync".
+
+ :param userdata fh: file-handle as returned by ``fio.open()``.
+ :return: true if success, false if failure.
+
+ .. code-block:: lua
+
+ tarantool> fh:fsync()
+ ---
+ - true
+ ...
diff --git a/doc/sphinx/reference/index.rst b/doc/sphinx/reference/index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..51d438df2b40b9a205b54dd21cd4e0db07d8f17d
--- /dev/null
+++ b/doc/sphinx/reference/index.rst
@@ -0,0 +1,24 @@
+-------------------------------------------------------------------------------
+ Reference Manual
+-------------------------------------------------------------------------------
+
+.. _Lua: http://www.lua.org
+
+.. toctree::
+ :maxdepth: 1
+
+ digest
+ uuid
+ json
+ yaml
+ msgpack
+ fiber
+ fiber-ipc
+ socket
+ fio
+ console
+ log
+ tap
+ pickle
+ other
+ expirationd
diff --git a/doc/sphinx/reference/json.rst b/doc/sphinx/reference/json.rst
new file mode 100644
index 0000000000000000000000000000000000000000..075909e90ba06d9f6616d44c4b56bb2b6b2c4ece
--- /dev/null
+++ b/doc/sphinx/reference/json.rst
@@ -0,0 +1,101 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `json`
+-------------------------------------------------------------------------------
+
+The json package provides JSON manipulation routines. It is based on the
+`Lua-CJSON package by Mark Pulford`_. For a complete manual on Lua-CJSON please read
+`the official documentation`_.
+
+.. module:: json
+
+.. function:: encode(lua-value)
+
+ Convert a Lua object to a JSON string.
+
+ :param lua_value: either a scalar value or a Lua table value.
+ :return: the original value reformatted as a JSON string.
+ :rtype: string
+
+ .. code-block:: lua
+
+ tarantool> json=require('json')
+ ---
+ ...
+ tarantool> json.encode(123)
+ ---
+ - '123'
+ ...
+ tarantool> json.encode({123})
+ ---
+ - '[123]'
+ ...
+ tarantool> json.encode({123, 234, 345})
+ ---
+ - '[123,234,345]'
+ ...
+ tarantool> json.encode({abc = 234, cde = 345})
+ ---
+ - '{"cde":345,"abc":234}'
+ ...
+ tarantool> json.encode({hello = {'world'}})
+ ---
+ - '{"hello":["world"]}'
+ ...
+
+.. function:: decode(string)
+
+ Convert a JSON string to a Lua object.
+
+ :param string string: a string formatted as JSON.
+ :return: the original contents formatted as a Lua table.
+ :rtype: table
+
+ .. code-block:: lua
+
+ tarantool> json=require('json')
+ ---
+ ...
+ tarantool> json.decode('123')
+ ---
+ - 123
+ ...
+ tarantool> json.decode('[123, "hello"]')[2]
+ ---
+ - hello
+ ...
+ tarantool> json.decode('{"hello": "world"}').hello
+ ---
+ - world
+ ...
+
+
+.. data:: NULL
+
+ A value comparable to Lua "nil" which may be useful as a placeholder in a tuple.
+
+ .. code-block:: lua
+
+ tarantool> -- When nil is assigned to a Lua-table field, the field is null
+ tarantool> {nil, 'a', 'b'}
+ - - null
+ - a
+ - b
+ ...
+ tarantool> -- When json.NULL is assigned to a Lua-table field, the field is json.NULL
+ tarantool> {json.NULL, 'a', 'b'}
+ ---
+ - - null
+ - a
+ - b
+ ...
+ tarantool> -- When json.NULL is assigned to a JSON field, the field is null
+ tarantool> json.encode({field2 = json.NULL, field1 = 'a', field3 = 'c'})
+ ---
+ - '{"field2":null,"field1":"a","field3":"c"}'
+ ...
+
+.. _Lua-CJSON package by Mark Pulford: http://www.kyne.com.au/~mark/software/lua-cjson.php
+.. _the official documentation: http://www.kyne.com.au/~mark/software/lua-cjson-manual.html
diff --git a/doc/sphinx/reference/log.rst b/doc/sphinx/reference/log.rst
new file mode 100644
index 0000000000000000000000000000000000000000..835982e13609647d43f32cd98fbcd8e335686823
--- /dev/null
+++ b/doc/sphinx/reference/log.rst
@@ -0,0 +1,61 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `log`
+-------------------------------------------------------------------------------
+
+.. module:: log
+
+The Tarantool server puts all diagnostic messages in a log file specified by
+the :ref:`logger <logger>` configuration parameter. Diagnostic messages may be either
+system-generated by the server's internal code, or user-generated with the
+``log.log_level_function_name`` function.
+
+.. function:: error(message)
+ warn(message)
+ info(message)
+ debug(message)
+
+ Output a user-generated message to the :ref:`log file <logger>`, given
+ log_level_function_name = ``error`` or ``warn`` or ``info`` or ``debug``.
+
+ :param string message: The actual output will be a line containing the
+ current timestamp, a module name, 'E' or 'W' or
+ 'I' or 'D' or 'R' depending on
+ ``log_level_function_name``, and ``message``.
+ Output will not occur if ``log_level_function_name``
+ is for a type greater than :ref:`log_level <logger>`.
+ :return: nil
+
+.. function:: logger_pid()
+
+.. function:: rotate()
+
+=================================================
+ Example
+=================================================
+
+.. code-block:: lua
+
+ #From the shell:
+ #Start the server, do some requests, exit, and display the log, thus:
+ $ ~/tarantool/src/tarantool
+ tarantool> box.cfg{log_level=3, logger='tarantool.txt'}
+ tarantool> log = require('log')
+ tarantool> log.error('Error')
+ tarantool> log.info('Info')
+ tarantool> os.exit()
+ $ less tarantool.txt
+
+The output from the less command will look approximately like this:
+
+.. code-block:: lua
+
+ 2...0 [5257] main/101/interactive C> version 1.6.3-355-ga4f762d
+ 2...1 [5257] main/101/interactive C> log level 3
+ 2...1 [5261] main/101/spawner C> initialized
+ 2...0 [5257] main/101/interactive [C]:-1 E> Error
+
+The 'Error' line is visible in tarantool.txt preceded by the letter E.
+The 'Info' line is not present because the log_level is 3.
diff --git a/doc/sphinx/reference/msgpack.rst b/doc/sphinx/reference/msgpack.rst
new file mode 100644
index 0000000000000000000000000000000000000000..73d0bc5577ecab37fb3876754fa4ddbe23dfc0ba
--- /dev/null
+++ b/doc/sphinx/reference/msgpack.rst
@@ -0,0 +1,60 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `msgpack`
+-------------------------------------------------------------------------------
+
+The ``msgpack`` package takes strings in MsgPack_ format and decodes them, or takes a
+series of non-MsgPack values and encodes them.
+
+.. module:: msgpack
+
+.. function:: encode(lua_value)
+
+ Convert a Lua object to a MsgPack string.
+
+ :param lua_value: either a scalar value or a Lua table value.
+ :return: the original value reformatted as a MsgPack string.
+ :rtype: string
+
+.. function:: decode(string)
+
+ Convert a MsgPack string to a Lua object.
+
+ :param string: a string formatted as YAML.
+ :return: the original contents formatted as a Lua table.
+ :rtype: table
+
+.. data:: NULL
+
+ A value comparable to Lua "nil" which may be useful as a placeholder in a tuple.
+
+=================================================
+ Example
+=================================================
+
+.. code-block:: lua
+
+ tarantool> msgpack = require('msgpack')
+ ---
+ ...
+ tarantool> y = msgpack.encode({'a',1,'b',2})
+ ---
+ ...
+ tarantool> z = msgpack.decode(y)
+ ---
+ ...
+ tarantool> z[1],z[2],z[3],z[4]
+ ---
+ - a
+ - 1
+ - b
+ - 2
+ ...
+ tarantool> box.space.tester:insert{20,msgpack.NULL,20}
+ ---
+ - [20, null, 20]
+ ...
+
+.. _MsgPack: http://msgpack.org/
diff --git a/doc/sphinx/reference/other.rst b/doc/sphinx/reference/other.rst
new file mode 100644
index 0000000000000000000000000000000000000000..297d672cd0008fb70a0fa5667a51b576d218e458
--- /dev/null
+++ b/doc/sphinx/reference/other.rst
@@ -0,0 +1,78 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Miscellaneous
+-------------------------------------------------------------------------------
+
+.. function:: tonumber64(value)
+
+ Convert a string or a Lua number to a 64-bit integer. The result can be
+ used in arithmetic, and the arithmetic will be 64-bit integer arithmetic
+ rather than floating-point arithmetic. (Operations on an unconverted Lua
+ number use floating-point arithmetic.) The ``tonumber64()`` function is
+ added by Tarantool; the name is global.
+
+ .. code-block:: lua
+
+ tarantool> type(123456789012345), type(tonumber64(123456789012345))
+ ---
+ - number
+ - number
+ ...
+ tarantool> i = tonumber64('1000000000')
+ ---
+ ...
+ tarantool> type(i), i / 2, i - 2, i * 2, i + 2, i % 2, i ^ 2
+ ---
+ - number
+ - 500000000
+ - 999999998
+ - 2000000000
+ - 1000000002
+ - 0
+ - 1000000000000000000
+ ...
+
+.. function:: dostring(lua-chunk-string [, lua-chunk-string-argument ...])
+
+ Parse and execute an arbitrary chunk of Lua code. This function is mainly
+ useful to define and run Lua code without having to introduce changes to
+ the global Lua environment.
+
+ :param string lua-chunk-string: Lua code
+ :param lua-value lua-chunk-string-argument: zero or more scalar values
+ which will be appended to, or substitute for,
+ items in the Lua chunk.
+ :return: whatever is returned by the Lua code chunk.
+ :except: If there is a compilation error, it is raised as a Lua error.
+
+ .. code-block:: lua
+
+ tarantool> dostring('abc')
+ ---
+ error: '[string "abc"]:1: ''='' expected near ''<eof>'''
+ ...
+ tarantool> dostring('return 1')
+ ---
+ - 1
+ ...
+ tarantool> dostring('return ...', 'hello', 'world')
+ ---
+ - hello
+ - world
+ ...
+ tarantool> console = require('console'); console.delimiter('!')
+ tarantool> -- This means ignore line feeds until next '!'
+ tarantool> -- Use `double square brackets`_ to enclose multi-line literal here!
+ tarantool> dostring([[local f = function(key)
+ -> t = box.space.tester:select{key};
+ -> if t ~= nil then return t[1] else return nil end
+ -> end
+ -> return f(...)]], 1)!
+ ---
+ - null
+ ...
+ tarantool> console.delimiter('')!
+
+.. _double square brackets: http://www.lua.org/pil/2.4.html
diff --git a/doc/sphinx/reference/pickle.rst b/doc/sphinx/reference/pickle.rst
new file mode 100644
index 0000000000000000000000000000000000000000..a74f83ca0aa3d68b412a9ba996bfda1481e8095e
--- /dev/null
+++ b/doc/sphinx/reference/pickle.rst
@@ -0,0 +1,142 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `pickle`
+-------------------------------------------------------------------------------
+
+.. module:: pickle
+
+.. function:: pack(format, argument [, argument ...])
+
+ To use Tarantool binary protocol primitives from Lua, it's necessary to
+ convert Lua variables to binary format. The ``pickle.pack()`` helper
+ function is prototyped after Perl 'pack_'.
+
+
+ .. container:: table
+
+ **Format specifiers**
+
+ +------+-------------------------------------------------+
+ | b, B | converts Lua variable to a 1-byte integer, |
+ | | and stores the integer in the resulting string |
+ +------+-------------------------------------------------+
+ | s, S | converts Lua variable to a 2-byte integer, and |
+ | | stores the integer in the resulting string, |
+ | | low byte first |
+ +------+-------------------------------------------------+
+ | i, I | converts Lua variable to a 4-byte integer, and |
+ | | stores the integer in the resulting string, low |
+ | | byte first |
+ +------+-------------------------------------------------+
+ | l, L | converts Lua variable to an 8-byte integer, and |
+ | | stores the integer in the resulting string, low |
+ | | byte first |
+ +------+-------------------------------------------------+
+ | n | converts Lua variable to a 2-byte integer, and |
+ | | stores the integer in the resulting string, big |
+ | | endian, |
+ +------+-------------------------------------------------+
+ | N | converts Lua variable to a 4-byte integer, and |
+ | | stores the integer in the resulting string, big |
+ +------+-------------------------------------------------+
+ | q, Q | converts Lua variable to an 8-byte integer, and |
+ | | stores the integer in the resulting string, big |
+ | | endian, |
+ +------+-------------------------------------------------+
+ | f | converts Lua variable to a 4-byte float, and |
+ | | stores the float in the resulting string |
+ +------+-------------------------------------------------+
+ | d | converts Lua variable to a 8-byte double, and |
+ | | stores the double in the resulting string |
+ +------+-------------------------------------------------+
+ | a, A | converts Lua variable to a sequence of bytes, |
+ | | and stores the sequence in the resulting string |
+ +------+-------------------------------------------------+
+
+ :param string format: string containing format specifiers
+ :param scalar-value argument(s): scalar values to be formatted
+ :return: a binary string containing all arguments,
+ packed according to the format specifiers.
+ :rtype: string
+
+ :except: unknown format specifier.
+
+ .. code-block:: lua
+
+ tarantool> pickle = require('pickle')
+ ---
+ ...
+ tarantool> box.space.tester:insert{0, 'hello world'}
+ ---
+ - [0, 'hello world']
+ ...
+ tarantool> box.space.tester:update({0}, {{'=', 2, 'bye world'}})
+ ---
+ - [0, 'bye world']
+ ...
+ tarantool> box.space.tester:update({0}, {{'=', 2, pickle.pack('iiA', 0, 3, 'hello')}})
+ ---
+ - [0, "\0\0\0\0\x03\0\0\0hello"]
+ ...
+ tarantool> box.space.tester:update({0}, {{'=', 2, 4}})
+ ---
+ - [0, 4]
+ ...
+ tarantool> box.space.tester:update({0}, {{'+', 2, 4}})
+ ---
+ - [0, 8]
+ ...
+ tarantool> box.space.tester:update({0}, {{'^', 2, 4}})
+ ---
+ - [0, 12]
+ ...
+
+.. function:: unpack(format, binary-string)
+
+ Counterpart to ``pickle.pack()``.
+
+ :param string format:
+ :param string binary-string:
+
+ :return: A list of strings or numbers.
+ :rtype: table
+
+ .. code-block:: lua
+
+ tarantool> pickle = require('pickle')
+ ---
+ ...
+ tarantool> -- this means following commands must end with '!'
+ tarantool> console = require('console'); console.delimiter('!')
+ tarantool> tuple = box.space.tester:replace{0}!
+ ---
+ ...
+ tarantool> string.len(tuple[1])!
+ ---
+ - 1
+ ...
+ tarantool> pickle.unpack('b', tuple[1])!
+ ---
+ - 48
+ ...
+ tarantool> pickle.unpack('bsi', pickle.pack('bsi', 255, 65535, 4294967295))!
+ ---
+ - 255
+ - 65535
+ - 4294967295
+ ...
+ tarantool> pickle.unpack('ls', pickle.pack('ls', tonumber64('18446744073709551615'), 65535))!
+ ---
+ - 18446744073709551615
+ - 65535
+ ...
+ tarantool> num, str, num64 = pickle.unpack('sAl', pickle.pack('sAl', 666, 'string',
+ -> tonumber64('666666666666666')))!
+ ---
+ ...
+ tarantool> console.delimiter('') -- back to normal: commands end with line feed!
+
+
+.. _pack: http://perldoc.perl.org/functions/pack.html
diff --git a/doc/sphinx/reference/socket.rst b/doc/sphinx/reference/socket.rst
new file mode 100644
index 0000000000000000000000000000000000000000..0ffdf70b0c96fbc3ca86472dd44fc1dd35e42ba3
--- /dev/null
+++ b/doc/sphinx/reference/socket.rst
@@ -0,0 +1,516 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `socket`
+-------------------------------------------------------------------------------
+
+The ``socket`` package allows exchanging data via BSD sockets with a local or
+remote host in connection-oriented (TCP) or datagram-oriented (UDP) mode.
+Semantics of the calls in the ``socket`` API closely follow semantics of the
+corresponding POSIX calls. Function names and signatures are mostly compatible
+with `luasocket`_.
+
+The functions for setting up and connecting are ``socket``, ``sysconnect``,
+``tcp_connect``. The functions for sending data are ``send``, ``sendto``,
+``write``, ``syswrite``. The functions for receiving data are ``recv``,
+``recvfrom``, ``read``. The functions for waiting before sending/receiving
+data are ``wait``, ``readable``, ``writable``. The functions for setting
+flags are ``nonblock``, ``setsockopt``. The functions for stopping and
+disconnecting are ``shutdown``, ``close``. The functions for error checking
+are ``errno``, ``error``.
+
+.. container:: table
+
+ **Socket functions**
+
+ +----------------+-------------+
+ | Purposes | Names |
+ +================+=============+
+ | | socket |
+ | +-------------+
+ | setup | sysconnect |
+ | +-------------+
+ | | tcp_connect |
+ +----------------+-------------+
+ | | send |
+ | +-------------+
+ | | sendto |
+ | sending +-------------+
+ | | write |
+ | +-------------+
+ | | syswrite |
+ +----------------+-------------+
+ | | recv |
+ | +-------------+
+ | receiving | recvfrom |
+ | +-------------+
+ | | read |
+ +----------------+-------------+
+ | | nonblock |
+ | +-------------+
+ | flag setting | setsockopt |
+ | +-------------+
+ | | linger |
+ +----------------+-------------+
+ | | listen |
+ | client/server +-------------+
+ | | accept |
+ +----------------+-------------+
+ | | shutdown |
+ | teardown +-------------+
+ | | close |
+ +----------------+-------------+
+ | | error |
+ | error checking +-------------+
+ | | errno |
+ +----------------+-------------+
+ | | getaddrinfo |
+ | +-------------+
+ | | getsockopt |
+ | information +-------------+
+ | | peer |
+ | +-------------+
+ | | name |
+ +----------------+-------------+
+
+
+Typically a socket session will begin with the setup functions, will set one
+or more flags, will have a loop with sending and receiving functions, will
+end with the teardown functions -- as an example at the end of this section
+will show. Throughout, there may be error-checking and waiting functions for
+synchronization. Some functions may "block" if a non-default option flag is
+set, therefore the fiber that they are in will yield so that other processes
+may take over, as is the norm for cooperative multitasking.
+
+For all examples in this section the socket name will be sock and
+the function invocations will look like ``sock:function_name(...)``.
+
+.. module:: socket
+
+.. function:: __call(domain, type, protocol)
+
+ Create a new TCP or UDP socket. The argument values
+ are the same as in the `Linux man page <http://man7.org/linux/man-pages/man2/socket.2.html>`_.
+
+ :param domain:
+ :param type:
+ :param protocol:
+ :return: a new socket, or nil.
+ :rtype: userdata
+
+.. function:: tcp_connect(host, port)
+ tcp_connect(host)
+
+ Connect a socket to a remote host.
+
+ :param string host: URL or IP address
+ :param number port: port number
+ :return: a connected socket, if no error.
+ :rtype: userdata
+
+.. function:: getaddrinfo(host, type, [, {option-list}])
+
+ The ``socket.getaddrinfo()`` function is useful for finding information
+ about a remote site so that the correct arguments for
+ ``sock:sysconnect()`` can be passed.
+
+ :return: A table containing these fields: "host", "family", "type", "protocol", "port".
+ :rtype: table
+
+ .. code-block:: lua
+
+ tarantool> socket.getaddrinfo('tarantool.org', 'http')
+
+ will return variable information such as
+
+ .. code-block:: yaml
+
+ ---
+ - - host: 188.93.56.70
+ family: AF_INET
+ type: SOCK_STREAM
+ protocol: tcp
+ port: 80
+ - host: 188.93.56.70
+ family: AF_INET
+ type: SOCK_DGRAM
+ protocol: udp
+ port: 80
+ ...
+
+.. function:: tcp_server(host, port, handler-function)
+
+ The ``socket.tcp_server()`` function makes Tarantool act as a server that
+ can accept connections. Usually the same objective
+ is accomplished with ``box.cfg{listen=...)``.
+
+ .. code-block:: lua
+
+ socket.tcp_server('localhost', 3302, function () end).
+
+.. class:: socket_object
+
+ .. method:: sysconnect(host, port)
+
+ Connect a socket to a remote host. The argument values are the same as
+ in the Linux man page [1]_.
+ The host must be an IP address.
+
+ Parameters:
+ * Either:
+ * host - a string representation of an IPv4 address
+ or an IPv6 address;
+ * port - a number.
+ * Or:
+ * host - a string containing "unix/";
+ * port - a string containing a path to a unix socket.
+ * Or:
+ * host - a number, 0 (zero), meaning "all local
+ interfaces";
+ * port - a number. If a port number is 0 (zero),
+ the socket will be bound to a random local port.
+
+
+ :return: a connected socket, if no error.
+ :rtype: userdata
+
+ .. code-block:: lua
+
+ sock:sysconnect('127.0.0.1', 80)
+
+ .. method:: send(data)
+ write(data)
+
+ Send data over a connected socket.
+
+ :param string data:
+ :return: true if success, false if error.
+ :rtype: boolean
+
+ .. method:: syswrite(size)
+
+ Write as much as possible data to the socket buffer if non-blocking.
+ Rarely used. For details see `this description`_.
+
+ .. method:: recv(size)
+
+ Read ``size`` bytes from a connected socket. An internal read-ahead
+ buffer is used to reduce the cost of this call.
+
+ :param integer size:
+ :return: a string of the requested length on success.
+ :rtype: string
+ :exception: On error, returns an empty string, followed by status,
+ errno, errstr. In case the writing side has closed its
+ end, returns the remainder read from the socket (possibly
+ an empty string), followed by "eof" status.
+
+ .. method:: read(limit [, timeout])
+ read(delimiter [, timeout])
+ read({limit=limit} [, timeout])
+ read({delimiter=delimiter} [,timeout])
+ read({limit=limit, delimiter=delimiter} [, timeout])
+
+ Read from a connected socket until some condition is true, and return
+ the bytes that were read.
+ Reading goes on until ``limit`` bytes have been read, or a delimiter
+ has been read, or a timeout has expired.
+
+ :param integer limit: maximum number of bytes to read for
+ example 50 means "stop after 50 bytes"
+ :param string delimiter: separator or `Lua pattern`_ for example
+ '[0-9]' means "stop after a digit"
+ :param number timeout: maximum number of seconds to wait for
+ example 50 means "stop after 50 seconds".
+
+ :return: an empty string if there is nothing more to read, or a nil
+ value if error, or a string up to ``limit`` bytes long,
+ which may include the bytes that matched the ``delimiter``
+ expression.
+ :rtype: string
+
+ .. method:: sysread(size)
+
+ Return all available data from the socket buffer if non-blocking.
+ Rarely used. For details see `this description`_.
+
+ .. method:: bind(host [, port])
+
+ Bind a socket to the given host/port. A UDP socket after binding
+ can be used to receive data (see :func:`socket_object.recvfrom`).
+ A TCP socket can be used to accept new connections, after it has
+ been put in listen mode.
+
+ :param host:
+ :param port:
+
+ :return: a socket object on success
+ :rtype: userdata
+ :exception: nil, status, errno, errstr on error.
+
+
+ .. method:: listen(backlog)
+
+ Start listening for incoming connections.
+
+ :param backlog: On Linux the listen ``backlog`` backlog may be from
+ /proc/sys/net/core/somaxconn, on BSD the backlog
+ may be ``SOMAXCONN``.
+
+ :return: true for success, false for error.
+ :rtype: boolean.
+
+ .. method:: accept()
+
+ Accept a new client connection and create a new connected socket.
+ It is good practice to set the socket's blocking mode explicitly
+ fter accepting.
+
+ :return: new socket if success.
+ :rtype: userdata
+ :exception: nil
+
+ .. method:: sendto(host, port, data)
+
+ Send a message on a UDP socket to a specified host.
+
+ :param string host:
+ :param number port:
+ :param string data:
+
+ :return: the number of bytes sent.
+ :rtype: number
+ :exception: status, errno, errstr.
+
+ .. method:: recvfrom(limit)
+
+ Receive a message on a UDP socket.
+
+ :param integer limit:
+ :return: message, a table containing "host", "family" and "port" fields.
+ :rtype: string, table
+ :exception: status, errno, errstr.
+
+ After
+
+ .. code-block:: lua
+
+ message_content, message_sender = recvfrom(1)
+
+ the value of ``message_content`` might be a string containing 'X' and
+ the value of ``message_sender`` might be a table containing
+ ``message_sender.host = '18.44.0.1'``,
+ ``message_sender.family = 'AF_INET'``,
+ ``message_sender.port = 43065``.
+
+ .. method:: shutdown(how)
+
+ Shutdown a reading end, a writing end, or both ends of a socket.
+
+ :param how: socket.SHUT_RD, socket.SHUT_WR, or socket.SHUT_RDWR.
+
+ :return: true or false.
+ :rtype: boolean
+
+ .. method:: close()
+
+ Close (destroy) a socket. A closed socket should not be used any more.
+ A socket is closed automatically when its userdata is garbage collected by Lua.
+
+ :return: true on success, false on error. For example, if
+ sock is already closed, sock:close() returns false.
+ :rtype: boolean
+
+ .. method:: error()
+ errno()
+
+ Retrieve information about the last error that occurred on a socket, if any.
+ Errors do not cause throwing of exceptions so these functions are usually necessary.
+
+ :return: result for ``sock:errno()``, result for ``sock:error()``.
+ If there is no error, then ``sock:errno()`` will return 0 and ``sock:error()``.
+ :rtype: number, string
+
+ .. method:: setsockopt(level, name, value)
+
+ Set socket flags. The argument values are the same as in the
+ Linux man page [2]_.
+ The ones that Tarantool accepts are:
+
+ * SO_ACCEPTCONN
+ * SO_BINDTODEVICE
+ * SO_BROADCAST
+ * SO_BSDCOMPAT
+ * SO_DEBUG
+ * SO_DOMAIN
+ * SO_ERROR
+ * SO_DONTROUTE
+ * SO_KEEPALIVE
+ * SO_MARK
+ * SO_OOBINLINE
+ * SO_PASSCRED
+ * SO_PEERCRED
+ * SO_PRIORITY
+ * SO_PROTOCOL
+ * SO_RCVBUF
+ * SO_RCVBUFFORCE
+ * SO_RCVLOWAT
+ * SO_SNDLOWAT
+ * SO_RCVTIMEO
+ * SO_SNDTIMEO
+ * SO_REUSEADDR
+ * SO_SNDBUF
+ * SO_SNDBUFFORCE
+ * SO_TIMESTAMP
+ * SO_TYPE
+
+ Setting SO_LINGER is done with ``sock:linger(active)``.
+
+ .. method:: getsockopt(level, name)
+
+ Get socket flags. For a list of possible flags see ``sock:setsockopt()``.
+
+ .. method:: linger([active])
+
+ Set or clear the SO_LINGER flag. For a description of the flag, see
+ Linux man page [3]_.
+
+ :param boolean active:
+
+ :return: new active and timeout values.
+
+ .. method:: nonblock([flag])
+
+ ``sock:nonblock()`` returns the current flag value. |br|
+ ``sock:nonblock(false)`` sets the flag to false and returns false. |br|
+ ``sock:nonblock(true)`` sets the flag to true and returns true.
+ This function may be useful before invoking a function which might
+ otherwise block indefinitely.
+
+ .. method:: readable([timeout])
+ writeable([timeout])
+ wait([timout])
+
+ ``sock:readable()`` waits until something is readable, or until a timeout value expires. |br|
+ ``sock:writable()`` waits until something is writable, or until a timeout value expires. |br|
+ ``sock:wait()`` waits until something is either readable or writable, or until a timeout value expires.
+
+ .. method:: name()
+
+ The ``The sock:name()`` function is used to get information about the
+ near side of the connection. If a socket was bound to ``xyz.com:45``,
+ then ``sock:name`` will return information about ``[host:xyz.com, port:45]``.
+ The equivalent POSIX function is ``getsockname()``.
+
+ :return: A table containing these fields: "host", "family", "type", "protocol", "port".
+ :rtype: table
+
+ .. method:: peer()
+
+ The ``sock:peer()`` function is used to get information about the far side of a connection.
+ If a TCP connection has been made to a distant host ``tarantool.org:80``, ``sock:peer()``
+ will return information about ``[host:tarantool.org, port:80]``.
+ The equivalent POSIX function is ``getpeername()``.
+
+ :return: A table containing these fields: "host", "family", "type", "protocol", "port".
+ :rtype: table
+
+.. _Lua pattern: http://www.lua.org/pil/20.2.html
+.. _this description: https://github.com/tarantool/tarantool/wiki/sockets%201.6
+
+=================================================
+ Example
+=================================================
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Use of a TCP socket over the Internet
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this example a connection is made over the internet between the Tarantool
+server and tarantool.org, then an HTTP "head" message is sent, and a response
+is received: "``HTTP/1.1 200 OK``". This is not a useful way to communicate
+with this particular site, but shows that the system works.
+
+
+.. code-block:: lua
+
+ tarantool> socket = require('socket')
+ ---
+ ...
+ tarantool> sock = socket.tcp_connect('tarantool.org', 80)
+ ---
+ ...
+ tarantool> type(sock)
+ ---
+ - table
+ ...
+ tarantool> sock:error()
+ ---
+ - null
+ ...
+ tarantool> sock:send("HEAD / HTTP/1.0\r\nHost: tarantool.org\r\n\r\n")
+ ---
+ - true
+ ...
+ tarantool> sock:read(17)
+ ---
+ - "HTTP/1.1 200 OK\r\n"
+ ...
+ tarantool> sock:close()
+ ---
+ - true
+ ...
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ Use of a UDP socket on localhost
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here is an example with datagrams. Set up two connections on 127.0.0.1
+(localhost): ``sock_1`` and ``sock_2``. Using ``sock_2``, send a message
+to ``sock_1``. Using ``sock_1``, receive a message. Display the received
+message. Close both connections. |br| This is not a useful way for a
+computer to communicate with itself, but shows that the system works.
+
+.. code-block:: lua
+
+ tarantool> socket = require('socket')
+ ---
+ ...
+ tarantool> sock_1 = socket('AF_INET', 'SOCK_DGRAM', 'udp')
+ ---
+ ...
+ tarantool> sock_1:bind('127.0.0.1')
+ ---
+ - true
+ ...
+ tarantool> sock_2 = socket('AF_INET', 'SOCK_DGRAM', 'udp')
+ ---
+ ...
+ tarantool> sock_2:sendto('127.0.0.1', sock_1:name().port,'X')
+ ---
+ - true
+ ...
+ tarantool> message = sock_1:recvfrom()
+ ---
+ ...
+ tarantool> message
+ ---
+ - X
+ ...
+ tarantool> sock_1:close()
+ ---
+ - true
+ ...
+ tarantool> sock_2:close()
+ ---
+ - true
+ ...
+
+
+.. _luasocket: https://github.com/diegonehab/luasocket
+
+.. [1] http://man7.org/linux/man-pages/man2/connect.2.html
+.. [2] http://man7.org/linux/man-pages/man2/setsockopt.2.html
+.. [3] http://man7.org/linux/man-pages/man1/loginctl.1.html
+
diff --git a/doc/sphinx/reference/tap.rst b/doc/sphinx/reference/tap.rst
new file mode 100644
index 0000000000000000000000000000000000000000..04ff65c71a61495c9f98a50a4a962b7a20bff0b3
--- /dev/null
+++ b/doc/sphinx/reference/tap.rst
@@ -0,0 +1,207 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `tap`
+-------------------------------------------------------------------------------
+
+The tap package streamlines the testing of other packages. It allows writing of
+tests in the `TAP protocol`_. The results from the tests can be parsed by
+standard TAP-analyzers so they can be passed to utilities such as `prove`_. Thus
+one can run tests and then use the results for statistics, decision-making, and so on.
+
+.. module:: tap
+
+.. function:: test(test-name)
+
+ Initialize. |br|
+ The result of ``tap.test`` is an object, which will be called taptest
+ in the rest of this discussion, which is necessary for
+ ``taptest:plan()`` and all the other methods.
+
+ :param string test-name: an arbitrary name to give for the test outputs.
+ :return: taptest
+ :rtype: userdata
+
+ .. code-block:: lua
+
+ tap = require('tap')
+ taptest = tap.test('test-name')
+
+.. class:: taptest
+
+ .. method:: plan(count)
+
+ Indicate how many tests will be performed.
+
+ :param number count:
+ :return: nil
+
+ .. method:: check()
+
+ Checks the number of tests performed. This check should only be done
+ after all planned tests are complete, so ordinarily ``taptest:check()``
+ will only appear at the end of a script.
+
+ Will display ``# bad plan: ...`` if the number of completed tests is not
+ equal to the number of tests specified by ``taptest:plan(...)``.
+
+ :return: nil
+
+ .. method:: diag(message)
+
+ Display a diagnostic message.
+
+ :param string message: the message to be displayed.
+ :return: nil
+
+ .. method:: ok(condition, test-name)
+
+ This is a basic function which is used by other functions. Depending
+ on the value of ``condition``, print 'ok' or 'not ok' along with
+ debugging information. Displays the message.
+
+ :param boolean condition: an expression which is true or false
+ :param string test-name: name of test
+
+ :return: true or false.
+ :rtype: boolean
+
+ .. code-block:: lua
+
+ tarantool> taptest:ok(true,'x')
+ ok - x
+ ---
+ - true
+ ...
+ tarantool> tap = require('tap')
+ ---
+ ...
+ tarantool> taptest = tap.test('test-name')
+ TAP version 13
+ ---
+ ...
+ tarantool> taptest:ok(1 + 1 == 2, 'X')
+ ok - X
+ ---
+ - true
+ ...
+
+ .. method:: fail(test-name)
+
+ ``taptest:fail('x')`` is equivalent to ``taptest:ok(false, 'x')``.
+ Displays the message.
+
+ :param string test-name: name of test
+
+ :return: true or false.
+ :rtype: boolean
+
+ .. method:: skip(message)
+
+ ``taptest:skip('x')`` is equivalent to
+ ``taptest:ok(true, 'x' .. '# skip')``.
+ Displays the message.
+
+ :param string test-name: name of test
+
+ :return: nil
+
+ .. code-block:: lua
+
+ tarantool> taptest:skip('message')
+ ok - message # skip
+ ---
+ - true
+ ...
+
+ .. method:: is(got, expected, test-name)
+
+ Check whether the first argument equals the second argument.
+ Displays extensive message if the result is false.
+
+ :param number got: actual result
+ :param number expected: expected result
+ :param string test-name: name of test
+ :return: true or false.
+ :rtype: boolean
+
+ .. method:: isnt(got, expected, test-name)
+
+ This is the negation of ``taptest:is(...)``.
+
+ :param number got: actual result
+ :param number expected: expected result
+ :param string test-name: name of test
+
+ :return: true of false.
+ :rtype: boolean
+
+ .. method:: isnil(value, test-name)
+ isstring(value, test-name)
+ isnumber(value, test-name)
+ istable(value, test-name)
+ isboolean(value, test-name)
+ isudata(value, test-name)
+ iscdata(value, test-name)
+
+ Test whether a value has a particular type. Displays a long message if
+ the value is not of the specified type.
+
+ :param lua-value value:
+ :param string test-name: name of test
+
+ :return: true of false.
+ :rtype: boolean
+
+ .. method:: is_deeply(got, expected, test-name)
+
+ Recursive version of ``tap-test:is(...)``, which can be be used to
+ compare tables as well as scalar values.
+
+ :return: true of false.
+ :rtype: boolean
+
+ :param lua-value got: actual result
+ :param lua-value expected: expected result
+ :param string test-name: name of test
+
+
+.. _prove: https://metacpan.org/pod/distribution/Test-Harness/bin/prove
+.. _TAP protocol: https://en.wikipedia.org/wiki/Test_Anything_Protocol
+
+=================================================
+ Example
+=================================================
+
+To run this example: put the script in a file named ./tap.lua, then make
+tap.lua executable by saying ``chmod a+x ./tap.lua``, then execute using
+Tarantool as a script processor by saying ./tap.lua.
+
+.. code-block:: lua
+
+ #!/usr/bin/tarantool
+ local tap = require('tap')
+ test = tap.test("my test name")
+ test:plan(2)
+ test:ok(2 * 2 == 4, "2 * 2 is 4")
+ test:test("some subtests for test2", function(test)
+ test:plan(2)
+ test:is(2 + 2, 4, "2 + 2 is 4")
+ test:isnt(2 + 3, 4, "2 + 3 is not 4")
+ end)
+ test:check()
+
+The output from the above script will look approximately like this:
+
+.. code-block:: tap
+
+ TAP version 13
+ 1..2
+ ok - 2 * 2 is 4
+ # Some subtests for test2
+ 1..2
+ ok - 2 + 2 is 4,
+ ok - 2 + 3 is not 4
+ # Some subtests for test2: end
+ ok - some subtests for test2
diff --git a/doc/sphinx/reference/uuid.rst b/doc/sphinx/reference/uuid.rst
new file mode 100644
index 0000000000000000000000000000000000000000..c40bb52d9e1a89d8e64ba2265595f48ad3b1e1d0
--- /dev/null
+++ b/doc/sphinx/reference/uuid.rst
@@ -0,0 +1,105 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `uuid`
+-------------------------------------------------------------------------------
+
+A "UUID" is a `Universally unique identifier`_. If an application requires that
+a value be unique only within a single computer or on a single database, then a
+simple counter is better than a UUID, because getting a UUID is time-consuming
+(it requires a syscall_). For clusters of computers, or widely distributed
+applications, UUIDs are better.
+
+The functions that can return a UUID are: ``uuid()``, ``uuid.bin()``, ``uuid.str()``. |br|
+The functions that can convert between different types of UUID are: ``:bin()``, ``:str()``, ``uuid.fromstr()``, ``uuid.frombin()``. |br|
+The function that can determine whether a UUID is an all-zero value is: ``:isnil()``.
+
+.. module:: uuid
+
+.. data:: nil
+
+ A nil object
+
+.. function:: __call()
+
+ :return: a UUID
+ :rtype: cdata
+
+.. function:: bin()
+
+ :return: a UUID
+ :rtype: 16-byte string
+
+.. function:: str()
+
+ :return: a UUID
+ :rtype: 36-byte binary string
+
+.. function:: fromstr(uuid_str)
+
+ :param uuid_str: UUID in 36-byte hexademical string
+ :return: converted UUID
+ :rtype: cdata
+
+.. function:: frombin(uuid_bin)
+
+ :param uuid_str: UUID in 16-byte binary string
+ :return: converted UUID
+ :rtype: cdata
+
+.. class:: uuid_cdata
+
+ .. method:: bin([byte-order])
+
+ :param byte-order: |br| 'l' - little-endian,
+ |br| 'b' - big-endian,
+ |br| 'h' - endianness depends on host (default),
+ |br| 'n' - endianness depends on network
+
+ :return: UUID converted from cdata input value.
+ :rtype: 16-byte binary string
+
+ .. method:: str()
+
+ :return: UUID converted from cdata input value.
+ :rtype: 36-byte hexadecimal string
+
+ .. method:: isnil()
+
+ The all-zero UUID value can be expressed as uuid.NULL, or as
+ ``uuid.fromstr('00000000-0000-0000-0000-000000000000')``.
+ The comparison with an all-zero value can also be expressed as
+ ``uuid_with_type_cdata == uuid.NULL``.
+
+ :return: true if the value is all zero, otherwise false.
+ :rtype: bool
+
+=================================================
+ Example
+=================================================
+
+.. code-block:: lua
+
+ tarantool> uuid = require('uuid')
+ ---
+ ...
+ tarantool> uuid(), uuid.bin(), uuid.str()
+ ---
+ - 16ffedc8-cbae-4f93-a05e-349f3ab70baa
+ - !!binary FvG+Vy1MfUC6kIyeM81DYw==
+ - 67c999d2-5dce-4e58-be16-ac1bcb93160f
+ ...
+ tarantool> uu = uuid()
+ ---
+ ...
+ tarantool> #uu:bin(), #uu:str(), type(uu), uu:isnil()
+ ---
+ - 16
+ - 36
+ - cdata
+ - false
+ ...
+
+.. _Universally unique identifier: https://en.wikipedia.org/wiki/Universally_unique_identifier
+.. _syscall: https://en.wikipedia.org/wiki/Syscall
diff --git a/doc/sphinx/reference/yaml.rst b/doc/sphinx/reference/yaml.rst
new file mode 100644
index 0000000000000000000000000000000000000000..a4e2d269ed27709d4c14c0e8767b561ccc0e883b
--- /dev/null
+++ b/doc/sphinx/reference/yaml.rst
@@ -0,0 +1,60 @@
+.. include:: ../directives.rst
+.. highlight:: lua
+
+-------------------------------------------------------------------------------
+ Package `yaml`
+-------------------------------------------------------------------------------
+
+The ``yaml`` package takes strings in YAML_ format and decodes them, or takes a
+series of non-YAML values and encodes them.
+
+.. module:: yaml
+
+.. function:: encode(lua_value)
+
+ Convert a Lua object to a YAML string.
+
+ :param lua_value: either a scalar value or a Lua table value.
+ :return: the original value reformatted as a YAML string.
+ :rtype: string
+
+.. function:: decode(string)
+
+ Convert a YAML string to a Lua object.
+
+ :param string: a string formatted as YAML.
+ :return: the original contents formatted as a Lua table.
+ :rtype: table
+
+.. data:: NULL
+
+ A value comparable to Lua "nil" which may be useful as a placeholder in a tuple.
+
+=================================================
+ Example
+=================================================
+
+.. code-block:: lua
+
+ tarantool> yaml = require('yaml')
+ ---
+ ...
+ tarantool> y = yaml.encode({'a',1,'b',2})
+ ---
+ ...
+ tarantool> z = yaml.decode(y)
+ ---
+ ...
+ tarantool> z[1],z[2],z[3],z[4]
+ ---
+ - a
+ - 1
+ - b
+ - 2
+ ...
+ tarantool> if yaml.NULL == nil then print('hi') end
+ hi
+ ---
+ ...
+
+.. _YAML: http://yaml.org/
diff --git a/doc/sql.txt b/doc/sql.txt
deleted file mode 100644
index d12f229bd3da03fc597e77f9b7587f75bbb51339..0000000000000000000000000000000000000000
--- a/doc/sql.txt
+++ /dev/null
@@ -1,62 +0,0 @@
-;
-; Tarantool SQL parser is implemented entirely on the client side.
-; This BNF provides a reference of the supported subset of
-; SQL, to which all clients are strongly encouraged
-; to stick.
-;
-; Convention: UPPERCASE letters are used for terminals and literals.
-; Lowercase letters are used for <non-terminals>. SQL is
-; case-insensitive, so this convention is present only to improve
-; legibility of the BNF.
-;
-; Tarantool features not supported in SQL:
-; - multipart keys
-; - update operations, except SET
-; - all index-specific queries, such as range queries, bitset
-; expression evaluation, iteration. These are only available
-; in Lua.
-
-<sql> ::= <insert> | <replace> | <update> | <delete> | <select>
-
-<insert> ::= INSERT [INTO] <ident> VALUES <value_list>
-
-<replace> ::= REPLACE [INTO] <ident> VALUES <value_list>
-
-<update> ::= UPDATE <ident> SET <update_list> <simple_where>
-
-<delete> ::= DELETE FROM <ident> <simple_where>
-
-; It's only possible to select all fields of a tuple (* for field list)
-<select> ::= SELECT * FROM <ident> <where> <opt_limit>
-
-<simple_where> ::= WHERE <predicate>
-
-<where> ::= WHERE <disjunction>
-
-<predicate> ::= <ident> = <constant>
-
-<disjunction> ::= <predicate> [{OR <predicate>}+]
-
-; LIMIT is optional
-<opt_limit> ::= | LIMIT NUM[, NUM]
-
-<value_list> ::= (<constant> [{, <constant>}+])
-
-<update_list> ::= <ident> = <constant> [{, <ident> = <constant>}+]
-
-<constant> ::= STR | NUM
-
-<ident> ::= ID
-
-; Only integer numbers, optionally signed, are supported
-NUM ::= [+-]?[0-9]+
-
-; Strings must be single-quoted
-STR ::= '.*'
-
-; Identifiers must be standard SQL, but end with digits.
-; These digits are used to infer the namespace or index id.
-
-ID ::= [a-z_]+[0-9]+
-
-; vim: syntax=bnf
diff --git a/doc/tnt.ent.cmake b/doc/tnt.ent.cmake
deleted file mode 100644
index 4c14b3172c7a0b9c15f0270cf197329afd63269a..0000000000000000000000000000000000000000
--- a/doc/tnt.ent.cmake
+++ /dev/null
@@ -1,12 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!--
- This file contains all common entities.
- tnt.ent is built by cmake from tnt.ent.cmake.
--->
-<!ENTITY tnt_version "@PACKAGE_VERSION@">
-<!-- Include the standard ISO 8879 publishing entities -->
-<!ENTITY % isopub SYSTEM "file://@CMAKE_SOURCE_DIR@/doc/isopub.ent">
-%isopub;
-<!--
- vim: syntax=dtd
--->
diff --git a/doc/user/CMakeLists.txt b/doc/user/CMakeLists.txt
deleted file mode 100644
index 7b85402e877426ec777a6633add3a64985f88777..0000000000000000000000000000000000000000
--- a/doc/user/CMakeLists.txt
+++ /dev/null
@@ -1,104 +0,0 @@
-set(PATH_USERGUIDE_HTML "${PROJECT_BINARY_DIR}/doc/www/content/doc/user_guide.html")
-set(PATH_USERGUIDE_HTML_CHUNK "${PROJECT_BINARY_DIR}/doc/www/content/doc/user_guide/")
-set(PATH_USERGUIDE_TXT "${PROJECT_BINARY_DIR}/doc/user/tarantool_user_guide.txt")
-
-if (XMLLINT STREQUAL "XMLLINT-NOTFOUND")
- message (FATAL_ERROR "xmllint is missing")
-endif()
-
-if (XSLTPROC STREQUAL "XSLTPROC-NOTFOUND")
- message (FATAL_ERROR "xsltproc is missing")
-endif()
-
-if (JING STREQUAL "JING-NOTFOUND")
- message (FATAL_ERROR "jing is missing")
-endif()
-
-if (LYNX STREQUAL "LYNX-NOTFOUND")
- message (FATAL_ERROR "lynx is missing")
-endif()
-
-# XMLLINT is not able to validate SCHEMATRON constraints, and
-# therefore is not a good validation tool for DocBook 5. However,
-# it can validate the entire document, following xinclude
-# directives, and thus is used here. To validate individual XML
-# files, or for troubleshooting, I (Kostja) recommend using jing,
-# since its diagnostics output is significantly more readable:
-# jing http://docbook.org/xml/5.0/rng/docbookxi.rng file.xml
-#
-add_custom_target(doc-check
- COMMAND ${XMLLINT} --xinclude --noout
- --relaxng http://docbook.org/xml/5.0/rng/docbookxi.rng
- ${CMAKE_SOURCE_DIR}/doc/user/user.xml)
-
-#
-# xsltproc-based documentation generation (default)
-#
-add_custom_target(html
- COMMAND ${XSLTPROC} --nonet --xinclude
- --stringparam base.dir "${PATH_USERGUIDE_HTML_CHUNK}"
- ${CMAKE_SOURCE_DIR}/doc/user/tnt-html-chunk.xsl
- ${CMAKE_SOURCE_DIR}/doc/user/user.xml)
-
-add_custom_target(html-chunk
- COMMAND ${XSLTPROC} --nonet --xinclude
- -o ${PATH_USERGUIDE_HTML}
- ${CMAKE_SOURCE_DIR}/doc/user/tnt-html.xsl
- ${CMAKE_SOURCE_DIR}/doc/user/user.xml)
-
-add_custom_target(txt
- DEPENDS html
- COMMAND ${LYNX} -dump ${PATH_USERGUIDE_HTML} > ${PATH_USERGUIDE_TXT})
-
-add_custom_target(pdf
- COMMAND ${XSLTPROC} --nonet
- --stringparam collect.xref.targets "all"
- --xinclude -o tarantool_user_guide.fo
- ${CMAKE_SOURCE_DIR}/doc/user/tnt-fo.xsl
- ${CMAKE_SOURCE_DIR}/doc/user/user.xml
- COMMAND fop tarantool_user_guide.fo tarantool_user_guide.pdf)
-
-add_custom_target(relink
- WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
- COMMAND ${XSLTPROC} --nonet
- --stringparam collect.xref.targets "only"
- --xinclude tnt-html.xsl user.xml)
-
-#
-# Java saxon-based documentation generation (misc)
-#
-add_custom_target(html-saxon
- COMMAND java -cp "/usr/share/java/saxon.jar:/usr/share/java/xml-resolver.jar:/usr/share/java/docbook-xsl-saxon.jar:/usr/share/java/xercesImpl.jar:/etc/xml/resolver:/usr/share/java/xslthl.jar:/usr/share/java/xml-commons-resolver-1.1.jar"
- -Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl
- -Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl
- -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XIncludeParserConfiguration
- com.icl.saxon.StyleSheet
- -x org.apache.xml.resolver.tools.ResolvingXMLReader
- -y org.apache.xml.resolver.tools.ResolvingXMLReader
- -r org.apache.xml.resolver.tools.CatalogResolver
- -u -o ${PATH_USERGUIDE_HTML} user.xml tnt-html.xsl)
-
-add_custom_target(html-saxon-chunk
- COMMAND java -cp "/usr/share/java/saxon.jar:/usr/share/java/xml-resolver.jar:/usr/share/java/docbook-xsl-saxon.jar:/usr/share/java/xercesImpl.jar:/etc/xml/resolver:/usr/share/java/xslthl.jar:/usr/share/java/xml-commons-resolver-1.1.jar"
- -Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl
- -Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl
- -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XIncludeParserConfiguration
- com.icl.saxon.StyleSheet
- -x org.apache.xml.resolver.tools.ResolvingXMLReader
- -y org.apache.xml.resolver.tools.ResolvingXMLReader
- -r org.apache.xml.resolver.tools.CatalogResolver
- -u user.xml tnt-html-chunk.xsl
- base.dir="${PATH_USERGUIDE_HTML_CHUNK}")
-
-
-add_custom_target(pdf-saxon
- COMMAND java -cp "/usr/share/java/saxon.jar:/usr/share/java/xml-commons-resolver-1.1.jar:/usr/share/java/docbook-xsl-saxon.jar:/usr/share/java/xercesImpl.jar:/etc/xml/resolver:/usr/share/java/xslthl.jar"
- -Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl
- -Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl
- -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XIncludeParserConfiguration
- com.icl.saxon.StyleSheet
- -x org.apache.xml.resolver.tools.ResolvingXMLReader
- -y org.apache.xml.resolver.tools.ResolvingXMLReader
- -r org.apache.xml.resolver.tools.CatalogResolver
- -u -o tarantool_user_guide.fo user.xml tnt-fo.xsl
- COMMAND fop tarantool_user_guide.fo tarantool_user_guide.pdf)
diff --git a/doc/user/configuration-reference.xml b/doc/user/configuration-reference.xml
index f7cd99e82a78242d2306b5397cb5435b810e93c8..11ae16e312d78a994cfd9252cb02c8c0318df15c 100644
--- a/doc/user/configuration-reference.xml
+++ b/doc/user/configuration-reference.xml
@@ -58,9 +58,9 @@ Target: Linux-x86_64-Debug
indicates possible incompatible changes,
and <literal><patch></literal> stands for the number of
bug fix releases made after the start of the
- milestone. The optional commit number and
- commit SHA1 are output for non-released versions
- only, and indicate how much this particular build has diverged
+ milestone. For non-released versions only, there may be a
+ commit number and commit SHA1
+ to indicate how much this particular build has diverged
from the last release.
</member>
<member>
@@ -74,7 +74,7 @@ Target: Linux-x86_64-Debug
xlink:href="http://www.kernel.org/pub/software/scm/git/docs/git-describe.html">git describe</link> to produce its version id, and
this id can be used at any time to check out the
corresponding source from our <link
- xlink:href="git://github.com/tarantool/tarantool.git">git repository</link>.
+ xlink:href="http://github.com/tarantool/tarantool.git">git repository</link>.
</para></note>
</listitem>
@@ -98,9 +98,7 @@ is mandatory if the user name is specified,
unless the user name is 'guest'.
So, formally, the URI syntax is
<code>[host:]port</code>
-or <code>[username:password@]host:port</code>
-or if username='guest' it may be
-<code>[username@]host:port</code>.
+or <code>[username:password@]host:port</code>.
If host is omitted, then 'localhost' is assumed.
If username:password is omitted, then 'guest' is assumed.
Some examples:
@@ -112,7 +110,6 @@ Some examples:
<tbody>
<row><entry>port</entry><entry> 3301</entry></row>
<row><entry>host:port</entry><entry> 127.0.0.1:3301</entry></row>
- <row><entry>guest@host:port</entry><entry> guest@mail.ru:3301</entry></row>
<row><entry>username:password@host:port</entry><entry> guest:sesame@mail.ru:3301</entry></row>
</tbody>
</tgroup>
@@ -141,6 +138,7 @@ box.cfg{
rows_per_wal = 50
}
print('Starting ',arg[1])</programlisting>
+and suppose the environment variable LISTEN_URI contains 3301,
and suppose the command line is <code>~/tarantool/src/tarantool script.lua ARG</code>.
Then the screen might look like this:<programlisting>
<prompt>$</prompt> <userinput>export LISTEN_URI=3301</userinput>
@@ -148,7 +146,6 @@ Then the screen might look like this:<programlisting>
... main/101/script.lua C> version 1.6.3-439-g7e1011b
... main/101/script.lua C> log level 5
... main/101/script.lua I> mapping 107374184 bytes for a shared arena...
-... main/101/spawner C> initialized
... main/101/script.lua I> recovery start
... main/101/script.lua I> recovering from `./00000000000000000000.snap'
... main/101/script.lua I> primary: bound to 0.0.0.0:3301
@@ -442,7 +439,7 @@ tarantool: primary pri: 3301 adm: 3313</programlisting>
<row>
<entry>snapshot_count</entry>
- <entry>float</entry>
+ <entry>integer</entry>
<entry>6</entry>
<entry>yes</entry>
<entry>
@@ -731,7 +728,8 @@ tarantool: primary pri: 3301 adm: 3313</programlisting>
<para>
Local hot standby is a feature which provides a simple form of failover without replication.
To initiate it, start a second instance of the Tarantool server on the same computer with
- the same <code>box.cfg</code> configuration settings -- including the same directories and same URIs.
+ the same <code>box.cfg</code> configuration settings -- including the same directories and
+ same non-null URIs.
A warning should appear with a message like
"W> primary: [URI] is already in use, will retry binding after [n] seconds".
This is fine.
diff --git a/doc/user/connectors.xml b/doc/user/connectors.xml
index 8ea70b93560bb0575a4711ed3111a57ac3c37d1c..578ed4a6cbf86467dd208e38f673a99fdd64be40 100644
--- a/doc/user/connectors.xml
+++ b/doc/user/connectors.xml
@@ -13,7 +13,7 @@
<section xml:id="protocol">
<title>Protocol</title>
- <para>Tarantool protocol was designed with focus on asynchronous
+ <para>Tarantool protocol was designed with a focus on asynchronous
I/O and easy integration with proxies. Each client
request starts with a variable-length binary header, containing
request id, request type, server id, log sequence number, and
@@ -48,8 +48,6 @@ The Tarantool API exists so that a client program can send a request packet
to the server, and receive a response. Here is an example of a what the client
would send for <command>box.space[513]:insert{'A', 'BB'}</command>. The BNF description of the components
is in file <link xlink:href="http://tarantool.org/doc/box-protocol.html" xlink:title="A complete BNF of Tarantool client/server protocol">doc/box-protocol.html</link>.
- A third-party contribution written in Lua for unpacking Tarantool messages is in file
- <link xlink:href="https://github.com/negram/Tnt-dissector/blob/master/tarantool.dis.lua" xlink:title="tarantool.dis.lua">Tnt-dissector</link>.
</para>
<informaltable frame='topbot'>
@@ -114,7 +112,7 @@ and interpret the response (doc/box-protocol.html has a description
of the packet format for responses as well as requests).
But it would be easier, and less error-prone, if one could
invoke a routine that formats the packet according to typed
-parameters. Something like <code>response=tarantool_routine("insert",0,"A","B");</code>.
+parameters. Something like <code>response=tarantool_routine("insert",513,"A","B");</code>.
And that is why APIs exist for drivers for Perl, Python, PHP, and so on.
</para>
</section>
@@ -209,7 +207,7 @@ my $tnt = DR::Tarantool::MsgPack::SyncClient->connect(
0 => {
name => 'primary', fields => [ 'field1' ] } } } } );
-$tnt->insert('tester' => [ 99999, 'BB' ]);</programlisting>
+$tnt->insert('examples' => [ 99999, 'BB' ]);</programlisting>
</para>
<para>
The example program only shows one command and does not show all that's necessary for
@@ -248,7 +246,7 @@ make
<programlisting>
cd ~
cp ./tarantool-php/modules/tarantool.so .
-export PHP_INI_SCAN_DIR=~/tarantool-php/tests/shared</programlisting>
+export PHP_INI_SCAN_DIR=~/tarantool-php/test/shared</programlisting>
</para>
<para>
Here is a complete PHP program that inserts [99999,'BB'] into a space named 'examples' via the PHP API.
diff --git a/doc/user/data-and-persistence.xml b/doc/user/data-and-persistence.xml
deleted file mode 100644
index 99f05c566547bddae6480f6eb6d15198ba4f73a2..0000000000000000000000000000000000000000
--- a/doc/user/data-and-persistence.xml
+++ /dev/null
@@ -1,22 +0,0 @@
-<!DOCTYPE chapter [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xml:id="data-and-persistence">
-<title>Data model and data persistence</title>
-<blockquote><para>
- This chapter describes how Tarantool stores
- values and what operations with data it supports.
-</para></blockquote>
-
-<xi:include href="data-model.xml"/>
-<xi:include href="persistence-architecture.xml"/>
-
-</chapter>
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/data-model.xml b/doc/user/data-model.xml
deleted file mode 100644
index 1688352de019fcf63a121f329adf0a6e181b9cd5..0000000000000000000000000000000000000000
--- a/doc/user/data-model.xml
+++ /dev/null
@@ -1,344 +0,0 @@
-
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="dynamic-data-model">
-
-<title>Dynamic data model</title>
-
-<para>
-
-If you tried out the <link linkend="getting-started-start-stop"><quote>Starting Tarantool and making your first database</quote></link>
-exercise from the last chapter, then your database looks like this:
-<programlisting>
-+--------------------------------------------+
-| |
-| SPACE 'tester' |
-| +----------------------------------------+ |
-| | | |
-| | TUPLE SET 'tester' | |
-| | +-----------------------------------+ | |
-| | | Tuple: [ 1 ] | | |
-| | | Tuple: [ 2, 'Music' ] | | |
-| | | Tuple: [ 3, 'length', 93 ] | | |
-| | +-----------------------------------+ | |
-| | | |
-| | INDEX 'primary' | |
-| | +-----------------------------------+ | |
-| | | Key: 1 | | |
-| | | Key: 2 | | |
-| | | Key: 3 | | |
-| | +-----------------------------------+ | |
-| | | |
-| +----------------------------------------+ |
-+--------------------------------------------+
-</programlisting>
-</para>
-
-<bridgehead renderas="sect2">Space</bridgehead>
-
-<para>
-A <emphasis>space<alt>the paradigm of tuples and spaces is
-derived from distributed computing</alt></emphasis> -- 'tester' in the example -- is a container.
-</para>
-<para>
-When Tarantool is being used to store data, there is always at least one space.
-There can be many spaces.
-Each space has a unique name specified by the user.
-Each space has a unique numeric identifier which can be specified by the user but usually is assigned automatically by Tarantool.
-Spaces always contain one tuple set and one or more indexes.
-</para>
-
-<bridgehead renderas="sect2">Tuple Set</bridgehead>
-
-<para>
-A <emphasis>tuple set<alt>There's a Wikipedia article about tuples: https://en.wikipedia.org/wiki/Tuple</alt></emphasis> -- 'tester' in the example -- is a group of tuples.
-</para>
-<para>
-There is always one tuple set in a space.
-The identifier of a tuple set is the same as the space name -- 'tester' in the example.
-</para>
-<para>
-A tuple fills
-the same role as a <quote>row</quote> or a <quote>record</quote>, and the
-components of a tuple (which we call <quote>fields</quote>)
-fill the same role as a
-<quote>row column</quote> or <quote>record field</quote>, except that: the
-fields of a tuple don't need to have names.
-That's why there was no need to pre-define the
-tuple set when creating the space, and that's
-why each tuple can have a different number of
-elements, and that's why we say that Tarantool has
-a <quote>dynamic</quote> data model.
-Tuples are stored as <link xlink:href="http://en.wikipedia.org/wiki/MessagePack">MsgPack</link> arrays.
-</para>
-<para>
-Any given tuple may have any number of fields and the
-fields may have a variety of types.
-The identifier of a field is the field's number, base 1.
-For example <quote>1</quote> can be used in some contexts
-to refer to the first field of a tuple.
-</para>
-<para>
-When Tarantool returns a tuple value, it surrounds
-strings with single quotes, separates fields with commas,
-and encloses the tuple inside square brackets. For example:
-<computeroutput>[ 3, 'length', 93 ]</computeroutput>.
-</para>
-
-<bridgehead renderas="sect2">Index</bridgehead>
-
-<para xml:id="an-index">
-An index -- 'primary' in the example -- is a group of key values and pointers.
-</para>
-<para>
-In order for a tuple set to be useful, there must always at least one index in a space.
-There can be many.
-As with spaces, the user can and should specify the index name, and
-let Tarantool come up with a unique numeric identifier (the "index id").
-In our example there is one index and its name is <quote>primary</quote>.
-</para>
-
-<para>
-An index may be <emphasis>multi-part</emphasis>, that is, the user can declare
-that an index key value is taken from two or more fields
-in the tuple, in any order. An index may be <emphasis>unique</emphasis>, that is, the user can declare
-that it would be illegal to have the same key value twice.
-An index may have <emphasis>one of four types</emphasis>:
-HASH which is fastest and uses the least memory but must be unique,
-TREE which allows partial-key searching and ordered results,
-BITSET which can be good for searches that contain '=' and
-multiple ANDed conditions, and RTREE for spatial coordinates.
-The first index is called the <emphasis><quote>primary key</quote> index</emphasis>
-and it must be unique; all other indexes are called
-<quote>secondary</quote> indexes.
-</para>
-
-<para>
-An index definition may include identifiers of tuple fields and their expected types.
-The allowed types are NUM (64-bit unsigned integer between 0 and 18,446,744,073,709,551,615), or STR (string, any sequence of octets),
-or ARRAY (a series of numbers for use with <link linkend="RTREE">RTREE indexes</link>).
-Take our example, which has the request:
-<programlisting>i = s:create_index('primary', {type = 'hash', parts = {1, 'NUM'}})</programlisting>
-The effect is that, for all tuples in tester, field number 1
-must exist and must be a 64-bit unsigned integer.
-</para>
-
-<para>
-Space definitions and index definitions are stored permanently in <emphasis>system spaces</emphasis>.
-It is possible to add, drop, or alter the definitions at runtime, with some restrictions.
-The syntax details for defining spaces and indexes are in section
-<link linkend="sp-box-library">The box library</link>.
-</para>
-
-<bridgehead renderas="sect2">Data types</bridgehead>
-
- <para>
- Tarantool can work with numbers, strings, booleans, tables, and userdata.
- </para>
-
- <para>
- <informaltable>
- <tgroup cols="4" align="left" colsep="1" rowsep="1">
- <thead>
- <row><entry>General type</entry> <entry>Specific type</entry><entry>What Lua type() would return</entry> <entry>Example</entry></row>
- </thead>
- <tbody>
- <row><entry xml:id="function-type-number">scalar </entry><entry>number</entry> <entry><link xlink:href="http://www.lua.org/pil/2.3.html">"number"</link></entry> <entry>12345</entry></row>
- <row><entry xml:id="function-type-string">scalar </entry><entry>string</entry> <entry><link xlink:href="http://www.lua.org/pil/2.4.html">"string"</link></entry> <entry>'A B C'</entry></row>
- <row><entry xml:id="function-type-boolean">scalar </entry><entry>boolean</entry> <entry><link xlink:href="http://www.lua.org/pil/2.2.html">"boolean"</link></entry> <entry>true</entry></row>
- <row><entry xml:id="function-type-nil">scalar </entry><entry>nil</entry> <entry><link xlink:href="http://www.lua.org/pil/2.1.html">"nil"</link></entry> <entry>nil</entry></row>
- <row><entry xml:id="function-type-lua-table">compound</entry><entry>Lua table</entry> <entry><link xlink:href="http://www.lua.org/pil/2.5.html">"table"</link></entry> <entry>table: 0x410f8b10</entry></row>
- <row><entry xml:id="function-type-tuple">compound </entry><entry>tuple</entry> <entry><link xlink:href="http://www.lua.org/pil/28.1.html">"Userdata"</link></entry><entry>12345: {'A B C'}</entry></row>
- </tbody>
- </tgroup>
- </informaltable>
- In Lua a "number" is double-precision floating-point;
- however, for database storage Tarantool uses MsgPack rules,
- and MsgPack allows for both integer and floating-point values.
- So Tarantool will store a number as a float if the value contains a decimal point, and otherwise will store as an integer.
- Tarantool can store signed numbers, but not in indexed fields -- when a field has a 'NUM' index, the values must be unsigned 64-bit integers.
- Large numbers can be entered with exponential notation, for example 9e99.
- Large integers greater than 100,000,000,000,000 (1e14) should be entered with the <link linkend="tonumber64">tonumber64</link> function.
- Storage is variable-length, so the smallest number requires only one byte but the largest number requires nine bytes.
- </para>
- <para>
- A "string" is a variable-length sequence of bytes, usually represented with alphanumeric
- characters inside single quotes.
- </para>
- <para>
- A "boolean" is either <code>true</code> or <code>false</code>.
- </para>
- <para>
- A "nil" type has only one possible value, also called "nil", but often displayed
- as "null". Nils may be compared to values of any types with == (is-equal) or ~=
- (is-not-equal), but other operations will not work. Nils may not be used in Lua tables;
- the workaround is to use
- <link linkend="yaml-null"><code>yaml.NULL</code></link>
- or <link linkend="json-null"><code>json.NULL</code></link>
- or <link linkend="msgpack-null"><code>msgpack.NULL</code></link>.
- </para>
- <para>
- A tuple is returned in YAML format like <code>- [120, 'a', 'b', 'c']</code>.
- A few functions may return tables with multiple tuples.
- A scalar may be converted to a tuple with only one field.
- A Lua table may contain all of a tuple's fields, but not nil.
- For more tuple examples see <code xlink:href="#box.tuple">box.tuple</code>.
- </para>
-
-
-<bridgehead renderas="sect2">Operations</bridgehead>
-
-<para>
-The basic operations are: the four data-change operations
-(insert, update, delete, replace), and the data-retrieval
-operation (select). There are also minor operations like <quote>ping</quote>
-which can only be used with the binary protocol.
-Also, there are <olink
-targetptr="box.index.iterator">index iterator</olink> operations,
-which can only be used with Lua code.
-(Index iterators are for traversing indexes one key at a time,
-taking advantage of features that are specific
-to an index type, for example evaluating Boolean expressions
-when traversing BITSET indexes, or going in descending order
-when traversing TREE indexes.)
-</para>
-
-<para>
-Five examples of basic operations:
-<programlisting>
--- Add a new tuple to tuple set tester.
--- The first field, field[1], will be 999 (type is NUM).
--- The second field, field[2], will be 'Taranto' (type is STR).
-box.space.tester:insert{999, 'Taranto'}
-
--- Update the tuple, changing field field[2].
--- The clause "{999}", which has the value to look up in
--- the index of the tuple's primary-key field, is mandatory
--- because update() requests must always have a clause that
--- specifies the primary key, which in this case is field[1].
--- The clause "{{'=', 2, 'Tarantino'}}" specifies that assignment
--- will happen to field[2] with the new value.
-box.space.tester:update({999}, {{'=', 2, 'Tarantino'}})
-
--- Replace the tuple, adding a new field.
--- This is also possible with the update() request but
--- the update() request is usually more complicated.
-box.space.tester:replace{999, 'Tarantella', 'Tarantula'}
-
--- Retrieve the tuple.
--- The clause "{999}" is still mandatory, although it does not have to
--- mention the primary key. */
-box.space.tester:select{999}
-
--- Delete the tuple.
--- Once again the clause to identify the primary-key field is mandatory.
-box.space.tester:delete{999}
-</programlisting>
-</para>
-
-<para>
-How does Tarantool do a basic operation? Let's take this example:
-<programlisting>
-box.space.tester:update({3}, {{'=', 2, 'size'}, {'=', 3, 0}})
-</programlisting>
-which, for those who know SQL, is equivalent to a statement like
-UPDATE tester SET "field[2]" = 'size', "field[3]" = 0 WHERE "field[[1]" = 3
-</para>
-
-<para>
-STEP #1: if this is happening on a remote client, then
-the client parses the statement and changes it to a
-binary-protocol instruction which has already been checked,
-and which the server can understand without needing to parse
-everything again. The client ships a packet to the server.
-</para>
-<para>
-STEP #2: the server's <quote>transaction processor</quote> thread uses the
-primary-key index on field[1] to find the location of the
-tuple in memory. It determines that the tuple can be updated
-(not much can go wrong when you're merely changing an unindexed
-field value to something shorter).
-</para>
-<para>
-STEP #3: the transaction processor thread sends a message to
-the <emphasis>write-ahead logging<alt>There's a Wikipedia article about write-ahead logging: https://en.wikipedia.org/wiki/Write-ahead_logging</alt></emphasis> (WAL) thread.
-</para>
-<para>
-At this point a <quote>yield</quote> takes place. To know
-the significance of that -- and it's quite significant -- you
-have to know a few facts and a few new words.
-</para>
-<para>
-FACT #1: there is only one transaction processor thread.
-Some people are used to the idea that there can be multiple
-threads operating on the database, with (say) thread #1
-reading row #x while thread#2 writes row#y. With Tarantool
-no such thing ever happens. Only the transaction processor
-thread can access the database, and there is only one
-transaction processor thread for each instance of the server.
-</para>
-<para>
-FACT #2: the transaction processor thread can handle many
-<emphasis>fibers<alt>There's a Wikipedia article about fibers: https://en.wikipedia.org/wiki/Fiber_%28computer_science%29</alt></emphasis>.
-A fiber is a set of computer instructions that may contain <quote>yield</quote> signals.
-The transaction processor thread will execute all computer instructions
-until a yield, then switch to execute the instructions of a different fiber.
-Thus (say) the thread reads row#x for the sake of fiber#1,
-then writes row#y for the sake of fiber#2.
-</para>
-<para>
-FACT #3: yields must happen, otherwise the transaction processor thread
-would stick permanently on the same fiber. There are implicit yields:
-every data-change operation or network-access causes an implicit yield,
-and every statement that goes through the tarantool client causes an
-implicit yield. And there are explicit yields: in a Lua function
-one can and should add <quote>yield</quote> statements to prevent hogging.
-This is called <emphasis>cooperative multitasking<alt>There's a Wikipedia
-article with a section about cooperative multitasking:
-https://en.wikipedia.org/wiki/Cooperative_multitasking#Cooperative_multitasking.2Ftime-sharing</alt></emphasis>.
-</para>
-<para>
-Since all data-change operations end with an implicit yield and
-an implicit commit, and since no data-change operation can change
-more than one tuple, there is no need for any locking.
-Consider, for example, a Lua function that does three Tarantool operations:<programlisting>
-s:select{999} -- this does not yield and does not commit
-s:update({...},{{...}}) -- this yields and commits
-s:select{999} -- this does not yield and does not commit */</programlisting>
-The combination <quote>SELECT plus UPDATE</quote> is an atomic transaction:
-the function holds a consistent view of the database
-until the UPDATE ends. For the combination <quote>UPDATE plus SELECT</quote>
-the view is not consistent, because after the UPDATE the transaction processor
-thread can switch to another fiber, and delete the tuple that
-was just updated.
-</para>
-<para>
-Since locks don't exist, and disk writes only involve the write-ahead log,
-transactions are usually fast. Also the Tarantool server may not be
-using up all the threads of a powerful multi-core processor,
-so advanced users may be able to start a second Tarantool
-server on the same processor without ill effects.
-</para>
-<para>
- Additional examples of requests can be found in the <citetitle
- xlink:href="https://github.com/tarantool/tarantool/tree/master/test/box"
- xlink:title="Tarantool regression test suite">Tarantool
- regression test suite</citetitle>. A complete grammar of
- supported data-manipulation functions will come later in this chapter.
-</para>
-<para>
- Since not all Tarantool operations can be expressed with the
- data-manipulation functions, or with Lua, to gain
- complete access to data manipulation functionality one must use
- a <olink targetptr="connectors">Perl, PHP, Python or other
- programming language connector</olink>. The client/server
- protocol is open and documented: an annotated BNF can be found
- in the source tree, file <filename
- xlink:href="http://tarantool.org/doc/box-protocol.html" xlink:title="A complete BNF of Tarantool client/server protocol">doc/box-protocol.html</filename>.
-</para>
-
-</section>
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/databases.xml b/doc/user/databases.xml
deleted file mode 100644
index c6194262fb18d26978bb7eba7eede810a2ea28ef..0000000000000000000000000000000000000000
--- a/doc/user/databases.xml
+++ /dev/null
@@ -1,3510 +0,0 @@
-<!DOCTYPE chapter [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xml:id="databases">
-<title>Databases</title>
-<blockquote><para>
- This chapter describes how Tarantool stores
- values and what operations with data it supports.
-</para></blockquote>
-
-<xi:include href="data-model.xml"/>
-<xi:include href="persistence-architecture.xml"/>
-
-<section xml:id="data-manipulation">
- <title>Data manipulation</title>
-
- <para>
- The basic "data-manipulation" requests are:
- <code>insert</code>, <code>replace</code>,
- <code>update</code>, <code>delete</code>, <code>select</code>.
- They all are part of the <code>box</code> library.
- They all may return data.
- Usually both inputs and outputs may be Lua tables.
- </para>
- <para>
- The Lua syntax for data-manipulation functions can vary.
- Here are examples of the variations with <code>select</code> examples;
- the same rules exist for the other data-manipulation functions.
- Every one of the examples does the same thing: select a tuple set
- from a space named tester where the primary-key field value equals 1.
- </para>
- <para>
- First there are "naming variations":
- <orderedlist xml:id="name-syntaxes" xreflabel="name-syntaxes">
- <listitem><para><code>box.space.tester:select{1}</code></para></listitem>
- <listitem><para><code>box.space['tester']:select{1}</code></para></listitem>
- <listitem><para><code>box.space[512]:select{1}</code></para></listitem>
- <listitem><para><code>variable = 'tester'; box.space[variable]:select{1}</code></para></listitem>
- </orderedlist>
- ... There is an assumption that
- the numeric id of 'tester' is 512, which happens to be the
- case in our sandbox example only. Literal values such as
- 'tester' may be replaced by variable names.
- Examples and descriptions in this manual have the "box.space.space.tester:" form;
- however, this is a matter of user preference and
- all the variants exist in the wild.
- </para>
- <para>
- Then there are "parameter variations":
- <orderedlist xml:id="parameter-syntaxes" xreflabel="parameter-syntaxes">
- <listitem><para><code>box.space.tester:select{1}</code></para></listitem>
- <listitem><para><code>box.space.tester:select({1})</code></para></listitem>
- <listitem><para><code>box.space.tester:select(1)</code></para></listitem>
- <listitem><para><code>box.space.tester:select({1},{iterator='EQ'})</code></para></listitem>
- <listitem><para><code>variable = 1; box.space.tester:select{variable}</code></para></listitem>
- <listitem><para><code>variable = {1}; box.space.tester:select(variable)</code></para></listitem>
- </orderedlist>
- ... The primary-key value is enclosed in braces, and if it was a
- multi-part primary key then the value would be multi-part,
- for example "...select{1,2,3}". The braces can be enclosed
- inside parentheses -- "...select({...}) -- which is
- optional unless it is necessary to pass something besides
- the primary-key value, as in the fourth example.
- Literal values such as 1 (a scalar value) or {1}
- (a Lua table value) may be replaced by variable names,
- as in examples [5] and [6].
- Although there are special cases where braces can be omitted,
- they are preferable because they signal "Lua table".
- Examples and descriptions in this manual have the "{1}" form; however, this
- too is a matter of user preference and all the variants
- exist in the wild.
- </para>
-
- <para>
- All the data-manipulation functions operate on tuple sets but,
- since primary keys are unique, the number of tuples in the tuple set is always 1.
- The only exception is <code>box.space...select</code>, which may accept either a
- primary-key value or a secondary-key value.
- </para>
-
-</section>
-
-<section xml:id="sp-box-library">
- <title>The <code>box</code> library</title>
-
- <para>
- As well as executing Lua chunks or defining their own functions,
- users can exploit the Tarantool server's storage functionality
- with the <code>box</code> Lua library.
- </para>
-
- <para>
- <bridgehead renderas="sect4">Packages of the box library</bridgehead>
-
- The contents of the <code>box</code> library can be inspected at runtime with
- <code>box</code>, with no arguments.
- The packages inside the box library are: box.schema, box.tuple, box.space, box.index,
- net.box, box.cfg, box.info, box.slab, box.stat.
- Every package contains one or more Lua functions. A few packages contain members as well as functions.
- The functions allow data definition (create alter drop), data manipulation (insert delete update select replace),
- and introspection (inspecting contents of spaces, accessing server configuration).
- </para>
-
- <para>
- <table>
- <title xml:id="complexity-factors">Complexity Factors that may affect data manipulation functions in the box library</title>
- <tgroup cols="2" align="left" colsep="1" rowsep="1">
- <thead>
- <row><entry>Factor</entry><entry>Explanation</entry></row>
- </thead>
- <tbody>
- <row><entry>Index size</entry> <entry>The number of index keys is the same as the number
- of tuples in the data set. For a TREE index, if
- there are more keys then the lookup time will be
- greater, although of course the effect is not linear.
- For a HASH index, if there are more keys then there
- is more RAM use, but the number of low-level steps
- tends to remain constant.</entry></row>
- <row><entry>Index type</entry> <entry>Typically a HASH index is faster than a TREE index
- if the number of tuples in the tuple set is greater than one.</entry></row>
- <row><entry>Number of indexes accessed</entry><entry>Ordinarily only one index is accessed to retrieve
- one tuple. But to update the tuple, there must be
- N accesses if the tuple set has N different indexes.</entry></row>
- <row><entry>Number of tuples accessed</entry><entry>A few requests, for example select, can retrieve
- multiple tuples. This factor is usually less
- important than the others.</entry></row>
- <row><entry>WAL settings</entry> <entry>The important setting for the write-ahead log is
- <olink targetptr="wal_mode"/>.
- If the setting causes no writing or delayed writing,
- this factor is unimportant. If the settings causes
- every data-change request to wait for writing to
- finish on a slow device, this factor is more
- important than all the others.</entry></row>
- </tbody>
- </tgroup>
- </table>
- In the discussion of each data-manipulation function there will be a note
- about which Complexity Factors might affect the function's resource usage.
- </para>
-
- <para>
- <bridgehead renderas="sect4">The two storage engines: memtx and sophia</bridgehead>
- A storage engine is a set of very-low-level routines which actually store and retrieve tuple values.
- Tarantool offers a choice of two storage engines: memtx (the in-memory storage engine)
- and sophia (the on-disk storage engine). To specify that the engine should be sophia,
- add a clause: <code>engine = 'sophia'</code>. The manual concentrates on memtx because it is
- the default and has been around longer. But sophia is a working key-value engine and will especially
- appeal to users who like to see data go directly to disk, so that recovery time might be
- shorter and database size might be larger.
- For architectural explanations and benchmarks, see <link xlink:href="http://sphia.org">sphia.org</link>.
- On the other hand, sophia lacks some functions and options that are available with memtx.
- Where that is the case, the relevant description will contain the words
- "only applicable for the memtx storage engine".
- </para>
-
-</section>
-
-<section xml:id="sp-box-schema">
- <title>Package <code>box.schema</code></title>
-<variablelist xml:id="box.schema" xreflabel="box.schema">
- <para>
- The <code>box.schema</code> package has one data-definition
- function: space.create().
- </para>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="box.space.create">
- box.schema.space.create(<replaceable>space-name</replaceable> [, {<replaceable>options</replaceable>} ])
- </emphasis>
- </term>
- <listitem>
- <para>
- Create a space.
- </para>
- <para>
- Parameters: <code>space-name</code>, which should not be a number and should not contain special characters;
- <code>options</code>.
- </para>
- <para>
- <table>
- <title>Options for box.schema.space.create</title>
- <tgroup cols="4" align="left" colsep="1" rowsep="1">
- <tbody>
- <row>
- <entry>NAME</entry><entry>EFFECT</entry><entry>TYPE</entry><entry>DEFAULT</entry>
- </row>
- <row>
- <entry>temporary</entry><entry>space is temporary</entry><entry>true|false</entry><entry>false</entry>
- </row>
- <row>
- <entry>id</entry><entry>unique identifier</entry><entry>number</entry><entry>last space's id, +1</entry>
- </row>
- <row>
- <entry>field_count</entry><entry>fixed field count</entry><entry>number</entry><entry>0 i.e. not fixed</entry>
- </row>
- <row>
- <entry>if_not_exists</entry><entry>no error if duplicate name</entry><entry>true|false</entry><entry>false</entry>
- </row>
- <row>
- <entry>engine</entry><entry>storage package</entry><entry>string</entry><entry>'memtx'</entry>
- </row>
- <row>
- <entry>user</entry><entry>user name</entry><entry>string</entry><entry>current user's name</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- <para>
- Returns: (type = tuple) the new space descriptor.
- </para>
- <para>
- Possible errors: If a space with the same name already exists.
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-tarantool> <userinput>s = box.schema.space.create('space55')</userinput>
----
-...
-tarantool> <userinput>s = box.schema.space.create('space55', {id = 555, temporary = false})</userinput>
----
-- error: Space 'space55' already exists
-...
-tarantool> <userinput>s = box.schema.space.create('space55', {if_not_exists = true})</userinput>
----
-...
-</programlisting>
- After a space is created, usually the next step is to
- <link linkend="box.create_index">create an index</link> for it, and
- then it is available for insert, select, and all the other
- <link linkend="box.space">box.space</link> functions.
- </para>
- </listitem>
- </varlistentry>
-
-
-</variablelist>
-
-</section>
-
-<section xml:id="sp-box-space">
- <title>Package <code>box.space</code></title>
-<variablelist xml:id="box.space" xreflabel="box.space">
- <para>
- The <code>box.space</code> package has the data-manipulation
- functions <code>select</code>, <code>insert</code>, <code>replace</code>, <code>update</code>,
- <code>delete</code>, <code>get</code>, <code>put</code>.
- It also has members, such as id, and whether or not a space is
- enabled.
- Package source code is available in file <filename
- xlink:href="https://github.com/tarantool/tarantool/blob/master/src/box/lua/box.lua">src/box/lua/box.lua</filename>.
- </para>
-
- <para>
- A list of all box.space functions follows, then comes a list of all <code>box.space</code> members.
- </para>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="box.create_index">
- box.space.<replaceable>space-name</replaceable>:create_index(<replaceable>index-name</replaceable> [, {<replaceable>options</replaceable>} ])
- </emphasis>
- </term>
- <listitem>
- <para>
- Create an index. It is mandatory to create an index for a tuple set before trying to
- insert tuples into it, or select tuples from it. The first created index, which will
- be used as the primary-key index, must be unique.
- </para>
- <para>
- Parameters: <code>index-name</code>, which should not be a number and should not contain special characters;
- <code>options</code>.
- </para>
- <para>
- <table>
- <title>Options for box.space...create_index</title>
- <tgroup cols="4" align="left" colsep="1" rowsep="1">
- <tbody>
- <row>
- <entry>NAME</entry><entry>EFFECT</entry><entry>TYPE</entry><entry>DEFAULT</entry>
- </row>
- <row>
- <entry>type</entry><entry>type of index</entry><entry>'HASH'|'TREE'|'BITSET'|'RTREE'</entry><entry>'TREE'</entry>
- </row>
- <row>
- <entry>id</entry><entry>unique identifier</entry><entry>number</entry><entry>last index's id, +1</entry>
- </row>
- <row>
- <entry>unique</entry><entry>index is unique</entry><entry>true|false</entry><entry>true</entry>
- </row>
- <row>
- <entry>parts</entry><entry>field-numbers + types</entry><entry>{field_no, 'NUM'|STR'}</entry><entry>{1, 'NUM'}</entry>
- </row>
- <row>
- <entry>if_not_exists</entry><entry>no error if duplicate name</entry><entry>true|false</entry><entry>false</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- <para>
- Returns: nil.
- </para>
- <para>
- Possible errors: too many parts.
- A type options other than TREE, or a unique option other than unique, or a parts option with more than one field component,
- is only applicable for the memtx storage engine.
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-tarantool> <userinput>s = box.space.space55</userinput>
----
-...
-tarantool> <userinput>s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})</userinput>
----
-...
-
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="box.insert">
- box.space.<replaceable>space-name</replaceable>:insert{<replaceable>field-value [, field-value ...]</replaceable>}
- </emphasis>
- </term>
- <listitem>
- <para>
- Insert a tuple into a space.
- </para>
- <para>
- Parameters: <code>space-name</code>, <code> field-value(s)</code> = fields of the new tuple.
- </para>
- <para>
- Returns: (type = tuple) the inserted tuple.
- </para>
- <para>
- Possible errors: If a tuple with the same unique-key value already exists, returns ER_TUPLE_FOUND.
- </para>
- <para>
- Example: <code><userinput>box.space.tester:insert{5000,'tuple number five thousand'}</userinput></code>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="box.select" xreflabel="box.select">
- box.space.<replaceable>space-name</replaceable>:select{<replaceable>field-value [, field-value ...]</replaceable>}
- </emphasis>
- </term>
- <listitem>
- <para>
- Search for a tuple or a set of tuples in the given space.
- </para>
- <para>
- Parameters: (type = tuple, as a Lua table) <code>field-value(s)</code>—
- = values to be matched against the index key, which may be multi-part.
- </para>
- <para>
- Returns: (type = tuple set, as a Lua table) the tuples whose primary-key fields
- are equal to the passed field-values. If the number of passed field-values is
- less than the number of fields in the primary key, then only the passed field-values are
- compared, so <code>select{1,2}</code> will match a tuple whose primary key is {1,2,3}.
- </para>
- <para>
- Complexity Factors: Index size, Index type.
- </para>
- <para>
- Possible Errors: No such space; wrong type.
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-tarantool> <userinput>s = box.schema.space.create('tmp', {temporary=true})</userinput>
----
-...
-tarantool> <userinput> s:create_index('primary',{parts = {1,'NUM', 2, 'STR'}})</userinput>
----
-...
-tarantool> <userinput> s:insert{1,'A'}</userinput>
----
-- [1, 'A']
-...
-tarantool> <userinput> s:insert{1,'B'}</userinput>
----
-- [1, 'B']
-...
-tarantool> <userinput> s:insert{1,'C'}</userinput>
----
-- [1, 'C']
-...
-tarantool> <userinput> s:insert{2,'D'}</userinput>
----
-- [2, 'D']
-...
-tarantool> <userinput> s:select{1,'B'} -- must equal both primary-key fields</userinput>
----
-- - [1, 'B']
-...
-
-tarantool> <userinput> s:select{1} -- must equal only one primary-key field</userinput>
----
-- - [1, 'A']
- - [1, 'B']
- - [1, 'C']
-...
-tarantool> <userinput> s:select{} -- must equal 0 fields, so returns all tuples</userinput>
----
-- - [1, 'A']
- - [1, 'B']
- - [1, 'C']
- - [2, 'D']
-...</programlisting>
- For examples of complex <code>select</code>s, where one can specify which
- index to search and what condition to use (for example "greater than"
- instead of "equal to") and how many tuples to return, see the later section
- <link linkend="box.index.iterator.select">box.space.space-name[.index.index-name]:select</link>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="box.get" xreflabel="box.get">
- box.space.<replaceable>space-name</replaceable>:get{<replaceable>field-value [, field-value ...]</replaceable>}
- </emphasis>
- </term>
- <listitem>
- <para>
- Search for a tuple in the given space.
- </para>
- <para>
- Parameters: (type = tuple, as a Lua table) <code>field-value(s)</code>—
- = values to be matched against the index key, which may be multi-part.
- </para>
- <para>
- Returns: (type = tuple) the selected tuple.
- </para>
- <para>
- Complexity Factors: Index size, Index type.
- </para>
- <para>
- Possible Errors: No such space; wrong type.
- </para>
- <para>
- The <code>box.space...select</code> function returns a set of tuples as a Lua
- table; the <code>box.space...get</code> function returns a single tuple.
- And it is possible to get the first tuple in a tuple set by appending "[1]".
- Therefore <code>box.space.tester:get{1}</code> has the same effect as
- <code>box.space.tester:select{1}[1]</code>, and may serve as a convenient
- shorthand.
- </para>
- <para>
- Example: <code><userinput>box.space.tester:get{1}</userinput></code>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="box.drop">
- box.space.<replaceable>space-name</replaceable>:drop()
- </emphasis>
- </term>
- <listitem>
- <para>
- Drop a space.
- </para>
- <para>
- Parameters: none.
- </para>
- <para>
- Returns: nil.
- </para>
- <para>
- Complexity Factors: Index size, Index type, Number of indexes accessed, WAL settings.
- </para>
- <para>
- Possible errors: If space-name does not exist.
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-tarantool> <userinput>box.space.space_that_does_not_exist:drop()</userinput>
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="box.rename">
- box.space.<replaceable>space-name</replaceable>:rename(<replaceable>space-name</replaceable>)
- </emphasis>
- </term>
- <listitem>
- <para>
- Rename a space.
- </para>
- <para>
- Parameters: new name for space.
- </para>
- <para>
- Returns: nil.
- </para>
- <para>
- Possible errors: If space-name does not exist.
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-tarantool> <userinput>box.space.space55:rename('space56')</userinput>
----
-...
-tarantool> <userinput>box.space.space56:rename('space55')</userinput>
----
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="box.space.alter">
- box.space.<replaceable>space-name</replaceable>.index.<replaceable>index-name</replaceable>:alter({<replaceable>options</replaceable>})
- </emphasis>
- </term>
- <listitem>
- <para>
- Alter an index.
- </para>
- <para>
- Parameters: <code>options</code> -- see the options list for create_index().
- </para>
- <para>
- Returns: nil.
- </para>
- <para>
- Possible errors: The first index cannot be changed to {unique = false}.
- The <code>alter</code> function is only applicable for the memtx storage engine.
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-tarantool> <userinput>box.space.space55.index.primary:alter({type = 'HASH'})</userinput>
----
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="box.space.drop">
- box.space.<replaceable>space-name</replaceable>.index.<replaceable>index-name</replaceable>:drop()
- </emphasis>
- </term>
- <listitem>
- <para>
- Drop an index. Dropping a primary-key index has a side effect: all tuples are deleted.
- </para>
- <para>
- Parameters: none.
- </para>
- <para>
- Returns: nil.
- </para>
- <para>
- Possible errors: If index-name doesn't exist.
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-tarantool> <userinput>box.space.space55.index.primary:drop()</userinput>
----
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="box.space.rename">
- box.space.<replaceable>space-name</replaceable>.index.<replaceable>index-name</replaceable>:rename(<replaceable>index-name</replaceable>)
- </emphasis>
- </term>
- <listitem>
- <para>
- Rename an index.
- </para>
- <para>
- Parameters: new name for index.
- </para>
- <para>
- Returns: nil.
- </para>
- <para>
- Possible errors: If index-name doesn't exist.
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-tarantool> <userinput>box.space.space55.index.primary:rename('secondary')</userinput>
----
-...
-</programlisting>
- </para>
- <para>
- Complexity Factors: Index size, Index type, Number of tuples accessed.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="box.replace">
- box.space.<replaceable>space-name</replaceable>:replace{<replaceable>field-value [, field-value ...]</replaceable>}
- </emphasis>
- or
- <emphasis role="lua" xml:id="box.put">
- box.space.<replaceable>space-name</replaceable>:put{<replaceable>field-value [, field-value ...]</replaceable>}
- </emphasis>
- </term>
- <listitem>
- <para>
- Insert a tuple into a space. If a tuple with
- the same primary key already exists,
- <code>box.space...:replace()</code> replaces the existing
- tuple with a new one. The syntax variants <code>box.space...:replace()</code>
- and <code>box.space...:put()</code> have the same effect; the latter is sometimes
- used to show that the effect is the converse of <code>box.space...:get()</code>.
- </para>
- <para>
- Parameters: <code>space-name</code>, <code> field-value(s)</code> = fields of the new tuple.
- </para>
- <para>
- Returns: (type = tuple) the inserted tuple.
- </para>
- <para>
- Possible errors: If a different tuple with the same unique-key value already exists, returns ER_TUPLE_FOUND.
- (This would only happen if there was a secondary index. By default secondary indexes are unique.)
- </para>
- <para>
- Complexity Factors: Index size, Index type, Number of indexes accessed, WAL settings.
- </para>
- <para>
- Example: <code><userinput>box.space.tester:replace{5000,'New value'}</userinput></code>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="box.update">
- box.space.<replaceable>space-name</replaceable>:update({<replaceable>key {, operator, field_no, value}...</replaceable>})
- </emphasis>
- </term>
- <listitem>
- <para>
- Update a tuple.
- </para>
- <para>
- The <code>update</code> function supports operations on fields —
- assignment, arithmetic (if the field is unsigned numeric),
- cutting and pasting fragments of a field,
- deleting or inserting a field. Multiple
- operations can be combined in a single update request, and in this
- case they are performed atomically and sequentially. Each operation requires
- specification of a field number. When multiple operations
- are present, the field number for each operation is assumed to
- be relative to the most recent state of the tuple, that is, as if
- all previous operations in a multi-operation update have
- already been applied. In other words, it is always safe to
- merge multiple <code>update</code> invocations into a single invocation, with no
- change in semantics.
- </para>
- <para>
- Parameters: <code>space-name</code>,
- <code>key</code> = primary-key field values, must be passed as a Lua table if key is multi-part,
- <code>{operator, field_no, value}</code> = a group of arguments
- for each operation, indicating what the operation is, what field
- the operation will apply to, and what value will be applied.
- For some operations the field number can be -1, meaning
- the last field in the tuple.
- Possible operators are: <quote>+</quote>
- for addition, <quote>-</quote> for subtraction,
- <quote>&</quote> for bitwise AND,
- <quote>|</quote> for bitwise OR, <quote>^</quote>
- for bitwise exclusive OR (XOR), <quote>:</quote>
- for string splice, <quote>!</quote> for insert,
- <quote>#</quote> for delete.
- Thus in the instruction <code>s:update(44, {{'+',1,55},{'=',3,'x'}})</code>
- the primary-key value is 44,
- the operators are '+' and '='
- meaning "add a value to a field
- and then assign a value to a field", the first affected field
- is field 1 and the value which will be added to it is 55, the second affected field
- is field 3 and the value which will be assigned to it is 'x'.
- </para>
- <para>
- Returns: (type = tuple) the updated tuple.
- </para>
- <para>
- Possible errors: it is illegal to modify a primary-key field.
- </para>
- <para>
- Complexity Factors: Index size, Index type, number of indexes accessed, WAL settings.
- </para>
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-#Assume that the initial state of the database is ...
-# tester has one tuple set and one primary key whose type is 'NUM'.
-# There is one tuple, with field[1] = 999 and field[2] = 'A'.
-
-#In the following update ...
-# The first argument is tester, that is, the affected space is tester
-# The second argument is 999, that is, the affected tuple is identified by
-# primary key value = 999
-# The third argument is '=', that is, there is one operation, assignment
-# to a field
-# The fourth argument is 2, that is, the affected field is field[2]
-# The fifth argument is 'B', that is, field[2] contents change to 'B'
-# Therefore, after the following update, field[1] = 999 and field[2] = 'B'.
-box.space.tester:update(999, {{'=', 2, 'B'}})
-
-#In the following update, the arguments are the same, except that ...
-# the key is passed as a Lua table (inside braces). This is unnecessary
-# when the primary key has only one field, but would be necessary if the
-# primary key had more than one field.
-# Therefore, after the following update, field[1] = 999 and field[2] = 'B'
-# (no change).
-box.space.tester:update({999}, {{'=', 2, 'B'}})
-
-#In the following update, the arguments are the same, except that ...
-# The fourth argument is 3, that is, the affected field is field[3].
-# It is okay that, until now, field[3] has not existed. It gets added.
-# Therefore, after the following update, field[1] = 999, field[2] = 'B',
-# field[3] = 1.
-box.space.tester:update({999}, {{'=', 3, 1}})
-
-#In the following update, the arguments are the same, except that ...
-# The third argument is '+', that is, the operation is addition rather
-# than assignment.
-# Since field[3] previously contained 1, this means we're adding 1 to 1.
-# Therefore, after the following update, field[1] = 999, field[2] = 'B',
-# field[3] = 2.
-box.space.tester:update({999}, {{'+', 3, 1}})
-
-#In the following update ...
-# The idea is to modify two fields at once.
-# The formats are '|' and '=', that is, there are two operations, OR and
-# assignment.
-# The fourth and fifth arguments mean that field[3] gets ORed with 1.
-# The seventh and eighth arguments mean that field[2] gets assigned 'C'.
-# Therefore, after the following update, field[1] = 999, field[2] = 'C',
-# field[3] = 3.
-box.space.tester:update({999}, {{'|', 3, 1}, {'=', 2, 'C'}})
-
-#In the following update ...
-# The idea is to delete field[2], then subtract 3 from field[3], but ...
-# after the delete, there is a renumbering -- so field[3] becomes field[2]
-# before we subtract 3 from it, and that's why the seventh argument is 2 not 3.
-# Therefore, after the following update, field[1] = 999, field[2] = 0.
-box.space.tester:update({999}, {{'#', 2, 1}, {'-', 2, 3}})
-
-#In the following update ...
-# We're making a long string so that splice will work in the next example.
-# Therefore, after the following update, field[1] = 999, field[2] = 'XYZ'.
-box.space.tester:update({999}, {{'=', 2, 'XYZ'}})
-
-#In the following update ...
-# The third argument is ':', that is, this is the example of splice.
-# The fourth argument is 2 because the change will occur in field[2].
-# The fifth argument is 2 because deletion will begin with the second byte.
-# The sixth argument is 1 because the number of bytes to delete is 1.
-# The seventh argument is '!!' because '!!' is to be added at this position.
-# Therefore, after the following update, field[1] = 999, field[2] = 'X!!Z'.
-box.space.tester:update({999}, {{':', 2, 2, 1, '!!'}})
-
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="box.delete">
- box.space.<replaceable>space-name</replaceable>:delete{<replaceable>field-value [, field-value ...]</replaceable>}
- </emphasis>
- </term>
- <listitem>
- <para>
- Delete a tuple identified by a primary key.
- </para>
- <para>
- Parameters: <code>space-name</code>, <code>field-value(s)</code> = values to match against keys in the primary index.
- </para>
- <para>
- Returns: (type = tuple) the deleted tuple.
- </para>
- <para>
- Complexity Factors: Index size, Index type
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-tarantool> <userinput>box.space.tester:delete(0)</userinput>
----
-- [0, 'My first tuple']
-...
-tarantool> <userinput>box.space.tester:delete(0)</userinput>
----
-...
-tarantool> <userinput>box.space.tester:delete('a')</userinput>
-- error: 'Supplied key type of part 0 does not match index part type:
- expected NUM'
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">box.space.<replaceable>space-name</replaceable>.id</emphasis></term>
- <listitem>
- <para>
- (type = number) Ordinal space number. Spaces can be referenced by either name or number.
- Thus, if space 'tester' has id = 800, then "box.space.tester:insert{0}" and "box.space[800]:insert{0}"
- are equivalent requests.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
-
- <term><emphasis role="lua">box.space.<replaceable>space-name</replaceable>.enabled</emphasis></term>
- <listitem>
- <para>
- (type = boolean) Whether or not this space is enabled. The value is false if there is no index.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="box.space.field_count">box.space.<replaceable>space-name</replaceable>.field_count</emphasis>
- </term>
- <listitem>
- <para>
- (type = number) The required field count for all tuples in this space.
- The field_count can be set initially with <code>box.schema.space.create<replaceable>... field_count = new-field-count-value ...</replaceable></code>.
- The default value is 0, which means there is no required field count.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space.<replaceable>space-name</replaceable>.index[]</emphasis>
- </term>
- <listitem>
- <para>
- (type = table) A container for all defined indexes. An index is a Lua object
- of type <code xlink:href="#box.index">box.index</code> with
- methods to search tuples and iterate over them in predefined order.
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>box.space.tester.id,box.space.tester.field_count,box.space.tester.index.primary.type</userinput>
----
-- 512
-- 0
-- TREE
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space.<replaceable>space-name</replaceable>:len()</emphasis>
- </term>
- <listitem>
- <para>
- Returns: (type = number) number of tuples in the space.
- The <code>len()</code> function is only applicable for the memtx storage engine.
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>box.space.tester:len()</userinput>
----
- - 2
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space.<replaceable>space-name</replaceable>:truncate()</emphasis>
- </term>
- <listitem>
- <para>
- Deletes all tuples.
- </para>
- <para>
- Complexity Factors: Index size, Index type, Number of tuples accessed.
- </para>
- <para>
- Returns: nil.
- </para>
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>box.space.tester:truncate()</userinput>
----
-...
-tarantool> <userinput>box.space.tester:len()</userinput>
----
- - 0
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis role="lua">box.space.<replaceable>space-name</replaceable>:inc{<replaceable>field-value [, field-value ...]</replaceable>}</emphasis>
- </term>
- <listitem>
- <para>
- Increments a counter in a tuple whose primary key matches the field-value(s).
- The field following the primary-key fields will be the counter.
- If there is no tuple matching the field-value(s), a new one is inserted
- with initial counter value set to 1.
- </para>
- <para>Parameters: <code>space-name</code>, <code>field-value(s)</code> = values
- which must match the primary key.
- </para>
- <para>
- Returns: (type = number) the new counter value.
- </para>
- <para>
- Complexity Factors: Index size, Index type, WAL settings.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>s = box.schema.space.create('forty_second_space')</userinput>
----
-...
-tarantool> <userinput>s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})</userinput>
----
-...
-tarantool> <userinput>box.space.forty_second_space:inc{1,'a'}</userinput>
----
-- 1
-...
-tarantool> <userinput>box.space.forty_second_space:inc{1,'a'}</userinput>
----
-- 2
-...</programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis role="lua">box.space.<replaceable>space-name</replaceable>:dec{<replaceable>field-value [, field-value ...]</replaceable>}</emphasis>
- </term>
- <listitem>
- <para>
- Decrements a counter in a tuple whose primary key matches the field-value(s).
- The field following the primary-key fields will be the counter.
- If there is no tuple matching the field-value(s), a new one is not inserted.
- If the counter value drops to zero, the tuple is deleted.
- </para>
- <para>
- Parameters: <code>space-name</code>, <code>field-value(s)</code> = values
- which must match the primary key.
- </para>
- <para>
- Returns: (type = number) the new counter value.
- </para>
- <para>
- Complexity Factors: Index size, Index type, WAL settings.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>s = box.schema.space.create('space19')</userinput>
----
-...
-tarantool> <userinput>s:create_index('primary', {unique = true, parts = {1, 'NUM', 2, 'STR'}})</userinput>
----
-...
-tarantool> <userinput>box.space.space19:insert{1,'a',1000}</userinput>
----
-- [1, 'a', 1000]
-...
-tarantool> <userinput>box.space.space19:dec{1,'a'}</userinput>
----
-- 999
-...
-tarantool> <userinput>box.space.space19:dec{1,'a'}</userinput>
----
-- 998
-... </programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space.<replaceable>space-name</replaceable>:auto_increment{<replaceable>field-value [, field-value ...]</replaceable>}</emphasis>
- </term>
- <listitem>
- <para>
- Insert a new tuple using an auto-increment primary key.
- The space specified by space-name must have a
- NUM primary key index of type TREE.
- The primary-key field will be incremented before the insert.
- </para>
- <para>
- Parameters: <code>space-name</code>, <code>field-value(s)</code> = values for the tuple's fields,
- other than the primary-key field.
- </para>
- <para>
- Returns: (type = tuple) the inserted tuple.
- </para>
- <para>
- Complexity Factors: Index size, Index type, Number of indexes accessed, WAL settings.
- </para>
- <para>
- Possible errors: index has wrong type or primary-key indexed field is not a number.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>box.space.tester:auto_increment{'Fld#1', 'Fld#2'}</userinput>
----
-- [1, 'Fld#1', 'Fld#2']
-...
-tarantool> <userinput>box.space.tester:auto_increment{'Fld#3'}</userinput>
----
-- [2, 'Fld#3']
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space.<replaceable>space-name</replaceable>:pairs()</emphasis>
- </term>
- <listitem>
- <para>
- A helper function to prepare for iterating over all tuples in a space.
- </para>
- <para>
- Returns: (type = function) function which can be used in a for/end loop.
- Within the loop, a value (type = tuple) is returned for each iteration.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting><prompt>tarantool></prompt> <userinput>s = box.schema.space.create('space33')</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>s:create_index('X', {}) -- index 'X' has default parts {1,'NUM'}</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>s:insert{0,'Hello my '}; s:insert{1,'Lua world'}</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>tmp = ''; for k, v in s:pairs() do tmp = tmp .. v[2] end</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>tmp</userinput>
----
-- Hello my Lua world
-...</programlisting>
- </listitem>
- </varlistentry>
-
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space._schema</emphasis>
- </term>
- <listitem>
- <para>
- _schema is a system tuple set. Its single tuple contains these fields:
- 'version', major-version-number, minor-version-number.
- </para>
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
- The following function will display all fields in all tuples of _schema.
-<programlisting>
-console = require('console'); console.delimiter('!')
-function example()
- local ta = {}, i, line
- for k, v in box.space._schema:pairs() do
- i = 1
- line = ''
- while i <= #v do line = line .. v[i] .. ' ' i = i + 1 end
- table.insert(ta, line)
- end
- return ta
-end!
-console.delimiter('')!</programlisting>
- Here is what example() returns in a typical installation:
-<programlisting>
-<prompt>tarantool></prompt> <userinput>example()</userinput>
----
-- - 'cluster 1ec4e1f8-8f1b-4304-bb22-6c47ce0cf9c6 '
- - 'max_id 520 '
- - 'version 1 6 '
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space._space</emphasis>
- </term>
- <listitem>
- <para>
- _space is a system tuple set. Its tuples contain these fields:
- id, uid, space-name, engine, field_count, temporary.
- </para>
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
- The following function will display all simple fields in all tuples of _space.
-<programlisting>console = require('console'); console.delimiter('!')
-function example()
- local ta = {}, i, line
- for k, v in box.space._space:pairs() do
- i = 1
- line = ''
- while i <= #v do
- if type(v[i]) ~= 'table' then
- line = line .. v[i] .. ' '
- end
- i = i + 1
- end
- table.insert(ta, line)
- end
- return ta
-end!
-console.delimiter('')!</programlisting>
- Here is what example() returns in a typical installation:
-<programlisting>
-<prompt>tarantool></prompt> <userinput>example()</userinput>
----
-- - '272 1 _schema memtx 0 '
- - '280 1 _space memtx 0 '
- - '288 1 _index memtx 0 '
- - '296 1 _func memtx 0 '
- - '304 1 _user memtx 0 '
- - '312 1 _priv memtx 0 '
- - '320 1 _cluster memtx 0 '
- - '512 1 tester memtx 0 '
- - '513 1 origin sophia 0 '
- - '514 1 archive memtx 0 '
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space._index</emphasis>
- </term>
- <listitem>
- <para>
- _index is a system tuple set. Its tuples contain these fields:
- space-id index-id index-name index-type index-is-unique index-field-count
- [tuple-field-no, tuple-field-type ...].
- </para>
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
- The following function will display all fields in all tuples of _index.
-<programlisting>console = require('console'); console.delimiter('!')
-function example()
- local ta = {}, i, line
- for k, v in box.space._index:pairs() do
- i = 1
- line = ''
- while i <= #v do line = line .. v[i] .. ' ' i = i + 1 end
- table.insert(ta, line)
- end
- return ta
-end!
-console.delimiter('')!</programlisting>
- Here is what example() returns in a typical installation:
-<programlisting>
-<prompt>tarantool></prompt> <userinput>example()</userinput>
----
-- - '272 0 primary tree 1 1 0 str '
- - '280 0 primary tree 1 1 0 num '
- - '280 1 owner tree 0 1 1 num '
- - '280 2 name tree 1 1 2 str '
- - '288 0 primary tree 1 2 0 num 1 num '
- - '288 2 name tree 1 2 0 num 2 str '
- - '296 0 primary tree 1 1 0 num '
- - '296 1 owner tree 0 1 1 num '
- - '296 2 name tree 1 1 2 str '
- - '304 0 primary tree 1 1 0 num '
- - '304 1 owner tree 0 1 1 num '
- - '304 2 name tree 1 1 2 str '
- - '312 0 primary tree 1 3 1 num 2 str 3 num '
- - '312 1 owner tree 0 1 0 num '
- - '312 2 object tree 0 2 2 str 3 num '
- - '320 0 primary tree 1 1 0 num '
- - '320 1 uuid tree 1 1 1 str '
- - '512 0 primary tree 1 1 0 num '
- - '513 0 first tree 1 1 0 NUM '
- - '514 0 first tree 1 1 0 STR '
-...</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space._user</emphasis>
- </term>
- <listitem>
- <para>
- _user is a new system tuple set for support of the <link linkend="authentication">authorization feature</link>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space._priv</emphasis>
- </term>
- <listitem>
- <para>
- _priv is a new system tuple set for support of the authorization feature.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space._cluster</emphasis>
- </term>
- <listitem>
- <para>
- _cluster is a new system tuple set for support of the <olink targetptr="replication">replication feature</olink>.
- </para>
- </listitem>
- </varlistentry>
-
-
-</variablelist>
-
-<bridgehead renderas="sect4">Example showing use of the box.space functions</bridgehead>
-<para>
-This function will illustrate how to look at all the spaces,
-and for each display: approximately
-how many tuples it contains, and the first field of its first tuple.
-The function uses Tarantool box.space functions len() and pairs().
-The iteration through the spaces is coded as a scan of the
-_space system tuple set, which contains metadata. The third field in
-_space contains the space name, so the key instruction "space_name = v[3]"
-means "space_name = the space_name field in the tuple of _space
-that we've just fetched with pairs()". The function returns a table.
-</para>
-<programlisting>
-console = require('console'); console.delimiter('!')
-function example()
- local tuple_count, space_name, line
- local ta = {}
- for k, v in box.space._space:pairs() do
- space_name = v[3]
- if box.space[space_name].index[0] ~= nil then
- tuple_count = box.space[space_name]:len()
- else
- tuple_count = 0
- end
- line = space_name .. ' tuple_count =' .. tuple_count
- if tuple_count > 0 then
- for k1, v1 in box.space[space_name]:pairs() do
- line = line .. '. first field in first tuple = ' .. v1[1]
- break
- end
- end
- table.insert(ta, line)
- end
- return ta
-end!
-console.delimiter('')!
-</programlisting>
-<para>
-... And here is what happens when one invokes the function:
-<programlisting>
-<prompt>tarantool></prompt> <userinput>example()</userinput>
----
-- - _schema tuple_count =3. first field in first tuple = cluster
- - _space tuple_count =15. first field in first tuple = 272
- - _index tuple_count =25. first field in first tuple = 272
- - _func tuple_count =1. first field in first tuple = 1
- - _user tuple_count =4. first field in first tuple = 0
- - _priv tuple_count =6. first field in first tuple = 1
- - _cluster tuple_count =1. first field in first tuple = 1
- - tester tuple_count =2. first field in first tuple = 1
- - origin tuple_count =0
- - archive tuple_count =13. first field in first tuple = test_0@tarantool.org
- - space55 tuple_count =0
- - tmp tuple_count =0
- - forty_second_space tuple_count =1. first field in first tuple = 1
-...
-</programlisting>
-</para>
-
-</section>
-
-<section xml:id="sp-box-index">
- <title>Package <code >box.index</code></title>
-<variablelist xml:id="box.index" xreflabel="box.index">
- <para>
- The <code>box.index</code> package provides read-only access for index definitions and index keys.
- Indexes are contained in <code
- xlink:href="#box.space">box.space.<replaceable>space-name</replaceable>.index</code> 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 of type <code>box.index</code> in the
- storage engine.
- </para>
- <varlistentry>
- <term><emphasis role="lua">box.space.<replaceable>space-name</replaceable>.index.<replaceable>index-name</replaceable>.unique</emphasis></term>
- <listitem>
- <para>
- (type = boolean) true if the index is unique.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space.<replaceable>space-name</replaceable>.index.<replaceable>index-name</replaceable>.type</emphasis>
- </term>
- <listitem>
- <para>
- (type = string) index type, 'TREE' or 'HASH' or 'BITSET' or 'RTREE'.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space.<replaceable>space-name</replaceable>.index.<replaceable>index-name</replaceable>.parts</emphasis>
- </term>
- <listitem>
- <para>
- An array describing index key fields.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term></term>
- <listitem><bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>box.space.tester.index.primary</userinput>
----
- unique: true
- parts:
- 0:
- type: NUM
- fieldno: 1
- id: 0
- space_id: 513
- name: primary
- type: TREE
-...</programlisting></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="boxindexiterator" xreflabel="box.index.iterator(type, ...)">
- box.space.<replaceable>space-name</replaceable>.index[.<replaceable>index-name</replaceable>]:pairs(<replaceable>bitset-value | field-value..., iterator-type</replaceable>)</emphasis>
- </term>
- <listitem>
- <para>
- This method provides iteration support within an
- index. Parameter <code>type</code> 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,
- a 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.
- </para>
- <para xml:id="iterator-consistency">
- 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": by causing a write to
- disk, network, or by an explicit call to <emphasis
- role="lua" xlink:href="#fiber.yield">fiber.yield()</emphasis>.
- 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.
- </para>
- <para>
- Parameters:
- <code>type</code> — iteration strategy as defined in tables below.
- </para>
- <para>
- Returns: this method returns an iterator closure, i.e.
- a <code>function</code> which can be used to
- get the next value on each invocation.
- </para>
- <para>
- Complexity Factors: Index size, Index type, Number of tuples accessed.
- </para>
- <para>
- Possible Errors:
- Selected iteration type is not supported in
- the subject index type, or supplied parameters
- do not match iteration type.
- </para>
-
- <xi:include href="iterator-types.xml"/>
-
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-<prompt>tarantool></prompt> <userinput> s = box.schema.space.create('space17')</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput> s:create_index('primary', {parts = {1, 'STR', 2, 'STR'}})</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput> s:insert{'C', 'C'}</userinput>
----
-- ['C', 'C']
-...
-<prompt>tarantool></prompt> <userinput> s:insert{'B', 'A'}</userinput>
----
-- ['B', 'A']
-...
-<prompt>tarantool></prompt> <userinput> s:insert{'C', '!'}</userinput>
----
-- ['C', '!']
-...
-<prompt>tarantool></prompt> <userinput> s:insert{'A', 'C'}</userinput>
----
-- ['A', 'C']
-...
-<prompt>tarantool></prompt> <userinput> console = require('console'); console.delimiter('!')</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput> function example()
- > for _, tuple in
- > s.index.primary:pairs(nil, {iterator = box.index.ALL}) do
- > print(tuple)
- > end
- > end!</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput> console.delimiter('')!</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput> example()</userinput>
-['A', 'C']
-['B', 'A']
-['C', '!']
-['C', 'C']
----
-...
-<prompt>tarantool></prompt> <userinput>s:drop()</userinput>
----
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="box.index.iterator.select" xreflabel="box.index.select(type, ...)">
- box.space.<replaceable>space-name</replaceable>[.index.<replaceable>index-name</replaceable>]:select({<replaceable>[field-value [, field-value ...]]</replaceable>}, {<replaceable>[option [, option ...]]</replaceable>})</emphasis>
- </term>
- <listitem>
- <para>
- This is is an alternative to <olink targetptr="box.select">box.space...select()</olink>
- which goes via a particular index and can make use of additional parameters that
- specify the iterator type, and the limit (that is, the maximum number of tuples to
- return) and the offset (that is, which tuple to start with in the list).
- </para>
- <para>
- Parameters: <code>field-value(s)</code> = values to be matched against the index key.
- <code>option(s)</code> = any or all of <code>iterator=<replaceable>iterator-type</replaceable></code>,
- <code>limit=<replaceable>maximum-number-of-tuples</replaceable></code>,
- <code>offset=<replaceable>start-tuple-number</replaceable></code>.
- </para>
- <para>
- Returns: (type = tuple set, as a Lua table) the tuple or tuples that match the field values.
- </para>
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-# Create a space named tester.
-# Create a unique index 'primary', which won't be needed for this example.
-# Create a non-unique index 'secondary' with an index on the second field.
-# Insert three tuples, values in field[2] equal to 'X', 'Y', and 'Z'.
-# Select all tuples where the secondary index keys are greater than 'X'.
-box.schema.space.create('tester')
-box.space.tester:create_index('primary', {parts = {1, 'NUM' }})
-box.space.tester:create_index('secondary', {type = 'tree', unique = false, parts = {2, 'STR'}})
-box.space.tester:insert{1,'X','Row with field[2]=X'}
-box.space.tester:insert{2,'Y','Row with field[2]=Y'}
-box.space.tester:insert{3,'Z','Row with field[2]=Z'}
-box.space.tester.index.secondary:select({'X'}, {iterator = 'GT', limit = 1000})
-</programlisting>
-The result will be a table of tuples and will look like this:
-<programlisting>
----
-- - [2, 'Y', 'Row with field[2]=Y']
- - [3, 'Z', 'Row with field[2]=Z']
-...
-</programlisting>
- </para>
- <para>
- Note: <code>[.index.<replaceable>index-name</replaceable>]</code> is optional. If it is
- omitted, then the assumed index is the first (primary-key) index. Therefore, for
- the example above, <code>box.space.tester:select({1}, {iterator = 'GT'})</code>
- would have returned the same two rows, via the 'primary' index.
- </para>
- <para>
- Note: <code>iterator = <replaceable>iterator type</replaceable></code> is optional.
- If it is omitted, then <code>iterator = 'EQ'</code> is assumed.
- </para>
- <para>
- Note: <code><replaceable>field-value [, field-value ...]</replaceable></code> is optional.
- If it is omitted, then every key in the index is considered to be a match,
- regardless of iterator type.
- Therefore, for the example above, <code>box.space.tester:select{}</code>
- will select every tuple in the tester space via the first (primary-key) index.
- </para>
- <para>
- Note: <code>box.space.<replaceable>space-name</replaceable>.index.<replaceable>index-name</replaceable>:select(...)[1]</code>.
- can be replaced by <code>box.space.<replaceable>space-name</replaceable>.index.<replaceable>index-name</replaceable>:get(...)</code>.
- That is, <code>get</code> can be used as a convenient shorthand to get the first
- tuple in the tuple set that would be returned by <code>select</code>.
- However, if there is more than one tuple in the tuple set, then <code>get</code> returns an error.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space.<replaceable>space-name</replaceable>.index.<replaceable>index-name</replaceable>:min([<replaceable>key-value</replaceable>])</emphasis>
- </term>
- <listitem>
- <para>
- Find the minimum value in the specified index.
- </para>
- <para>
- Returns: (type = tuple) the tuple for the first key in the index.
- If optional <code>key-value</code> is supplied, returns the first key which is greater than or equal to key-value.
- </para>
- <para>
- Complexity Factors: Index size, Index type.
- </para>
- <para>
- Possible errors: index is not of type 'TREE'.
- </para>
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>box.space.tester.index.primary:min()</userinput>
----
-- ['Alpha!', 55, 'This is the first tuple!']
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space.<replaceable>space-name</replaceable>.index.<replaceable>index-name</replaceable>:max([<replaceable>key-value</replaceable>])</emphasis>
- </term>
- <listitem>
- <para>
- Find the maximum value in the specified index.
- </para>
- <para>
- Returns: (type = tuple) the tuple for the last key in the index.
- If optional <code>key-value</code> is supplied, returns the last key which is less than or equal to key-value.
- </para>
- <para>
- Complexity Factors: Index size, Index type.
- </para>
- <para>
- Possible errors: index is not of type 'TREE'.
- </para>
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>box.space.tester.index.primary:max()</userinput>
----
-- ['Gamma!', 55, 'This is the third tuple!']
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space.<replaceable>space-name</replaceable>.index.<replaceable>index-name</replaceable>:random(<replaceable>random-value</replaceable>)</emphasis>
- </term>
- <listitem>
- <para>
- Find a random value in the specified index.
- 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.
- </para>
- <para>
- Parameters: <code>random-value</code> = an arbitrary non-negative integer.
- </para>
- <para>
- Returns: (type = tuple) the tuple for the random key in the index.
- </para>
- <para>
- Complexity Factors: Index size, Index type.
- </para>
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>box.space.tester.index.secondary:random(1)</userinput>
----
-- ['Beta!', 66, 'This is the second tuple!']
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.space.<replaceable>space-name</replaceable>.index.<replaceable>index-name</replaceable>:count(<replaceable>key-value</replaceable>, <replaceable>options</replaceable>)</emphasis>
- </term>
- <listitem>
- <para>
- Iterate over an index, counting the number of tuples which equal the
- provided search criteria.
- </para>
- <para>
- Parameters: <code>key-value</code> = the value which must match the key(s)
- in the specified index. The type may be a list of field-values, or a tuple containing
- only the field-values.
- </para>
- <para>
- Returns: (type = number) the number of matching index keys.
- The <code>index</code> function is only applicable for the memtx storage engine.
- </para>
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>box.space.tester.index.primary:count(999)</userinput>
----
-- 0
-...
-</programlisting>
-<programlisting>tarantool> <userinput>box.space.tester.index.primary:count('Alpha!', { iterator = 'LE' })</userinput>
----
- - 1
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
-</variablelist>
-
-<bridgehead renderas="sect4">Example showing use of the box functions</bridgehead>
-<para xml:id="box-function-example" xreflabel="box-function-example">
-This example will work with the sandbox configuration described in the preface.
-That is, there is a space named tester with a numeric primary key.
-The example function will: (1) select a tuple whose key value is 1000;
-(2) return an error if the tuple already exists and already has 3 fields;
-(3) Insert or replace the tuple with: field[1] = 1000, field[2] = a uuid, field[3] = number of seconds since 1970-01-01;
-(4) Get field[3] from what was replaced;
-(5) Format the value from field[3] as yyyy-mm-dd hh:mm:ss.ffff;
-(6) Return the formatted value.
-The function uses Tarantool box functions <code>box.space...select</code>, <code>box.space...replace</code>, <code>fiber.time</code>, <code>uuid.str()</code>.
-The function uses Lua functions
-<link xlink:href="http://www.lua.org/pil/22.1.html">os.date()</link>
-and <link xlink:href="http://www.lua.org/pil/20.html">string.sub()</link>.
-</para>
-<programlisting>
-console = require('console'); console.delimiter('!')
-function example()
- local a, b, c, table_of_selected_tuples, replaced_tuple, time_field
- local formatted_time_field
- local fiber = require('fiber')
- table_of_selected_tuples = box.space.tester:select{1000}
- if table_of_selected_tuples ~= nil then
- if table_of_selected_tuples[1] ~= nil then
- if #table_of_selected_tuples[1] == 3 then
- box.error({code=1, reason='This tuple already has 3 fields'})
- end
- end
- end
- replaced_tuple = box.space.tester:replace
- {1000, require('uuid').str(), tostring(fiber.time())}
- time_field = tonumber(replaced_tuple[3])
- formatted_time_field = os.date("%Y-%m-%d %H:%M:%S", time_field)
- c = time_field % 1
- d = string.sub(c, 3, 6)
- formatted_time_field = formatted_time_field .. '.' .. d
- return formatted_time_field
-end!
-console.delimiter('')!
-</programlisting>
-<para>
-... And here is what happens when one invokes the function:
-<programlisting>
-<prompt>tarantool></prompt> <userinput>box.space.tester:delete(1000)</userinput>
----
-- 1000: {'264ee2da03634f24972be76c43808254', '1391037015.6809'}
-...
-<prompt>tarantool></prompt> <userinput>example(1000)</userinput>
----
-- 2014-01-29 16:11:51.1582
-...
-<prompt>tarantool></prompt> <userinput>example(1000)</userinput>
----
-- error: 'This tuple already has 3 fields'
-...
-</programlisting>
-</para>
-
-</section>
-
-<section xml:id="RTREE">
- <title>Package <code >box.index</code> with index type = RTREE for spatial searches</title>
- <para>
- The <code>box.index</code> package may be used for spatial searches
- if the index type is RTREE. There are operations for searching
- <emphasis>rectangles</emphasis>. Rectangles are described according
- to their X-axis (horizontal axis) and Y-axis (vertical axis)
- coordinates in a grid of arbitrary size. Here is a picture of four
- rectangles on a grid with 11 horizontal points and 11 vertical points:
-<programlisting>
- X AXIS
- 1 2 3 4 5 6 7 8 9 10 11
- 1
- 2 *-------+ <-Rectangle#1
-Y AXIS 3 | |
- 4 +-------*
- 5 *-----------------------+ <-Rectangle#2
- 6 | |
- 7 | *---+ | <-Rectangle#3
- 8 | | | |
- 9 | +---* |
- 10 +-----------------------*
- 11 * <-Rectangle#4
-</programlisting>
- The rectangles are defined according to this scheme:
- {X-axis coordinate of top left,
- Y-axis coordinate of top left,
- X-axis coordinate of bottom right,
- Y-axis coordinate of bottom right} -- or more succinctly:
- {x1,y1,x2,y2}. So in the picture ...
- Rectangle#1 starts at position 1 on the X axis and position
- 2 on the Y axis, and ends at position 3 on the X axis and
- position 4 on the Y axis, so its coordinates are
- {1,2,3,4}. Rectangle#2's coordinates are {3,5,9,10}.
- Rectangle#3's coordinates are {4,7,5,9}. And finally
- Rectangle#4's coordinates are {10,11,10,11}.
- Rectangle#4 is actually a "point" since it has zero
- width and zero height, so it could have been described
- with only two digits: {10,11}.
- </para>
- <para>
- Some relationships between the rectangles are:
- "Rectangle#1's nearest neighbor is Rectangle#2", and
- "Rectangle#3 is entirely inside Rectangle#2".
- </para>
- <para>
- Now let us create a space and add an RTREE index.
-<programlisting>
-<userinput>s = box.schema.create_space('rectangles')</userinput>
-<userinput>i = s:create_index('primary',{type='HASH',parts={1,'NUM'}})</userinput>
-<userinput>r = s:create_index('spatial',{type='RTREE',unique=false,parts={2,'ARRAY'}})</userinput>
-</programlisting>
- Field#1 doesn't matter, we just make it because we need a primary-key index.
- (RTREE indexes cannot be unique and therefore cannot be primary-key indexes.)
- The second field must be an "array", which means its values must represent
- {x,y} points or {x1,y1,x2,y2} rectangles.
- Now let us populate the table by inserting two tuples,
- containing the coordinates of Rectangle#2 and Rectangle#4.
-<programlisting>
-<userinput>s:insert{1, {3,5,9,10}}</userinput>
-<userinput>s:insert{2, {10,11}}</userinput>
-</programlisting>
- and now, following the description of <link linkend="rtree-iterator">RTREE iterator types</link>,
- we can search the rectangles with these requests:
-<programlisting>
-<userinput>r:select({10,11,10,11},{iterator='EQ'}) -- Request#1 (returns 1 tuple)</userinput>
-<userinput>r:select({4,7,5,9},{iterator='GT'}) -- Request#2 (returns 1 tuple)</userinput>
-<userinput>r:select({1,2,3,4},{iterator='NEIGHBOR'}) -- Request#3 (returns 2 tuples)</userinput>
-</programlisting>
- Request#1 returns 1 tuple because the point {10,11} is the same as the
- rectangle {10,11,10,11} ("Rectangle#4" in the picture).
- Request#2 returns 1 tuple because the rectangle {4,7,5,9}, which was
- "Rectangle#3" in the picture, is entirely within{3,5,9,10} which was Rectangle#2.
- Request#3 returns 2 tuples, because the NEIGHBOR iterator always returns all
- tuples, and the first returned tuple will be {3,5,9,10} ("Rectangle#2" in
- the picture) because it is the closest neighbor of {1,2,3,4} ("Rectangle#1"
- in the picture).
- </para>
- <para>
- More examples of spatial searching are online in the file
- <link xlink:href="https://github.com/tarantool/tarantool/wiki/R-tree-index-quick-start-and-usage">"R tree index quick start and usage"</link>.
- </para>
-</section>
-
-<section xml:id="sp-error">
- <title>Package <code>box.error</code></title>
- <para>
- The <code>box.error</code> function is for raising an error.
- The difference between this function
- and Lua's built-in <code>error()</code> 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 <constant>ER_PROC_LUA</constant>.
- </para>
-<variablelist xml:id="error" xreflabel="error">
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.error({[code=<replaceable>errcode-number</replaceable>,] reason=<replaceable>errtext-string</replaceable>})</emphasis>
- </term>
- <listitem>
- <para>
- When called with a Lua-table argument, the errorcode-number and errtext-string have any user-desired values.
- The result will be those values.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.error()</emphasis>
- </term>
- <listitem>
- <para>
- When called without arguments, <code>box.error()</code> re-throws whatever the last error was.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.error(<replaceable>errcode-number, errtext-string [, errtext-string ...]</replaceable>)</emphasis>
- </term>
- <listitem>
- <para>
- Emulate a request error, with text based on one of the pre-defined Tarantool errors defined in
- the file <link xlink:href="https://github.com/tarantool/tarantool/blob/master/src/errcode.h"><filename>errcode.h</filename></link>
- in the source tree. Lua constants which correspond to those Tarantool errors
- are defined as members of <code>box.error</code>, for example <code>box.error.NO_SUCH_USER</code> == 45.
- </para>
- <para>
- Parameters: <code>errcode-number</code> = number of a pre-defined error,
- <code>errtext-string</code> = part of the message which will accompany the error.
- For example the NO_SUCH_USER message is "User '%s' is not found" -- it includes one
- "%s" component which will be replaced with <code>errtext-string</code>. Thus a call to
- <code>box.error(box.error.NO_SUCH_USER, 'joe')</code> or
- <code>box.error(45, 'joe')</code> will result in an error with the accompanying
- message "User 'joe' is not found".
- </para>
- <para>
- Possible errors: whatever is specified in errcode-number.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting><prompt>tarantool></prompt> <userinput>box.error({code=555, reason='Arbitrary message'})</userinput>
----
-- error: Arbitrary message
-...
-
-<prompt>tarantool></prompt> <userinput>box.error()</userinput>
----
-- error: Arbitrary message
-...
-
-<prompt>tarantool></prompt> <userinput>box.error(box.error.FUNCTION_ACCESS_DENIED, 'A', 'B', 'C')</userinput>
----
-- error: A access denied for user 'B' to function 'C'
-...</programlisting>
- </listitem>
- </varlistentry>
-
-</variablelist>
-</section>
-
-<section xml:id="sp-box-tuple">
- <title>Package <code>box.tuple</code></title>
-<variablelist xml:id="box.tuple" xreflabel="box.tuple">
- <para>The <code>box.tuple</code> package provides read-only access for the <code>box.tuple</code> userdata
- type. It allows, for a single tuple: selective retrieval of the
- field contents, retrieval of information about size,
- iteration over all the fields, and conversion to a Lua table.
- </para>
- <varlistentry>
- <term>
- <emphasis role="lua">box.tuple.new(<replaceable>scalar-value | Lua-table-value</replaceable>)</emphasis>
- </term>
- <listitem>
- <para>
- Construct a new tuple from either a scalar or a Lua table.
- Alternatively, one can get new tuples from tarantool's
- SQL-like statements: SELECT, INSERT, UPDATE, REPLACE,
- which can be regarded as statements that do new()
- implicitly.
- </para>
- <para>
- Parameters: <code>scalar-value | Lua-table-value</code> = the value that will become the tuple contents.
- </para>
- <para>
- Returns: (type = tuple) a new tuple.
- </para>
- <para>
- In the following example, x will be a new table object containing one tuple and t will be a new tuple object.
- Saying <code>t</code> returns the entire tuple t.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
- <programlisting>tarantool> <userinput>x = box.space.tester:insert{33,tonumber('1'),tonumber64('2')}:totable()</userinput>
----
-...
-tarantool> <userinput>t = box.tuple.new({'abc', 'def', 'ghi', 'abc'})</userinput>
----
-...
-tarantool> <userinput>t</userinput>
----
-- ['abc', 'def', 'ghi', 'abc']
-...</programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis role="lua"># <replaceable>tuple-value</replaceable></emphasis>
- </term>
- <listitem>
- <para>
- The # operator in Lua means "return count of components".
- So, if t is a tuple instance, <code>#t</code>
- will return the number of
- fields.
- </para>
- <para>
- Returns: (type = number) number of fields.
- </para>
- <para>
- In the following example, a tuple named t is created
- and then the number of fields in t is returned.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
- <programlisting>tarantool> <userinput>t = box.tuple.new({'Fld#1','Fld#2','Fld#3','Fld#4'})</userinput>
----
-...
-tarantool> <userinput>#t</userinput>
----
-- 4
-...</programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis role="lua"> <replaceable>tuple-value</replaceable>:bsize()</emphasis>
- </term>
- <listitem>
- <para>
- If t is a tuple instance, <code>t:bsize()</code>
- will return the number of bytes in the tuple.
- It is useful to check this number when making changes to data,
- because there is a fixed maximum: one megabyte.
- Every field has one or more "length" bytes preceding the
- actual contents, so bsize() returns a value which is
- slightly greater than the sum of the lengths of the contents.
- </para>
- <para>
- Returns: (type = number) number of bytes.
- </para>
- <para>
- In the following example, a tuple named t is created
- which has three fields, and for each field it takes one byte
- to store the length and three bytes to store the contents,
- and a bit for overhead, so bsize() returns 3*(1+3)+1.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
- <programlisting>tarantool> <userinput>t = box.tuple.new({'aaa','bbb','ccc'})</userinput>
----
-...
-tarantool> <userinput>t:bsize()</userinput>
----
- - 13
-...</programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis role="lua"><replaceable>tuple-value</replaceable> [ <replaceable>field-number</replaceable> ]</emphasis>
- </term>
- <listitem>
- <para>
- If t is a tuple instance, <code>t[<replaceable>field-number</replaceable>]</code>
- will return the field numbered <code>field-number</code> in the tuple.
- The first field is t[1].
- </para>
- <para>
- Returns: (type = scalar) field value.
- </para>
- <para>
- In the following example, a tuple named t is created
- and then the second field in t is returned.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
- <programlisting>tarantool> <userinput>t = box.tuple.new({'Fld#1','Fld#2','Fld#3','Fld#4'})</userinput>
----
-...
-tarantool> <userinput>t[2]</userinput>
----
- - Fld#2
-...</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua"><replaceable>tuple-value</replaceable>:find(<replaceable>[field-number,] field-value</replaceable>) or <replaceable>tuple-value</replaceable>:findall(<replaceable>[field-number,] field-value</replaceable>)</emphasis>
- </term>
- <listitem>
- <para>
- If t is a tuple instance, <code>t:find(<replaceable>field-value</replaceable>)</code>
- will return the number of the first field in t that matches the field value), and
- <code>t:findall(<replaceable>field-value [, field-value ...]</replaceable>)</code>
- will return numbers of all fields in t that match the field value. Optionally
- one can put a numeric argument field-number before the search-value to indicate
- <quote>start searching at field number <code>field-number</code>.</quote>
- </para>
- <para>
- Returns: (type = number) the number of the field in the tuple.
- </para>
- <para>
- In the following example, a tuple named t is created
- and then: the number of the first field in t which matches 'a' is returned,
- then the numbers of all the fields in t which match 'a' are returned,
- then the numbers of all the fields in t which match 'a' and are at or after the second field
- are returned.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
- <programlisting>tarantool> <userinput>t = box.tuple.new({'a','b','c','a'})</userinput>
----
-...
-tarantool> <userinput>t:find('a')</userinput>
----
-- 1
-...
-tarantool> <userinput>t:findall('a')</userinput>
----
-- 1
-- 4
-...
-tarantool> <userinput>t:findall(2, 'a')</userinput>
----
- - 4
-...</programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis role="lua"><replaceable>tuple-value</replaceable>:transform(<replaceable>start-field-number, fields-to-remove [, field-value ...]</replaceable>)</emphasis>
- </term>
- <listitem>
- <para>
- If t is a tuple instance, <code>t:transform(<replaceable>start-field-number</replaceable>,<replaceable>fields-to-remove</replaceable>)</code>
- will return a tuple where, starting from field start-field-number, a number of fields (fields-to-remove) are removed.
- Optionally one can add more arguments after fields-to-remove to indicate new values that will replace
- what was removed.
- </para>
- <para>
- Parameters: <code>start-field-number</code> = base 1, may be negative, <code>fields-to-remove</code>, <code>field-values(s)</code>.
- </para>
- <para>
- Returns: (type = tuple) a new tuple.
- </para>
- <para>
- In the following example, a tuple named t is created
- and then, starting from the second field, two fields are removed
- but one new one is added, then the result is returned.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
- <programlisting>tarantool> <userinput>t = box.tuple.new({'Fld#1','Fld#2','Fld#3','Fld#4','Fld#5'})</userinput>
----
-...
-tarantool> <userinput>t:transform(2,2,'x')</userinput>
----
-- ['Fld#1', 'x', 'Fld#4', 'Fld#5']
-...</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua"><replaceable>tuple-value</replaceable>:unpack()</emphasis>
- </term>
- <listitem>
- <para>
- If t is a tuple instance, <code>t:unpack(<replaceable>n</replaceable>)</code>
- will return all fields.
- </para>
- <para>
- Returns: (type = scalar) field(s) from the tuple.
- </para>
- <para>
- In the following example, a tuple named t is created
- and then all its fields are selected,
- then the result is returned.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
- <programlisting>tarantool> <userinput>t = box.tuple.new({'Fld#1','Fld#2','Fld#3','Fld#4','Fld#5'})</userinput>
----
-...
-tarantool> <userinput>t:unpack()</userinput>
----
- - Fld#1
- - Fld#2
- - Fld#3
- - Fld#4
- - Fld#5
-...</programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis role="lua"><replaceable>tuple-value</replaceable>:pairs()</emphasis>
- </term>
- <listitem>
- <para>
- In Lua, lua-table-value:pairs() is a method which returns: function, lua-table-value, nil.
- Tarantool has extended this so that tuple-value:pairs() returns: function, tuple-value, nil.
- It is useful for Lua iterators, because Lua iterators traverse
- a value's components until an end marker is reached.
- </para>
- <para>
- Returns: (type = function) function, (type = tuple) tuple-value, (type = nil) nil.
- </para>
- <para>
- In the following example, a tuple named t is created
- and then all its fields are selected using a Lua for-end loop.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>t = box.tuple.new({'Fld#1','Fld#2','Fld#3','Fld#4','Fld#5'})</userinput>
----
-...
-tarantool> <userinput>tmp = ''; for k, v in t:pairs() do tmp = tmp .. v end</userinput>
----
-...
-tarantool> <userinput>tmp</userinput>
----
-- Fld#1Fld#2Fld#3Fld#4Fld#5
-...</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua"><replaceable>tuple-value</replaceable>:update(<replaceable>{{format, field_no, value}...}</replaceable>)</emphasis>
- </term>
- <listitem>
- <para>
- Update a tuple.
- </para>
- <para>
- This function updates a tuple which is not in a space.
- Compare the function
- <code>box.space.<replaceable>space-name</replaceable>:update{<replaceable>key, format, {field_no, value}...</replaceable>)</code>,
- which updates a tuple in a space.
- </para>
- <para>
- Parameters: briefly:
- <code>format</code> indicates the type of update operation such as '=' for 'assign new value',
- <code>field_no</code> indicates the field number to change such as 2 for field number 2,
- <code>value</code> indicates the string which operates on the field such as 'B' for a new assignable value = 'B'.
- For details: see the description for <code>format</code>, <code>field_no</code>, and <code>value</code>
- in the section <olink targetptr="box.update"><code>box.space.<replaceable>space-name</replaceable>:update{<replaceable>key, format, {field_no, value}...</replaceable>)</code></olink>.
- </para>
- <para>
- Returns: (type = tuple) the new tuple.
- </para>
- <para>
- In the following example, a tuple named t is created
- and then its second field is updated to equal 'B'.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>t = box.tuple.new({'Fld#1','Fld#2','Fld#3','Fld#4','Fld#5'})</userinput>
----
-...
-tarantool> <userinput>t:update({{'=',2,'B'}})</userinput>
----
-- ['Fld#1', 'B', 'Fld#3', 'Fld#4', 'Fld#5']
-...</programlisting>
- </listitem>
- </varlistentry>
-
-</variablelist>
-
-<bridgehead renderas="sect4">Example showing use of the box.tuple functions</bridgehead>
-<para>
-This function will illustrate how to convert tuples to/from
-Lua tables and lists of scalars:
-<programlisting>
- scalars to tuple: tuple = box.tuple.new({scalar1, scalar2, ... scalar_n})
- tuple to Lua table: lua_table = {tuple:unpack()}
- tuple to scalars: scalar1, scalar2, ... scalar_n = tuple:unpack()
- Lua table to tuple: tuple = box.tuple.new(lua_table)
-</programlisting>
-Then it will find the field that contains 'b',
-remove that field from the tuple,
-and display how many bytes remain in the tuple.
-The function uses Tarantool box.tuple functions new(), unpack(), find(), transform(), bsize().
-</para>
-<programlisting>
-console = require('console'); console.delimiter('!')
-function example()
- local tuple1, tuple2, lua_table_1, scalar1, scalar2, scalar3, field_number
- tuple1 = box.tuple.new({'a', 'b', 'c'})
- luatable1 = {tuple1:unpack()}
- scalar1, scalar2, scalar3 = tuple1:unpack()
- tuple2 = box.tuple.new(luatable1)
- field_number = tuple2:find('b')
- tuple2 = tuple2:transform(field_number, 1)
- return 'tuple2 = ' , tuple2 , ' # of bytes = ' , tuple2:bsize()
-end!
-console.delimiter('')!
-</programlisting>
-<para>
-... And here is what happens when one invokes the function:
-<programlisting>
-<prompt>tarantool></prompt> <userinput>example()</userinput>
----
-- 'tuple2 = '
-- ['a', 'c']
-- ' # of bytes = '
-- 5
-...
-</programlisting>
-</para>
-
-</section>
-
-<!-- end of lib -->
-
-
-<!-- end of lib -->
-
-<!-- end of lib -->
-
-<section xml:id="sp-box-cfg">
- <title>Packages <code>box.cfg</code>,
- <code>box.info</code>, <code>box.slab</code> and
- <code>box.stat</code>: server introspection</title>
-
-<variablelist>
- <title>Package <code xml:id="box.cfg">box.cfg</code></title>
- <para>
- The box.cfg package is for administrators to specify all the server configuration parameters;
- the full description of the parameters is in section <olink targetptr="configuration-file">Configuration</olink>.
- Use <code>box.cfg</code> without braces to get read-only access to those parameters.
- </para>
- <varlistentry>
- <term><emphasis role="lua">box.cfg</emphasis></term>
- <listitem><bridgehead renderas="sect4">Example</bridgehead><programlisting>
-tarantool> <userinput>box.cfg</userinput>
----
-- too_long_threshold: 0.5
- slab_alloc_factor: 2
- slab_alloc_minimal: 64
- background: false
- slab_alloc_arena: 1
- log_level: 5
- ...
-...
-</programlisting></listitem>
- </varlistentry>
-</variablelist>
-
-<variablelist>
- <title>Package <code>box.info</code></title>
- <para>
- The box.info package provides access to information about
- server variables -- pid, uptime, version and others.
- </para>
-
- <para>
- <emphasis role="strong">recovery_lag</emphasis> holds the
- difference (in seconds) between the current time on the
- machine (wall clock time) and the time stamp of the last
- applied record. In replication setup, this difference can
- indicate the delay taking place before a change is
- applied to a replica.
- </para>
- <para>
- <emphasis role="strong">recovery_last_update</emphasis> is
- the wall clock time of the last change recorded in the
- write-ahead log. To convert it to human-readable time,
- you can use <command>date -d@<replaceable>1306964594.980</replaceable></command>.
- </para>
- <para>
- <emphasis role="strong">status</emphasis> is
- either "primary" or "replica/<hostname>".
- </para>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.info()</emphasis>
- </term>
- <listitem>
- <para>
- Since box.info contents are dynamic, it's not
- possible to iterate over keys with the Lua
- <emphasis>pairs()</emphasis> function. For this
- purpose, <emphasis>box.info()</emphasis> builds and
- returns a Lua table with all keys and values provided
- in the package.
- </para>
- <para>
- Returns: (type = Lua table) keys and values in the package.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-tarantool> <userinput>box.info()</userinput>
-- server:
- lsn: 158
- ro: false
- uuid: 75967704-0115-47c2-9d03-bd2bdcc60d64
- id: 1
- pid: 32561
- version: 1.6.4-411-gcff798b
- snapshot_pid: 0
- status: running
- vclock: {1: 158}
- replication:
- status: off
- uptime: 2778
-...</programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis role="lua">box.info.status, box.info.pid, box.info.version, ...</emphasis>
- </term>
- <listitem>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-tarantool> <userinput>box.info.pid</userinput>
----
-- 1747
-...
-tarantool> <userinput>box.info.logger_pid</userinput>
----
-- 1748
-...
-tarantool> <userinput>box.info.version</userinput>
----
-- 1.6.4-411-gcff798b
-...
-tarantool> <userinput>box.info.uptime</userinput>
----
-- 3672
-...
-tarantool> <userinput>box.info.status</userinput>
----
- - running
-...
-tarantool> <userinput>box.info.recovery_lag</userinput>
----
- - 0.000
-...
-tarantool> <userinput>box.info.recovery_last_update</userinput>
----
- - 1306964594.980
-...
-tarantool> <userinput>box.info.snapshot_pid</userinput>
----
- - 0
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
-</variablelist>
-
-<variablelist>
- <title>Package <code>box.slab</code></title>
- <para>
- The box.slab package provides access to slab allocator statistics.
- The slab
- allocator is the main allocator used to store tuples.
- This can be used to monitor the total memory use and
- memory fragmentation.
- </para>
- <para>
- The display of slabs is broken down by the slab size --
- 64-byte, 136-byte, and so on. The example omits the slabs
- which are empty. The example display is saying that:
- there are 16 items stored
- in the 64-byte slab (and 16*64=1024 so
- bytes_used = 1024); there is 1 item
- stored in the 136-byte slab (and
- 136*1=136 so bytes_used = 136); the
- arena_used value is the total of all the bytes_used
- values (1024+136 = 1160); the
- arena_size value is the arena_used value
- plus the total of all the bytes_free values
- (1160+4193200+4194088 = 8388448). The
- arena_size and arena_used values are the amount of
- the % of <olink targetptr="slab_alloc_arena"/> that is
- already distributed to the slab allocator.
- </para>
- <varlistentry>
- <term xml:id="box.slab.info" xreflabel="box.slab.info()">
- <emphasis role="lua">box.slab</emphasis></term>
- <listitem><bridgehead renderas="sect4">Example</bridgehead><programlisting>
-tarantool> <userinput>box.slab.info().arena_used</userinput>
----
- - 4194304
-...
-tarantool> <userinput>box.slab.info().arena_size</userinput>
----
- - 104857600
-...
-tarantool> <userinput>box.slab.info().slabs</userinput>
----
-- - {mem_free: 9320, mem_used: 6976, 'item_count': 109, 'item_size': 64, 'slab_count': 1,
- 'slab_size': 16384}
- - {mem_free: 16224, mem_used: 72, 'item_count': 1, 'item_size': 72, 'slab_count': 1,
- 'slab_size': 16384}
- etc.
-...
-tarantool> <userinput>box.slab.info().slabs[1]</userinput>
----
-- {mem_free: 9320, mem_used: 6976, 'item_count': 109, 'item_size': 64, 'slab_count': 1,
- 'slab_size': 16384}
-...
-</programlisting></listitem>
- </varlistentry>
-</variablelist>
-
-<variablelist>
- <title>Package <code>box.stat</code></title>
- <para>
- The box.stat package provides access to request
- statistics. Show the average number of requests per second, and the
- total number of requests since startup, broken down by
- request type.
- </para>
- <varlistentry>
- <term xml:id="box.stat" xreflabel="box.stat">
- <emphasis role="lua">box.stat</emphasis></term>
- <listitem><bridgehead renderas="sect4">Example</bridgehead><programlisting>
-tarantool> <userinput>box.stat, type(box.stat) -- a virtual table</userinput>
----
-- []
-- table
-...
-tarantool> <userinput>box.stat() -- the full contents of the table</userinput>
----
-- DELETE:
- total: 48902544
- rps: 147
- EVAL:
- total: 0
- rps: 0
- SELECT:
- total: 388322317
- rps: 1246
- REPLACE:
- total: 4
- rps: 0
- INSERT:
- total: 48207694
- rps: 139
- AUTH:
- total: 0
- rps: 0
- CALL:
- total: 8
- rps: 0
- UPDATE:
- total: 743350520
- rps: 1874
-...
-tarantool> <userinput>box.stat().DELETE -- a selected item of the table</userinput>
----
-- total: 48902544
- rps: 0
-...
-</programlisting></listitem>
- </varlistentry>
-</variablelist>
-
-<para>
- Additional examples can be found in the open source <link
- xlink:href="https://github.com/mailru/tntlua">Lua stored
- procedures repository</link> and in the server test suite.
-</para>
-</section>
-
-<section xml:id="sp-net-box">
- <title>Package <code>net.box</code> — working with networked Tarantool peers</title>
- <para>
- The <code>net.box</code> package contains connectors to remote database systems.
- One variant, <code>box.net.sql</code>, is for connecting to MySQL or MariaDB or PostgreSQL
- — that variant is the subject of the <olink targetptr="plugins"><quote>SQL DBMS plugins</quote></olink> appendix.
- In this section the subject is the built-in variant, <code>box.net</code>.
- This is for connecting to tarantool servers via a network.
- </para>
-<variablelist xml:id="net.box">
- <para>
- Call <code>require('net.box')</code> to get a net.box object, which will be called <code>net_box</code>
- for examples in this section.
- Call <code><replaceable>net_box</replaceable>:new()</code> to connect and get a connection object,
- which will be called <code>conn</code> for examples in this section.
- Call the other <code>net.box()</code> routines, passing <code>conn:</code>,
- to execute requests on the remote box.
- Call <code>conn:close</code> to disconnect.
- </para>
-
- <para>
- All <code>net.box</code> methods are fiber-safe, that is, it is
- safe to share and use the same connection object across
- multiple concurrent fibers. In fact, it's perhaps the
- best programming practice with Tarantool. When multiple
- fibers use the same connection, all requests are pipelined
- through the same network socket, but each fiber gets back a
- correct response. Reducing the number of active sockets
- lowers the overhead of system calls and increases the
- overall server performance. There are, however, cases when
- a single connection is not enough — for example when it's necessary to
- prioritize requests or to use different authentication ids.
- </para>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="net.box.new">
- conn = <replaceable>net_box</replaceable>:new(<replaceable>host</replaceable>, <replaceable>port</replaceable> [, {<replaceable>other parameter[s]</replaceable>}])</emphasis>
- </term>
- <listitem>
- <para>
- Create a new connection. The connection is
- established on demand, at the time of the first
- request. It is re-established automatically after
- a disconnect.
- The returned <code>conn</code> object supports methods for making remote
- requests, such as select, update or delete.
- </para>
- <para>
- For the local tarantool server there is a pre-created always-established
- connection object named <code><replaceable>net_box</replaceable>.self</code>.
- Its purpose is to make polymorphic use of the
- <code>net.box</code> API easier. Therefore
- <code>conn = <replaceable>net_box</replaceable>:new('localhost', 3301)</code> can
- be replaced by <code>conn = <replaceable>net.box</replaceable>.self</code>.
- However, there is an important difference between the embedded
- connection and a remote one. With the embedded connection,
- requests which do not modify data do not yield. When using
- a remote connection, any request can yield, and local database state may
- have changed by the time it returns.
- </para>
- <para>
- Parameters: <code>host</code>, <code>port</code>, <code>wait_connect</code>, <code>user</code>, <code>password</code>.
- </para>
- <para>
- Returns: (type = userdata) conn object).
- </para>
- <para>
- Examples: <code><userinput>conn = net_box:new('localhost', 3301)</userinput></code>,
- <code><userinput>conn = net_box:new('127.0.0.1', box.cfg.listen, {wait_connect = false, user = 'guest', password = ''})</userinput></code>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="net.box.ping">
- <replaceable>conn</replaceable>:ping()</emphasis></term>
- <listitem>
- <para>
- Execute a PING command.
- </para>
- <para>
- Returns: (type = boolean) <code>true</code> on success,
- <code>false</code> on error. Example: <code><userinput>net_box.self:ping()</userinput></code>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="net.box.wait_connected">
- <replaceable>conn</replaceable>:wait_connected([<replaceable>timeout</replaceable>])</emphasis></term>
- <listitem>
- <para>
- Wait for connection to be active or closed.
- </para>
- <para>
- Returns: (type = boolean) <code>true</code> when connected,
- <code>false</code> on failure. Example: <code><userinput>net_box.self:wait_connected()</userinput></code>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="net.box.close">
- <replaceable>conn</replaceable>:close()</emphasis></term>
- <listitem>
- <para>
- Close a connection.
- </para>
- <para>
- Connection objects are garbage collected just like any other objects
- in Lua, so an explicit destruction is not mandatory.
- However, since <code>close()</code> is a system call, it
- is good programming practice to close a connection
- explicitly when it is no longer needed, to avoid lengthy
- stalls of the garbage collector.
- </para>
- <para>
- Example: <code><userinput>conn:close()</userinput></code>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="net.box.select">
- <replaceable>conn</replaceable>.space.<replaceable>space-name</replaceable>:select{<replaceable>field-value</replaceable>, ...}</emphasis></term>
- <listitem>
- <para>
- <code>conn.space.<replaceable>space-name</replaceable>:select{...}</code> is the remote-call equivalent of the local call
- <code xlink:href="#box.select">box.space.<replaceable>space-name</replaceable>:select{...}</code>.
- Please note this difference: a local <code>box.space.<replaceable>space-name</replaceable>:select{...}</code> does not yield,
- but a remote <code>conn.space.<replaceable>space-name</replaceable>:select{...}</code> call does yield,
- so local data may change while a remote <code>conn.space.<replaceable>space-name</replaceable>:select{...}</code> is running.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="net.box.insert">
- <replaceable>conn</replaceable>.space.<replaceable>space-name</replaceable>:insert{field-value, ...}</emphasis></term>
- <listitem>
- <para>
- <code>conn.space.<replaceable>space-name</replaceable>:insert(...)</code> is the remote-call equivalent of the local call
- <code xlink:href="#box.insert">box.space.<replaceable>space-name</replaceable>:insert(...)</code>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="net.box.replace">
- <replaceable>conn</replaceable>.space.<replaceable>space-name</replaceable>:replace{field-value, ...}</emphasis></term>
- <listitem>
- <para>
- <code>conn.space.<replaceable>space-name</replaceable>:replace(...)</code> is the remote-call equivalent of the local call
- <code xlink:href="#box.replace">box.space.<replaceable>space-name</replaceable>:replace(...)</code>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="net.box.update">
- <replaceable>conn</replaceable>.space.<replaceable>space-name</replaceable>:update(<replaceable>key</replaceable>, <replaceable>format</replaceable>, ...)</emphasis></term>
- <listitem>
- <para>
- <code>conn.space.<replaceable>space-name</replaceable>:update(...)</code> is the remote-call equivalent of the local call
- <code xlink:href="#box.update">box.space.<replaceable>space-name</replaceable>:update(...)</code>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="net.box.delete">
- <replaceable>conn</replaceable>.space.<replaceable>space-name</replaceable>:delete{key}</emphasis></term>
- <listitem>
- <para>
- <code>conn.space.<replaceable>space-name</replaceable>:delete{...}</code> is the remote-call equivalent of the local call
- <code xlink:href="#box.delete">box.space.<replaceable>space-name</replaceable>:delete{...}</code>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="net.box.call">
- <replaceable>conn</replaceable>:call(<replaceable>function-name</replaceable> [, <replaceable>arguments</replaceable>])</emphasis></term>
- <listitem>
- <para>
- <code>conn:call('func', '1', '2', '3')</code> is the remote-call equivalent of <code>func('1', '2', '3')</code>.
- That is, conn:call is a remote stored-procedure call.
- </para>
- <para>
- Example: <code><userinput>conn:call('function5')</userinput></code>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="net.box.timeout">
- <replaceable>conn</replaceable>:timeout(<replaceable>timeout</replaceable>)</emphasis></term>
- <listitem>
- <para>
- <code>timeout(...)</code> is a wrapper which sets a timeout for the request that follows it.
- Example: <code>conn:timeout(0.5).space.tester:update({1}, {{'=', 2, 15}})</code>.
- </para>
- <para>
- All remote calls support execution timeouts.
- Using a wrapper object makes the remote
- connection API compatible with the local one, removing
- the need for a separate <code>timeout</code> argument, which
- the local version would ignore. Once a request is sent,
- it cannot be revoked from the remote server even if
- a timeout expires: the timeout expiration only aborts the
- wait for the remote server response, not the request itself.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
- <bridgehead renderas="sect4">Example showing use of most of the net.box methods</bridgehead>
- <para>
- This example will work with the sandbox configuration described in the preface.
- That is, there is a space named tester with a numeric primary key.
- Assume that the database is nearly empty.
- Assume that the tarantool server is running on localhost 127.0.0.1:3301.
-<programlisting>
-<prompt>tarantool></prompt><userinput> box.schema.user.grant('guest', 'read,write,execute', 'universe')</userinput>
----
-...
-<prompt>tarantool></prompt><userinput> console = require('console'); console.delimiter('!')</userinput>
----
-...
-<prompt>tarantool></prompt><userinput> net_box = require('net.box')!</userinput>
----
-...
-<prompt>tarantool></prompt><userinput> function example()</userinput>
-<prompt> ></prompt><userinput> if net_box.self:ping() then</userinput>
-<prompt> ></prompt><userinput> table.insert(ta, 'self:ping() succeeded')</userinput>
-<prompt> ></prompt><userinput> table.insert(ta, ' (no surprise -- self connection is pre-established)')</userinput>
-<prompt> ></prompt><userinput> end</userinput>
-<prompt> ></prompt><userinput> if box.cfg.listen == '3301' then</userinput>
-<prompt> ></prompt><userinput> table.insert(ta,'The local server listen address = 3301')</userinput>
-<prompt> ></prompt><userinput> else</userinput>
-<prompt> ></prompt><userinput> table.insert(ta, 'The local server listen address is not 3301')</userinput>
-<prompt> ></prompt><userinput> table.insert(ta, '( (maybe box.cfg{...listen="3301"...} was not stated)')</userinput>
-<prompt> ></prompt><userinput> table.insert(ta, '( (so connect will fail)')</userinput>
-<prompt> ></prompt><userinput> end</userinput>
-<prompt> ></prompt><userinput> conn = net_box:new('127.0.0.1', 3301)</userinput>
-<prompt> ></prompt><userinput> conn.space.tester:delete{800}</userinput>
-<prompt> ></prompt><userinput> table.insert(ta, 'conn delete done on tester.')</userinput>
-<prompt> ></prompt><userinput> conn.space.tester:insert{800, 'data'}</userinput>
-<prompt> ></prompt><userinput> table.insert(ta, 'conn insert done on tester, index 0')</userinput>
-<prompt> ></prompt><userinput> table.insert(ta, ' primary key value = 800.')</userinput>
-<prompt> ></prompt><userinput> wtuple = conn.space.tester:select{800}</userinput>
-<prompt> ></prompt><userinput> table.insert(ta, 'conn select done on tester, index 0')</userinput>
-<prompt> ></prompt><userinput> table.insert(ta, ' number of fields = ' .. #wtuple)</userinput>
-<prompt> ></prompt><userinput> conn.space.tester:delete{800}</userinput>
-<prompt> ></prompt><userinput> table.insert(ta, 'conn delete done on tester')</userinput>
-<prompt> ></prompt><userinput> conn.space.tester:replace{800, 'New data', 'Extra data'}</userinput>
-<prompt> ></prompt><userinput> table.insert(ta, 'conn:replace done on tester')</userinput>
-<prompt> ></prompt><userinput> conn:timeout(0.5).space.tester:update({800}, {{'=', 2, 'Fld#1'}})</userinput>
-<prompt> ></prompt><userinput> table.insert(ta, 'conn update done on tester')</userinput>
-<prompt> ></prompt><userinput> conn:close()</userinput>
-<prompt> ></prompt><userinput> table.insert(ta, 'conn close done')</userinput>
-<prompt> ></prompt><userinput> end!</userinput>
----
-...
-<prompt>tarantool></prompt><userinput> console.delimiter('')!</userinput>
----
-...
-<prompt>tarantool></prompt><userinput> ta = {}</userinput>
----
-...
-<prompt>tarantool></prompt><userinput> example()</userinput>
----
-...
-<prompt>tarantool></prompt><userinput> ta</userinput>
----
-- - self:ping() succeeded
- - ' (no surprise -- self connection is pre-established)'
- - The local server listen address = 3301
- - conn delete done on tester.
- - conn insert done on tester, index 0
- - ' primary key value = 800.'
- - conn select done on tester, index 0
- - ' number of fields = 1'
- - conn delete done on tester
- - conn:replace done on tester
- - conn update done on tester
- - conn close done
-...
-<prompt>tarantool></prompt><userinput> box.space.tester:select{800} -- Prove that the update succeeded.</userinput>
----
-- [800, 'Fld#1', 'Extra data']
-...
-</programlisting>
-</para>
-</section>
-
-
-<section xml:id="administrative-requests">
- <title>Administrative requests</title>
- <para>To learn which functions are considered to be administrative,
- type <emphasis role="lua">help()</emphasis>.
- A reference description also follows
- below:</para>
-
- <variablelist>
-
- <varlistentry>
- <term xml:id="box.snapshot" xreflabel="box.snapshot()">
- <emphasis role="lua">box.snapshot()</emphasis>
- </term>
- <listitem><para>
- Take a snapshot of all data and store it in
- <filename><olink
- targetptr="snap_dir"/>/<latest-lsn>.snap</filename>.
- To take a snapshot, Tarantool first enters the delayed
- garbage collection mode for all data. In this mode,
- tuples which were allocated before the snapshot has
- started are not freed until the snapshot has finished.
- To preserve consistency of the primary key, used to
- iterate over tuples, a copy-on-write technique is employed.
- If the master process changes part of a primary key,
- the corresponding process page is split, and the snapshot
- process obtains an old copy of the page. Since a
- snapshot is written sequentially, one can expect a very
- high write performance (averaging to 80MB/second on modern
- disks), which means an average database instance gets
- saved in a matter of minutes. Note, that as long as there
- are any changes to the parent index memory through concurrent
- updates, there are going to be page splits, and therefore
- one needs to have some extra free memory to run this
- command. 10% of <olink targetptr="slab_alloc_arena"/>
- is, on average, sufficient. This statement waits until a
- snapshot is taken and returns operation result. For
- example:
-<programlisting>tarantool> <userinput>box.info.version</userinput>
----
-- 1.6.3-439-g7e1011b
-...
-tarantool> <userinput>box.snapshot()</userinput>
----
-- ok
-...
-tarantool> <userinput>box.snapshot()</userinput>
----
-error: can't save snapshot, errno 17 (File exists)
-...
-</programlisting>
- </para>
- <para>
- Taking a snapshot does not cause the server to start a new
- write-ahead log. Once a snapshot is taken, old WALs can be
- deleted as long as all replicas are up to date. But the
- WAL which was current at the time <emphasis
- role="lua">box.snapshot()</emphasis> started must be
- kept for recovery, since it still contains log records
- written after the start of <emphasis role="lua">
- box.snapshot()</emphasis>.
- </para>
- <para>
- An alternative way to save a snapshot is to send the server
- SIGUSR1 UNIX signal. While this approach could be handy, it
- is not recommended for use in automation: a signal provides no
- way to find out whether the snapshot was taken successfully
- or not.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="coredump" xreflabel="coredump()">
- <emphasis role="lua">coredump()</emphasis>
- </term>
- <listitem><para>
- Fork and dump a core. Since Tarantool stores all tuples
- in memory, it can take some time. Mainly useful for
- debugging.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="fiber.info" xreflabel="fiber.info">
- <emphasis role="lua">require('fiber').info()</emphasis>
- </term>
- <listitem><para>
- Show all running fibers, with their stack.
- Mainly useful for debugging.
- </para></listitem>
- </varlistentry>
-
- </variablelist>
-
-</section>
-
-
-<section xml:id="multitasking">
-<title>Atomic execution</title>
-
-<para>
- In several places it's been noted that Lua processes occur in
- fibers on a single thread. That is why there
- can be a guarantee of execution atomicity. That requires emphasis.
-</para>
-<bridgehead renderas="sect4">Cooperative multitasking environment</bridgehead>
-<para>
- Tarantool core is built around a cooperative multi-tasking
- paradigm: unless a running fiber deliberately yields control
- to some other fiber, it is not preempted.
- <quote>Yield points</quote> are built into all
- calls from Tarantool core to the operating system.
- Any system call which can block is performed in an
- asynchronous manner and the fiber waiting
- on the system call is preempted with a fiber ready to
- run. This model makes all programmatic locks unnecessary:
- cooperative multitasking ensures that there is no concurrency
- around a resource, no race conditions and no memory
- consistency issues.
-</para>
-<para>
- When requests are small, e.g. simple UPDATE, INSERT, DELETE,
- SELECT, fiber scheduling is fair: it takes only a little time
- to process the request, schedule a disk write, and yield to
- a fiber serving the next client.
-</para>
-<para>
- A function, however, can perform complex computations,
- or be written in such a way that control is not given away for a
- long time. This can lead to unfair scheduling, when a single
- client throttles the rest of the system, or to apparent stalls
- in request processing.
- Avoiding this situation is the responsibility of the function's
- author. Most of the <code>box</code> calls, such as
- <code>box.space...insert</code>, <code>box.space...update</code>,
- <code>box.space...delete</code> are yield points;
- <code>box.space...select</code>, however, is not.
-</para>
-<para>
- It should also be noted that, in the absence of transactions,
- any yield in a function is a potential change in the
- database state. Effectively, it's only possible
- to have CAS (compare-and-swap) -like atomic stored
- procedures: i.e. functions which select and then modify a record.
- Multiple data change requests always run through a built-in
- yield point.
-</para>
-<para>
- At this point an objection could arise: "It's good that a single
- data-change request will commit and yield, but surely there are
- times when multiple data-change requests must happen without
- yielding." The standard example is the money-transfer, where
- $1 is withdrawn from account #1 and deposited into account #2.
- If something interrupted after the withdrawal, then the
- institution would be out of balance. For such cases, the
- <code>begin ... commit|rollback</code> block was designed.
-</para>
- <variablelist>
- <varlistentry>
- <term xml:id="begin" xreflabel="begin()">
- <emphasis role="lua">box.begin()</emphasis>
- </term>
- <listitem><para>
- From this point, implicit yields are suspended.
- In effect the fiber which executes <code>box.begin()</code>
- is starting an "active multi-request transaction", blocking all
- other fibers until the transaction ends.
- All operations within this transaction should use the same storage engine.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="commit" xreflabel="commit()">
- <emphasis role="lua">box.commit()</emphasis>
- </term>
- <listitem><para>
- End the currently active transaction, and make
- all its data-change operations permanent.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="rollback" xreflabel="rollback()">
- <emphasis role="lua">box.rollback()</emphasis>
- </term>
- <listitem><para>
- End the currently active transaction, but cancel
- all its data-change operations. An explicit call
- to functions outside box.space that always yield,
- such as <code>fiber.yield</code> or
- <code>fiber.sleep</code>, will have the same effect.
- </para></listitem>
- </varlistentry>
- </variablelist>
-<para>
- <emphasis>The requests in a transaction must be
- sent to the server as a single block.</emphasis>
- It is not enough to enclose them
- between <code>begin</code> and <code>commit</code>
- or <code>rollback</code>. To ensure they are sent
- as a single block: put them in a function, or put
- them all on one line, or use a delimiter so that
- multi-line requests are handled together.
-</para>
-
-<para>
-Example:
-Assuming that in tuple set 'tester' there are tuples
-in which the third field represents a positive dollar amount ...
-Start a transaction, withdraw from tuple#1, deposit in tuple#2,
-and end the transaction, making its effects permanent.<programlisting>
-console = require('console'); console.delimiter('!')
-box.begin()
-amount_of_money = 1.00
-box.space.tester:update({999}, {{'-', 3, amount_of_money}})
-box.space.tester:update({1000}, {{'+', 3, amount_of_money}})
-box.commit()
-console.delimiter('')!</programlisting>
-</para>
-</section>
-
-
-<section xml:id="authentication" xreflabel="authentication">
-<title>Authentication and access control</title>
-
-<para>
-Understanding the details of security is primarily an issue for administrators,
-but ordinary users should at least skim this section so that they will have an
-idea of how Tarantool makes it possible for administrators to prevent
-unauthorized access to the database and to certain functions.
-</para>
-
-
-<para>
-Briefly: there is a method to guarantee with password checks that users really
-are who they say they are ("authentication"). There is a _user space where
-user names and password-hashes are stored. There are functions for saying
-that certain users are allowed to do certain things ("privileges"). There
-is a _priv space where privileges are stored. Whenever a user tries to do
-an operation, there is a check whether the user has the privilege to do
-the operation ("access control").
-</para>
-
-<para>
-<bridgehead renderas="sect4">Passwords</bridgehead>
-Each user may have a password.
-The password is any alphanumeric string.
-Administrators should advise users to choose long unobvious passwords,
-but it is ultimately up to the users to choose or change
-their own passwords.
-</para>
-
-<para>
-Tarantool passwords are stored in the _user space with a
-<link xlink:href="https://en.wikipedia.org/wiki/Cryptographic_hash">Cryptographic hash function</link>
-so that, if the password is 'x', the stored hashed-password is a long string like
-'lL3OvhkIPOKh+Vn9Avlkx69M/Ck='.
-When a client connects to a Tarantool server, the server sends a random
-<link xlink:href="https://en.wikipedia.org/wiki/Salt_%28cryptography%29">Salt Value</link>
-which the client must mix with the hashed-password before sending
-to the server.
-Thus the original value 'x' is never stored anywhere except in the
-user's head, and the hashed value is never passed down a
-network wire except when mixed with a random salt.
-This system prevents malicious onlookers from finding passwords
-by snooping in the log files or snooping on the wire.
-It is the same system that <link xlink:href="http://dev.mysql.com/doc/refman/4.1/en/password-hashing.html">MySQL introduced several years ago</link>
-which has proved adequate for medium-security installations.
-Nevertheless administrators should warn users that no system
-is foolproof against determined long-term attacks, so passwords
-should be guarded and changed occasionally.
-</para>
-
-<para>
-Notes: To get the hash-password of a string 'X', say <code>box.schema.user.password('X')</code>.
-To see more about the details of the algorithm for the purpose of writing a new client application, read
-<link xlink:href="https://github.com/tarantool/tarantool/blob/master/src/scramble.h">the scramble.h header file</link>.
-</para>
-
-<para>
-<bridgehead renderas="sect4">Users and the _user space</bridgehead>
-The fields in the _user space are:
-the numeric id of the tuple, the numeric id of the tuple's creator, the user name, the type, and the optional password.
-</para>
-
-<para>
-There are three special tuples in the _user space: 'guest', 'admin', and 'public'.
-</para>
-
-
- <table>
- <title>The system users</title>
- <tgroup cols="4" align="left" colsep="1" rowsep="1">
- <tbody>
- <row>
- <entry>NAME</entry><entry>ID</entry><entry>TYPE</entry><entry>DESCRIPTION</entry>
- </row>
- <row>
- <entry>guest</entry><entry>0</entry><entry>user</entry><entry>Default when connecting remotely. Usually an untrusted user with few privileges.</entry>
- </row>
- <row>
- <entry>admin</entry><entry>1</entry><entry>user</entry><entry>Default when using <code>tarantool</code> as a console. Usually an administrative user with all privileges.</entry>
- </row>
- <row>
- <entry>public</entry><entry>2</entry><entry>role</entry><entry>Not a user in the usual sense. Described later in section <link linkend="roles">Roles</link>. </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
-
-<para>
-To select a row from the _user space, use <code>box.select</code>.
-For example, here is what happens with a select for user id = 0,
-which is the 'guest' user, which by default has no password:
-<programlisting><prompt>tarantool></prompt> <userinput>box.space._user:select{0}</userinput>
----
-- - [0, 1, 'guest', 'user']
-...</programlisting></para>
-
-<para>
-To change tuples in the user space, do not use ordinary <code>box.space</code> functions
-for insert or update or delete -- the _user space is special so
-there are special functions which have appropriate error checking.
-</para>
-
-<para>
-To create a new user, say
-<code>box.schema.user.create(<replaceable>user-name</replaceable>)</code>
-or
-<code>box.schema.user.create(<replaceable>user-name</replaceable>, {password=<replaceable>password</replaceable>})</code>.
-The form
-<code>box.schema.user.create(<replaceable>user-name</replaceable>, {password=<replaceable>password</replaceable>})</code>
-is better because in a <link linkend="URI">URI</link> (Uniform Resource Identifier) it is usually illegal to include a user-name without a password.
-</para>
-
-<para>
-To change the current user's password, say
-<code>box.schema.user.passwd(<replaceable>password</replaceable>)</code>.
-</para>
-
-<para>
-To change a different user's password, say
-<code>box.schema.user.passwd(<replaceable>user-name</replaceable>, <replaceable>password</replaceable>)</code>.
-(Only the admin user can perform this function.)
-</para>
-
-<para>
-To drop a user, say
-<code>box.schema.user.drop(<replaceable>user-name</replaceable>)</code>.
-</para>
-
-<para>
-To check whether a user exists, say
-<code>box.schema.user.exists(<replaceable>user-name</replaceable>)</code>,
-which returns <code>true</code> or <code>false</code>.
-</para>
-
-<para>
-For example, here is a session which creates a new user with
-a strong password, selects a tuple in
-the _user space, and then drops the user.
-<programlisting><prompt>tarantool></prompt> <userinput>box.schema.user.create('JeanMartin', {password = 'Iwtso_6_os$$'})</userinput>
----
-...
-
-<prompt>tarantool></prompt> <userinput>box.space._user.index.name:select{'JeanMartin'}</userinput>
----
-- - [17, 1, 'JeanMartin', 'user', {'chap-sha1': 't3xjUpQdrt857O+YRvGbMY5py8Q='}]
-...
-
-<prompt>tarantool></prompt> <userinput>box.schema.user.drop('JeanMartin')</userinput>
----
-...</programlisting></para>
-
-<para>
-Notes: The maximum number of users is 32.
-</para>
-
-<para>
-<bridgehead renderas="sect4">Privileges and the _priv space</bridgehead>
-The fields in the _priv space are:
-the numeric id of the user who gave the privilege ("grantor_id"),
-the numeric id of the user who received the privilege ("grantee_id"),
-the id of the object,
-the type of object -- "space" or "function" or "universe",
-the type of operation -- "read" or "write" or "execute" or a combination such as "read,write,execute".
-</para>
-
-<para>
-The function for granting a privilege is:
-<code>box.schema.user.grant(<replaceable>user-name-of-grantee</replaceable>, <replaceable>operation-type</replaceable>, <replaceable>object-type</replaceable>, <replaceable>object-name</replaceable>)</code>
-or
-<code>box.schema.user.grant(<replaceable>user-name-of-grantee</replaceable>, <replaceable>operation-type</replaceable>, 'universe')</code>.
-</para>
-
-<para>
-The function for revoking a privilege is:
-<code>box.schema.user.revoke(<replaceable>user-name-of-grantee</replaceable>, <replaceable>operation-type</replaceable>, <replaceable>object-type</replaceable>, <replaceable>object-name</replaceable>)</code>
-or
-<code>box.schema.user.revoke(<replaceable>user-name-of-grantee</replaceable>, <replaceable>operation-type</replaceable>, 'universe')</code>.</para>
-
-<para>
-For example, here is a session where the admin user gave
-the guest user the privilege to read from a
-space named space55, and then took the privilege away:
-<programlisting><prompt>tarantool></prompt> <userinput>box.schema.user.grant('guest', 'read', 'space', 'space55')</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>box.schema.user.revoke('guest', 'read', 'space', 'space55')</userinput>
----
-...</programlisting></para>
-
-<para>
-Notes: Generally privileges are granted or revoked by the owner of the object
-(the user who created it), or by the 'admin' user.
-Before dropping any objects or users, steps should be taken to ensure
-that all their associated privileges have been revoked.
-Only the 'admin' user can grant privileges for the 'universe'.
-</para>
-
-<para>
-<bridgehead renderas="sect4">Functions and the _func space</bridgehead>
-The fields in the _func space are:
-the numeric function id, a number, and the function name.
-</para>
-
-<para>
-The _func space does not include the function's body.
-One continues to create Lua functions in the usual way,
-by saying "<code>function <replaceable>function_name</replaceable> () ... end</code>", without
-adding anything in the _func space. The _func space only
-exists for storing function tuples so that their names
-can be used within grant/revoke functions.
-</para>
-
-<para>
-The function for creating a _func tuple is:
-<code>box.schema.func.create(<replaceable>function-name</replaceable>)</code>.
-</para>
-
-<para>
-The function for dropping a _func tuple is:
-<code>box.schema.func.drop(<replaceable>function-name</replaceable>)</code>.
-</para>
-
-<para>
-The function for checking whether a _func tuple exists is:
-<code>box.schema.func.exists(<replaceable>function-name</replaceable>)</code>.
-</para>
-
-<para>
-In the following example, a function named 'f7' is created,
-then it is put in the _func space, then it is used in a
-box.schema.user.grant function, then it is dropped:
-<programlisting><prompt>tarantool></prompt> <userinput>function f7() box.session.uid() end</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>box.schema.func.create('f7')</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>box.schema.user.grant('guest', 'execute', 'function', 'f7')</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>box.schema.user.revoke('guest', 'execute', 'function', 'f7')</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>box.schema.func.drop('f7')</userinput>
----
-...</programlisting></para>
-
-<para>
-<bridgehead renderas="sect4">"box.session" and security</bridgehead>
-
-After a connection has taken place, the user has access to a "session" object
-which has several functions. The ones which are of interest for security
-purposes are:
-<programlisting>box.session.uid() #returns the id of the current user
-box.session.user() #returns the name of the current user
-box.session.su(<replaceable>user-name</replaceable>) #allows changing current user to 'user-name'</programlisting></para>
-
-<para>
-If a user types requests directly on the Tarantool server in its interactive mode,
-or if a user connects via telnet to the administrative port (using
-<olink targetptr="admin_port">admin</olink> instead of listen), then the user by default is 'admin' and has
-many privileges. If a user connects from an application program via one of the
-<olink targetptr="connectors">connectors</olink>, then the user by default is 'guest' and has few
-privileges. Typically an admin user will set up and configure objects, then
-grant privileges to appropriate non-admin users. Typically a guest user will
-use <code>box.session.su()</code> to change into a non-generic user to whom admin
-has granted more than the default privileges. For example, admin might say:<programlisting>
-box.space._user:insert{123456,0,'manager'}
-box.schema.user.grant('manager', 'read', 'space', '_space')
-box.schema.user.grant('manager', 'read', 'space', 'payroll')</programlisting>
-and later a guest user, who wishes to see the payroll, might say:<programlisting>
-box.session.su('manager')
-box.space.payroll:select{'Jones'}</programlisting>
-</para>
-
-<para xml:id="roles">
-<bridgehead renderas="sect4">Roles</bridgehead>
-A role is a container for privileges which can be granted to regular users.
-Instead of granting and revoking individual privileges, one can put all the
-privileges in a role and then grant or revoke the role.
-Role information is in the _user space but the third field -- the type field -- is 'role' rather than 'user'.
-</para>
-
-<para>
-If a role R1 is granted a privilege X, and user U1 is granted a privilege "role R1",
-then user U1 in effect has privilege X.
-Then if a role R2 is granted a privilege Y, and role R1 is granted a privilege "role R2",
-then user U1 in effect has both privilege X and privilege Y.
-In other words, a user gets all the privileges that are granted to a user's roles,
-directly or indirectly.
-</para>
-
-<variablelist>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="role-1">box.schema.role.create(<replaceable>role-name</replaceable>)</emphasis></term>
- <listitem><para>
- Create a new role.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="role-2">box.schema.role.grant(<replaceable>role-name</replaceable>, <replaceable>privilege</replaceable>)</emphasis></term>
- <listitem><para>
- Put a privilege in a role.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="role-3">box.schema.role.revoke(<replaceable>role-name</replaceable>, <replaceable>privilege</replaceable>)</emphasis></term>
- <listitem><para>
- Take a privilege out of a role.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="role-4">box.schema.user.drop(<replaceable>role-name</replaceable>)</emphasis></term>
- <listitem><para>Drop a role.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="role-5">box.schema.role.info()</emphasis></term>
- <listitem><para>Get information about a role.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="role-6">box.schema.user.grant(<replaceable>user-name</replaceable>, 'execute', 'role', <replaceable>role-name</replaceable>)</emphasis></term>
- <listitem><para>Grant a role to a user.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="role-7">box.schema.role.grant(<replaceable>role-name</replaceable>, 'execute', 'role', <replaceable>role-name</replaceable>)</emphasis></term>
- <listitem><para>Grant a role to a role.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="role-8">box.schema.user.revoke(<replaceable>user-name</replaceable>, 'execute', 'role', <replaceable>role-name</replaceable>)</emphasis></term>
- <listitem><para>Revoke a role from a user.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="role-9">box.schema.role.revoke(<replaceable>role-name</replaceable>, 'execute', 'role', <replaceable>role-name</replaceable>)</emphasis></term>
- <listitem><para>Revoke a role from a role.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua" xml:id="role-a">box.schema.role.exists(<replaceable>role-name</replaceable>)</emphasis></term>
- <listitem><para>Check whether a role exists. Returns (type = boolean) <code>true</code> if role-name identifies a role, otherwise <code>false</code>.
- </para></listitem>
- </varlistentry>
-
-</variablelist>
-
-<para>
-There is one predefined role, named 'public', which is automatically assigned to
-new users when they are created with <code>box.schema.user.create(<replaceable>user-name</replaceable>)</code>.
-Therefore a convenient way to grant 'read' on space 't' to every user that will ever exist is:
-<code>box.schema.role.grant('public','read','space','t')</code>.
-</para>
-
-<para>
-<bridgehead renderas="sect4">Example showing a role within a role</bridgehead>
-In this example, a new user named U1 will insert a new tuple into
-a new space named T, and will succeed even though user U1 has no
-direct privilege to do such an insert -- that privilege is inherited
-from role R1, which in turn inherits from role R2.
-<programlisting>
--- This example will work for a user with many privileges, such as 'admin'
-box.schema.space.create('T')
-box.space.T:create_index('primary',{})
--- Create a user U1 so that later it's possible to say box.session.su('U1')
-box.schema.user.create('U1')
--- Create two roles, R1 and R2
-box.schema.role.create('R1')
-box.schema.role.create('R2')
--- Grant role R2 to role R1 and role R1 to U1 (order doesn't matter)
-box.schema.role.grant('R1','execute','role','R2')
-box.schema.role.grant('U1','execute','role','R1')
--- Grant read and execute privileges to R2 (but not to R1 and not to U1)
-box.schema.role.grant('R2','read,write','space','T')
-box.schema.role.grant('R2','execute','universe')
--- Use box.session.su to say "now become user U1"
-box.session.su('U1')
--- The following insert succeeds because U1 in effect has write privilege on T
-box.space.T:insert{1}
-</programlisting>
-</para>
-
-</section>
-
-<section xml:id="limitations">
-
-<title>Limitations</title>
-
-<variablelist>
-
- <varlistentry>
- <term xml:id="limitations-index-field-count" xreflabel="limitations-index-field-count">Number of fields in an index</term>
- <listitem><para>For BITSET indexes, the maximum is 1.
- For TREE or HASH indexes, the maximum is 255 (box.schema.INDEX_PART_MAX).
- For RTREE indexes, the number of fields must be either 2 or 4.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="limitations-index-count" xreflabel="limitations-index-count">Number of indexes in a space</term>
- <listitem><para>10 (box.schema.INDEX_MAX).
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="limitations-tuple-field-count" xreflabel="limitations-tuple-field-count">Number of fields in a tuple</term>
- <listitem><para>The theoretical maximum is 2147483647 (box.schema.FIELD_MAX).
- The practical maximum is whatever is specified by the space's <link linkend="box.space.field_count">field_count</link> member,
- or the maximum tuple length.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="limitations-space-count" xreflabel="limitations-space-count">Number of spaces</term>
- <listitem><para>The theoretical maximum is 2147483647 (box.schema.SPACE_MAX).
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="limitations-connections-count" xreflabel="limitations-connections-count">Number of connections</term>
- <listitem><para>The practical limit is the number of file descriptors that one can set with
- the operating system.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="limitations-slab-alloc-arena-size" xreflabel="limitations-slab-alloc-arena-size">Space size</term>
- <listitem><para>The total maximum size for all spaces is in effect set by <olink targetptr="slab_alloc_arena"/>,
- which in turn is limited by the total available memory.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="limitations-update-count" xreflabel="limitations-update-count">Update operations count</term>
- <listitem><para>The maximum number of operations that can be in a single update is 4000 (BOX_UPDATE_OP_CNT_MAX).
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="limitations-user-count" xreflabel="limitations-user-count">Number of users and roles</term>
- <listitem><para>32.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="limitations-name-length" xreflabel="limitations-name-length">Length of an index name or space name or user name</term>
- <listitem><para>32 (box.schema.NAME_MAX).
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="sophia-limitations" xreflabel="sophia-limitations">Limitations which are only applicable for the sophia storage engine</term>
- <listitem><para>
- The maximum number of fields in an index is always 1, that is, multi-part indexes are not supported.
- The maximum number of indexes in a space is always 1, that is, secondary indexes are not supported.
- Indexes must be unique, that is, the options type=HASH or type=RTREE or type=BITSET are not supported.
- Indexes must be unique, that is, the option unique=false is not supported.
- The alter(), len(), and count() functions are not supported.
- </para></listitem>
- </varlistentry>
-
-</variablelist>
-
-</section>
-
-
-</chapter>
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/errcode.xml b/doc/user/errcode.xml
deleted file mode 100644
index 792393d55a434dee2e63b795d6d15068f62eb49a..0000000000000000000000000000000000000000
--- a/doc/user/errcode.xml
+++ /dev/null
@@ -1,97 +0,0 @@
-<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="errcode">
-
-<title>List of error codes</title>
-
-<para>In the current version of the binary protocol, error message,
-which is normally more descriptive than error code,
-is not present in server response. The actual message may contain
-a file name, a detailed reason or operating system error code.
-All such messages, however, are logged in the error log.
-Below follow only general descriptions
-of some popular codes. A complete list of errors can be found in
-file <filename xlink:href="https://github.com/tarantool/tarantool/blob/master/src/errcode.h">errcode.h</filename> in the source tree.
-
-</para>
-<variablelist>
-<title>List of error codes</title>
-
- <varlistentry>
- <term xml:id="ER_NONMASTER" xreflabel="ER_NONMASTER">ER_NONMASTER</term>
- <listitem><para>Can't modify data on a replication slave.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="ER_ILLEGAL_PARAMS" xreflabel="ER_ILLEGAL_PARAMS">ER_ILLEGAL_PARAMS</term>
- <listitem><para>Illegal parameters. Malformed protocol
- message.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="ER_MEMORY_ISSUE" xreflabel="ER_MEMORY_ISSUE">ER_MEMORY_ISSUE</term>
- <listitem><para>Out of memory: <olink targetptr="slab_alloc_arena"/> limit is reached.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="ER_WAL_IO" xreflabel="ER_WAL_IO">ER_WAL_IO</term>
- <listitem><para>Failed to write to disk. May mean: failed to record a change in
- the write-ahead log. Some sort of disk error.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="ER_KEY_PART_COUNT" xreflabel="ER_KEY_PART_COUNT">ER_KEY_PART_COUNT</term>
- <listitem><para>Key part count is not the same as index part count
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="ER_NO_SUCH_SPACE" xreflabel="ER_NO_SUCH_SPACE">ER_NO_SUCH_SPACE</term>
- <listitem><para>Attempt to access a space that does not exist.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="ER_NO_SUCH_INDEX" xreflabel="ER_NO_SUCH_INDEX">ER_NO_SUCH_INDEX</term>
- <listitem><para>The specified index does not exist for the specified space.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="ER_PROC_LUA" xreflabel="ER_PROC_LUA">ER_PROC_LUA</term>
- <listitem><para>An error inside a Lua procedure.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="ER_FIBER_STACK" xreflabel="ER_FIBER_STACK">ER_FIBER_STACK</term>
- <listitem><para>Recursion limit reached when creating a new fiber. This is
- usually an indicator of a bug in a stored procedure, recursively invoking itself
- ad infinitum.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="ER_UPDATE_FIELD" xreflabel="ER_UPDATE_FIELD">ER_UPDATE_FIELD</term>
- <listitem><para>An error occurred during update of a field.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="ER_TUPLE_FOUND" xreflabel="ER_TUPLE_FOUND">ER_TUPLE_FOUND</term>
- <listitem><para>.Duplicate key exists in unique index ...
- </para></listitem>
- </varlistentry>
-
-</variablelist>
-
-</appendix>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/html-highlight.xsl b/doc/user/html-highlight.xsl
deleted file mode 100644
index 02cb8b611b8213911cc5707cdf7f92d3472e0588..0000000000000000000000000000000000000000
--- a/doc/user/html-highlight.xsl
+++ /dev/null
@@ -1,73 +0,0 @@
-<?xml version="1.0" encoding="ASCII"?>
-<!--This file was created automatically by html2xhtml-->
-<!--from the HTML stylesheets.-->
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:d="http://docbook.org/ns/docbook"
-xmlns:xslthl="http://xslthl.sf.net" xmlns="http://www.w3.org/1999/xhtml" exclude-result-prefixes="xslthl d" version="1.0">
-
-<!-- ********************************************************************
- $Id: highlight.xsl 8419 2009-04-29 20:37:52Z kosek $
- ********************************************************************
-
- This file is part of the XSL DocBook Stylesheet distribution.
- See ../README or http://docbook.sf.net/release/xsl/current/ for
- and other information.
-
- ******************************************************************** -->
-
-<xsl:import href="http://docbook.sourceforge.net/release/xsl-ns/current/highlighting/common.xsl"/>
-
-<xsl:template match="xslthl:keyword" mode="xslthl">
- <b class="hl-keyword"><xsl:apply-templates mode="xslthl"/></b>
-</xsl:template>
-
-<xsl:template match="xslthl:string" mode="xslthl">
- <b class="hl-string"><i style="color:red"><xsl:apply-templates mode="xslthl"/></i></b>
-</xsl:template>
-
-<xsl:template match="xslthl:comment" mode="xslthl">
- <i class="hl-comment" style="color: silver"><xsl:apply-templates mode="xslthl"/></i>
-</xsl:template>
-
-<xsl:template match="xslthl:directive" mode="xslthl">
- <span class="hl-directive" style="color: maroon"><xsl:apply-templates mode="xslthl"/></span>
-</xsl:template>
-
-<xsl:template match="xslthl:tag" mode="xslthl">
- <b class="hl-tag" style="color: #000096"><xsl:apply-templates mode="xslthl"/></b>
-</xsl:template>
-
-<xsl:template match="xslthl:attribute" mode="xslthl">
- <span class="hl-attribute" style="color: #F5844C"><xsl:apply-templates mode="xslthl"/></span>
-</xsl:template>
-
-<xsl:template match="xslthl:value" mode="xslthl">
- <span class="hl-value" style="color: #993300"><xsl:apply-templates mode="xslthl"/></span>
-</xsl:template>
-
-<xsl:template match="xslthl:html" mode="xslthl">
- <b><i style="color: red"><xsl:apply-templates mode="xslthl"/></i></b>
-</xsl:template>
-
-<xsl:template match="xslthl:xslt" mode="xslthl">
- <b style="color: #0066FF"><xsl:apply-templates mode="xslthl"/></b>
-</xsl:template>
-
-<!-- Not emitted since XSLTHL 2.0 -->
-<xsl:template match="xslthl:section" mode="xslthl">
- <b><xsl:apply-templates mode="xslthl"/></b>
-</xsl:template>
-
-<xsl:template match="xslthl:number" mode="xslthl">
- <span class="hl-number"><xsl:apply-templates mode="xslthl"/></span>
-</xsl:template>
-
-<xsl:template match="xslthl:annotation" mode="xslthl">
- <i><span class="hl-annotation" style="color: gray"><xsl:apply-templates mode="xslthl"/></span></i>
-</xsl:template>
-
-<!-- Not sure which element will be in final XSLTHL 2.0 -->
-<xsl:template match="xslthl:doccomment|xslthl:doctype" mode="xslthl">
- <b class="hl-tag" style="color: blue"><xsl:apply-templates mode="xslthl"/></b>
-</xsl:template>
-
-</xsl:stylesheet>
diff --git a/doc/user/iterator-types.xml b/doc/user/iterator-types.xml
deleted file mode 100644
index 5704cc65f18e1cfa036d24becd71e239372eedb9..0000000000000000000000000000000000000000
--- a/doc/user/iterator-types.xml
+++ /dev/null
@@ -1,371 +0,0 @@
-<!DOCTYPE para [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<para xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="iterator-types">
-
-
-<table frame='all' pgwide='1'>
-<title>TREE iterator types</title>
-
-<tgroup cols='3' colsep='1' rowsep='1'>
-<colspec colnum='3' colname="Description" colwidth="6*"/>
-
-<thead>
- <row>
- <entry>Type</entry>
- <entry>Arguments</entry>
- <entry>Description</entry>
- </row>
-</thead>
-
-<tbody>
-
- <row>
- <entry>box.index.ALL or 'ALL'</entry>
- <entry>none</entry>
- <entry>
- Iterate over all tuples in an index.
- Tuples are returned in ascending
- order of the key.
- </entry>
- </row>
-
- <row>
- <entry>box.index.EQ or 'EQ'</entry>
- <entry>field values</entry>
- <entry>
- <simpara>
- Equality iterator: iterate over all tuples
- where field values = key values.
- Parts of a multi-part key need to be separated by
- commas.
- </simpara>
- <simpara>
- If the number of field values is less than the
- number of parts of a multi-part key, the
- missing field values are considered to be matching.
- </simpara>
- <simpara>
- If there are multiple matches, then tuples are
- returned in ascending order by key.
- </simpara>
- </entry>
- </row>
-
- <row>
- <entry>box.index.GT or 'GT'</entry>
- <entry>field values</entry>
- <entry>
- Keys match if key values are greater than field values.
- If the number of field values is less than the
- number of parts of a multi-part key, the
- missing field values are considered to be matching.
- If the field value is <code>nil</code>, iteration starts from
- the smallest key in the index. Tuples are returned
- in ascending order by key.
- </entry>
- </row>
-
- <row>
- <entry>box.index.REQ or 'REQ'</entry>
- <entry>field values</entry>
- <entry>
- Reverse equality iterator. Matching is determined
- in the same way as for <code>box.index.EQ</code>,
- but, if there are multiple matches, then tuples
- are returned in descending order by key,
- </entry>
- </row>
-
- <row>
- <entry>box.index.GE or 'GE'</entry>
- <entry>field values</entry>
- <entry>
- Keys match if key values are greater than or equal
- to field values.
- Tuples are returned in ascending order by key.
- If the field value is
- <code>nil</code>, iteration starts from the first
- key in the index.
- </entry>
- </row>
-
- <row>
- <entry>box.index.LT or 'LT'</entry>
- <entry>field values</entry>
- <entry>
- Keys match if key values are less than
- field values.
- Tuples are returned in descending order by key.
- If the field value is
- <code>nil</code>, iteration starts from the last
- key in the index.
- </entry>
- </row>
-
- <row>
- <entry>box.index.LE or 'LE'</entry>
- <entry>field values</entry>
- <entry>
- Keys match if key values are less than or equal
- to field values.
- Tuples are returned in descending order by key.
- If the field value is
- <code>nil</code>, iteration starts from the last
- key in the index.
- </entry>
- </row>
-</tbody>
-</tgroup>
-</table>
-
-
-<table frame='all' pgwide='1'>
-<title>HASH iterator types</title>
-
-<tgroup cols='3' colsep='1' rowsep='1'>
-<colspec colnum='3' colname="Description" colwidth="6*"/>
-
-<thead>
- <row>
- <entry>Type</entry>
- <entry>Arguments</entry>
- <entry>Description</entry>
- </row>
-</thead>
-
-<tbody>
-
- <row>
- <entry>box.index.ALL or 'ALL'</entry>
- <entry>none</entry>
- <entry>
- Iterate over all tuples in an index.
- Tuples are returned in ascending
- order of the key's hash, and so
- will appear to be unordered.
- </entry>
- </row>
-
- <row>
- <entry>box.index.EQ or 'EQ'</entry>
- <entry>field values</entry>
- <entry>
- <simpara>
- Equality iterator: iterate over all tuples matching
- the key.
- Parts of a multi-part key need to be separated by
- commas.
- </simpara>
- <simpara>
- A HASH index only supports exact match: all parts
- of a key participating in the index must be provided.
- </simpara>
- <simpara>
- HASH indexes are always unique.
- </simpara>
- </entry>
- </row>
-
- <row>
- <entry>box.index.GT or 'GT'</entry>
- <entry>field values</entry>
- <entry>
- Keys match if hashed key values are greater than hashed field values.
- If the number of field values is less than the
- number of parts of a multi-part key, the result is an error.
- Tuples are returned in ascending order by hashed key,
- so the order will appear to be random.
- Provided that the space is not being updated,
- the 'GT' iterator can be used
- to retrieve all tuples piece by piece,
- by supplying the last returned value from the previous range as the
- start field value for an iterator over the next range.
- </entry>
- </row>
-
-</tbody>
-</tgroup>
-</table>
-
-
-<table frame='all' pgwide='1'>
-<title>BITSET iterator types</title>
-
-<tgroup cols='3' colsep='1' rowsep='1'>
-<colspec colnum='3' colname="Description" colwidth="6*"/>
-
-<thead>
- <row>
- <entry>Type</entry>
- <entry>Arguments</entry>
- <entry>Description</entry>
- </row>
-</thead>
-
-<tbody>
-
- <row>
- <entry>box.index.ALL or 'ALL'</entry>
- <entry>none</entry>
- <entry>
- Iterate over all tuples in an index.
- Tuples are returned in ascending
- order of the key's bitset, and so
- will appear to be unordered.
- </entry>
- </row>
-
- <row>
- <entry>box.index.EQ or 'EQ'</entry>
- <entry>field values</entry>
- <entry>
- <simpara>
- Equality iterator: iterate over all tuples matching
- the field values.
- If there are multiple field values, they need to be separated by
- commas.
- </simpara>
- <simpara>
- BITSET indexes are always unique.
- </simpara>
- </entry>
- </row>
-
- <row>
- <entry>box.index.BITS_ALL_SET</entry>
- <entry>bit mask</entry>
- <entry>
- Keys match if all of the bits specified in 'bit mask'
- are set.
- </entry>
- </row>
-
- <row>
- <entry>box.index.BITS_ANY_SET</entry>
- <entry>bit mask</entry>
- <entry>
- Keys match if any of the bits specified in 'bit mask'
- is set.
- </entry>
- </row>
-
- <row>
- <entry>box.index.BITS_ALL_NOT_SET</entry>
- <entry>bit mask</entry>
- <entry>
- Keys match if none of the bits specified in 'bit mask'
- is set.
- </entry>
- </row>
-</tbody>
-</tgroup>
-</table>
-
-<table xml:id="rtree-iterator" frame='all' pgwide='1'>
-<title>RTREE iterator types</title>
-
-<tgroup cols='3' colsep='1' rowsep='1'>
-<colspec colnum='3' colname="Description" colwidth="6*"/>
-
-<thead>
- <row>
- <entry>Type</entry>
- <entry>Arguments</entry>
- <entry>Description</entry>
- </row>
-</thead>
-
-<tbody>
-
- <row>
- <entry>box.index.ALL or 'ALL'</entry>
- <entry>none</entry>
- <entry>
- All keys match.
- Tuples are returned in ascending
- order of the primary key.
- </entry>
- </row>
-
- <row>
- <entry>box.index.EQ or 'EQ'</entry>
- <entry>field values</entry>
- <entry>
- Keys match if the rectangle defined by the field values
- is the same as the rectangle defined by the key --
- where "key" means "the key in the RTREE index" and
- "rectangle" means "rectangle as explained in section
- <link linkend="RTREE">RTREE</link>.
- </entry>
- </row>
-
- <row>
- <entry>box.index.GT or 'GT'</entry>
- <entry>field values</entry>
- <entry>
- Keys match if all points of the rectangle defined by the field values
- are within the rectangle defined by the key.
- </entry>
- </row>
-
- <row>
- <entry>box.index.GE or 'GE'</entry>
- <entry>field values</entry>
- <entry>
- Keys match if all points of the rectangle defined by the field values
- are within, or at the side of, the rectangle defined by the key.
- </entry>
- </row>
-
- <row>
- <entry>box.index.LT or 'LT'</entry>
- <entry>field values</entry>
- <entry>
- Keys match if all points of the rectangle defined by the key
- are within the rectangle defined by the field values.
- </entry>
- </row>
-
- <row>
- <entry>box.index.LE or 'LE'</entry>
- <entry>field values</entry>
- <entry>
- Keys match if all points of the rectangle defined by the key
- are within, or at the side of, the rectangle defined by the field values.
- </entry>
- </row>
-
- <row>
- <entry>box.index.OVERLAPS or 'OVERLAPS'</entry>
- <entry>field values</entry>
- <entry>
- Keys match if any point of the rectangle defined by the field values
- is within, or at the side of, the rectangle defined by the key.
- </entry>
- </row>
-
- <row>
- <entry>box.index.NEIGHBOR or 'NEIGHBOR'</entry>
- <entry>field values</entry>
- <entry>
- All keys match. Tuples are returned in order according to the
- distance from the top left corner of the rectangle
- defined by the field values.
- </entry>
- </row>
-
-</tbody>
-</tgroup>
-</table>
-
-</para>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/language-reference.xml b/doc/user/language-reference.xml
deleted file mode 100644
index 067317b8eb8f4d1b472ed5f1b992fa1691a2daf3..0000000000000000000000000000000000000000
--- a/doc/user/language-reference.xml
+++ /dev/null
@@ -1,363 +0,0 @@
-<!DOCTYPE book [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xml:id="language-reference">
-
-<title>Language reference</title>
-<blockquote><para>
- This chapter provides a reference of Tarantool data operations
- and administrative commands.
-</para></blockquote>
-<bridgehead renderas="sect2">Digression: primary and administrative ports</bridgehead>
-<para>
- During start up, the server can allow connections on up to two TCP ports:
- <itemizedlist>
- <listitem><para>
- Primary port. This port is for handling requests in the
- <link xlink:href="http://tarantool.org/doc/box-protocol.html" xlink:title="A complete BNF of Tarantool client/server protocol">native Tarantool protocol</link>
- (also called the "binary protocol"), and provides full data access.
- </para>
- <para>
- The default value of the port is <literal>3301</literal>,
- as defined in the <olink targetptr="primary_port"/>
- configuration option.
- </para></listitem>
- <listitem><para>
- Administrative port, which is for handling requests in unconverted text (also called the "text protocol"),
- which defaults to <literal>3313</literal>,
- and is defined in the <olink targetptr="admin_port"/>
- configuration option.
- </para></listitem>
- </itemizedlist>
- Traditionally, in the absence of authentication,
- ordinary users could be blocked from
- doing administrative operations by simply having them
- blocked from access to the administrative port.
- The client, however, had to be aware of
- the separation, and the <command>tarantool</command> command line
- client automatically selected the correct port
- with the help of a simple regular expression. SELECTs, UPDATEs,
- INSERTs, DELETEs and CALLs were sent to the primary port.
- Lua commands were sent to the administrative port.
-</para>
-
-<section xml:id="data-manipulation">
- <title>Data manipulation</title>
-
- <para>
- The four basic "data-manipulation" requests are: insert() / replace(),
- update(), delete(), select(). They all, including
- insert() and update() and delete(), may return data.
- There are other request types for scanning multiple keys.
- </para>
- <para>
- The update() function supports operations on fields —
- assignment, arithmetic operations (the field must be numeric),
- cutting and pasting fragments of a field, — as well as
- operations on a tuple: push and pop of a field at the tail of
- a tuple, deletion and insertion of a field. Multiple
- operations can be combined into a single update, and in this
- case they are performed atomically. Each operation expects
- field number as its first argument. When a sequence of changes
- is present, field identifier in each operation is assumed to
- be relative to the most recent state of the tuple, i.e. as if
- all previous operations in a multi-operation update have
- already been applied. In other words, it's always safe to
- merge multiple update() invocations into a single one, with no
- change in semantics.
- </para>
- <para>Tarantool protocol was designed with focus on asynchronous
- I/O and easy integration with proxies. Each client
- request starts with a 12-byte binary header, containing three
- fields: request type, length, and a numeric id.
- </para>
- <para>
- The mandatory length, present in request header simplifies
- client or proxy I/O. A response to a request is sent to the
- client as soon as it is ready. It always carries in its header
- the same type and id as in the request. The id makes it
- possible to match a request to a response, even if the latter
- arrived out of order.
- </para>
- <para>For the insert() and update() and delete() operations,
- it is mandatory to pass the primary-key value.
- For the select() operation, either a primary-key value or a
- secondary-key value (possibly multi-part) may be passed.
- All the data-manipulation functions operate on whole tuple(s),
- except update() -- for update() one only needs
- to list the fields that are actually changed.
- </para>
- <para>Unless implementing a client driver, one needn't
- concern oneself with the complications of the binary
- protocol. <olink targetptr="connectors">Language-specific
- drivers</olink> provide a friendly way to store domain
- language data structures in Tarantool.
- A complete description of the binary protocol
- is maintained in annotated Backus-Naur
- form in the source tree: please see
- <link xlink:href="http://tarantool.org/doc/box-protocol.html"><filename>doc/box-protocol.html</filename></link>.
- </para>
-</section>
-
-<section xml:id="administrative-console">
- <title>Administrative console</title>
- <para>
- The administrative console is simply an outlet of the Tarantool
- Lua interpreter. You can connect to the administrative port
- using any <command>telnet</command> client, or a tool like
- <command>rlwrap</command>, if access to readline features is
- desired. Additionally, <command>tarantool</command>, the
- command line client, may distinguish between requests types
- and direct them to the appropriate port.
- The server response to an administrative command, even though
- it is always in plain text, can be quite complex.
- It is encoded using YAML markup to simplify automated parsing.
- </para>
- <para>To learn which functions are considered to be administrative,
- type <emphasis role="lua">help()</emphasis> in the
- administrative console. A reference description also follows
- below:</para>
-
- <variablelist>
-
- <varlistentry>
- <term xml:id="box.snapshot" xreflabel="box.snapshot()">
- <emphasis role="lua">box.snapshot()</emphasis>
- </term>
- <listitem><para>
- Take a snapshot of all data and store it in
- <filename><olink
- targetptr="snap_dir"/>/<latest-lsn>.snap</filename>.
- To take a snapshot, Tarantool first enters the delayed
- garbage collection mode for all data. In this mode,
- tuples which were allocated before the snapshot has
- started are not freed until the snapshot has finished.
- To preserve consistency of the primary key, used to
- iterate over tuples, a copy-on-write technique is employed.
- If the master process changes part of a primary key,
- the corresponding process page is split, and the snapshot
- process obtains an old copy of the page. Since a
- snapshot is written sequentially, one can expect a very
- high write performance (averaging to 80MB/second on modern
- disks), which means an average database instance gets
- saved in a matter of minutes. Note, that as long as there
- are any changes to the parent index memory through concurrent
- updates, there are going to be page splits, and therefore
- one needs to have some extra free memory to run this
- command. 10% of <olink targetptr="slab_alloc_arena"/>
- is, on average, sufficient. This statement waits until a
- snapshot is taken and returns operation result. For
- example:
-<programlisting>tarantool> <userinput>box.info.version</userinput>
----
-- 1.6.0-805-g4a7e71d
-...
-tarantool> <userinput>box.snapshot()</userinput>
----
-ok
-...
-tarantool> <userinput>box.snapshot()</userinput>
----
-fail: can't save snapshot, errno 17 (File exists)
-...
-</programlisting>
- </para>
- <para>
- Taking a snapshot does not cause the server to start a new
- write-ahead log. Once a snapshot is taken, old WALs can be
- deleted as long as all replicas are up to date. But the
- WAL which was current at the time <emphasis
- role="lua">box.snapshot()</emphasis> started must be
- kept for recovery, since it still contains log records
- written after the start of <emphasis role="lua">
- box.snapshot()</emphasis>.
- </para>
- <para>
- An alternative way to save a snapshot is to send the server
- SIGUSR1 UNIX signal. While this approach could be handy, it
- is not recommended for use in automation: a signal provides no
- way to find out whether the snapshot was taken successfully
- or not.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="box.info" xreflabel="box.info()">
- <emphasis role="lua">box.info()</emphasis>
- </term>
- <listitem><para>
-<programlisting>
-<prompt>tarantool></prompt> <userinput>box.info()</userinput>
-- version: 1.6.0-805-g4a7e71d
- status: primary
- pid: 12315
- lsn: 15481913304
- snapshot_pid: 0
- recovery_last_update: 1306964594
- recovery_lag: 0
- uptime: 441524
- build:
- flags: ' -fno-omit-frame-pointer -fno-stack-protector -fexceptions
- -funwind-tables -msse2 -std=gnu99 -Wall -Wextra -Wno-sign-compare
- -Wno-strict-aliasing -fopenmp -pthread'
- target: Linux-x86_64-Debug
- compiler: /usr/bin/cc /usr/bin/c++
- options: cmake . -DCMAKE_INSTALL_PREFIX=/usr/local -DENABLE_STATIC=OFF
- -DENABLE_TRACE=ON -DENABLE_BACKTRACE=ON -DENABLE_CLIENT=true
- logger_pid: 12316
- config: /usr/local/etc/tarantool.cfg
-</programlisting>
- </para>
- <para>
- <emphasis role="strong">recovery_lag</emphasis> holds the
- difference (in seconds) between the current time on the
- machine (wall clock time) and the time stamp of the last
- applied record. In replication setup, this difference can
- indicate the delay taking place before a change is
- applied to a replica.
- </para>
- <para>
- <emphasis role="strong">recovery_last_update</emphasis> is
- the wall clock time of the last change recorded in the
- write-ahead log. To convert it to human-readable time,
- you can use <command>date -d@<replaceable>1306964594.980</replaceable></command>.
- </para>
- <para>
- <emphasis role="strong">status</emphasis> is
- either "primary" or "replica/<hostname>".
- </para>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="box.stat" xreflabel="box.stat">
- <emphasis role="lua">box.stat()</emphasis>
- </term>
- <listitem><para>
- Show the average number of requests per second, and the
- total number of requests since startup, broken down by
- request type.
-<programlisting>
-tarantool> <userinput>box.stat()</userinput>
----
-- DELETE:
- total: 48902544
- rps: 147
- SELECT:
- total: 388322317
- rps: 1246
- REPLACE:
- total: 0
- rps: 0
- INSERT:
- total: 48207694
- rps: 139
- AUTH:
- total: 0
- rps: 0
- CALL:
- total: 0
- rps: 0
- UPDATE:
- total: 743350520
- rps: 1874
-...
-</programlisting>
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="box.slab.info" xreflabel="box.slab.info()">
- <emphasis role="lua">box.slab()</emphasis>
- </term>
- <listitem>
- <para>
- Show the statistics of the slab allocator. The slab
- allocator is the main allocator used to store tuples.
- This can be used to monitor the total memory use and
- memory fragmentation. For example:
- </para>
-<programlisting>
-<prompt>tarantool></prompt> <userinput>box.slab.info()</userinput>
----
-- slabs:
- 64:
- items: 16
- bytes_used: 1024
- item_size: 64
- slabs: 1
- bytes_free: 4193200
- ...
- 136:
- items: 1
- bytes_used: 136
- item_size: 136
- slabs: 1
- bytes_free: 4194088
- ...
- arena_size: 8388448
- arena_used: 1160
-</programlisting>
- <para>
- The display of slabs is broken down by the slab size --
- 64-byte, 136-byte, and so on. The example omits the slabs
- which are empty. The example display is saying that:
- there are 16 items stored
- in the 64-byte slab (and 16*64=1024 so
- bytes_used = 1024); there is 1 item
- stored in the 136-byte slab (and
- 136*1=136 so bytes_used = 136); the
- arena_used value is the total of all the bytes_used
- values (1024+136 = 1160); the
- arena_size value is the arena_used value
- plus the total of all the bytes_free values
- (1160+4193200+4194088 = 8388448). The
- arena_size and arena_used values are the amount of
- the % of <olink targetptr="slab_alloc_arena"/> that is
- already distributed to the slab allocator.
- </para>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="coredump" xreflabel="coredump()">
- <emphasis role="lua">coredump()</emphasis>
- </term>
- <listitem><para>
- Fork and dump a core. Since Tarantool stores all tuples
- in memory, it can take some time. Mainly useful for
- debugging.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="fiber.info" xreflabel="fiber.info">
- <emphasis role="lua">require('fiber').info()</emphasis>
- </term>
- <listitem><para>
- Show all running fibers, with their stack.
- Mainly useful for debugging.
- </para></listitem>
- </varlistentry>
-
- </variablelist>
-
-</section>
-
-<xi:include href="stored-procedures.xml" />
-<xi:include href="triggers.xml" />
-
-</chapter>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/limitations.xml b/doc/user/limitations.xml
deleted file mode 100644
index b606909779057ae761849909e6227fe7fbe5f572..0000000000000000000000000000000000000000
--- a/doc/user/limitations.xml
+++ /dev/null
@@ -1,64 +0,0 @@
-<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="limitations">
-
-<title>Limitations</title>
-
-
-<variablelist>
-
- <varlistentry>
- <term xml:id="limitations-index-field-count" xreflabel="limitations-index-field-count">Number of fields in an index</term>
- <listitem><para>For BITSET indexes, the maximum is 1.
- For TREE indexes, the theoretical maximum is about 4 billion (BOX_FIELD_MAX)
- but the practical maximum is the number of fields in a tuple.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="limitations-index-count" xreflabel="limitations-index-count">Number of indexes in a space</term>
- <listitem><para>10 (BOX_INDEX_MAX).
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="limitations-tuple-field-count" xreflabel="limitations-tuple-field-count">Number of fields in a tuple</term>
- <listitem><para>There is no theoretical maximum.
- The practical maximum is whatever is specified by the space's <code>field_count</code> member,
- or the maximum tuple length.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="limitations-space-count" xreflabel="limitations-space-count">Number of spaces</term>
- <listitem><para>255.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="limitations-connections-count" xreflabel="limitations-connections-count">Number of connections</term>
- <listitem><para>The practical limit is the number of file descriptors that one can set with
- the operating system.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="limitations-slab-alloc-arena-size" xreflabel="limitations-slab-alloc-arena-size">Space size</term>
- <listitem><para>The total maximum size for all spaces is in effect set by slab_alloc_arena,
- which in turn is limited by the total available memory.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="limitations-update-count" xreflabel="limitations-updae-count">Update operations count</term>
- <listitem><para>The maximum number of operations that can be in a single update is 4000 (BOX_UPDATE_OP_CNT_MAX).
- </para></listitem>
- </varlistentry>
-
-</variablelist>
-</appendix>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/lua-and-packages.xml b/doc/user/lua-and-packages.xml
deleted file mode 100644
index 2a5ea7e3200bbdcb0bae5db5bd99d53811cb5c90..0000000000000000000000000000000000000000
--- a/doc/user/lua-and-packages.xml
+++ /dev/null
@@ -1,33 +0,0 @@
-<!DOCTYPE book [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xml:id="lua-and-packages">
-
-<title>Lua and the Tarantool Lua Packages</title>
-
-<blockquote>
- <para>
- <link xlink:href="http://www.lua.org">Lua</link>
- is a light-weight, multi-paradigm, embeddable language.
- Stored procedures in Lua can be used to implement
- data manipulation patterns or data structures.
- It is possible to dynamically define, invoke,
- alter and drop Lua functions. Lua functions can run
- in the background and perform administrative tasks.
- </para>
-</blockquote>
-
-
-<xi:include href="stored-procedures.xml" />
-
-
-</chapter>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/lua-tutorial.xml b/doc/user/lua-tutorial.xml
deleted file mode 100644
index 0be320b948ddaad1369884d9573de8865b710dcc..0000000000000000000000000000000000000000
--- a/doc/user/lua-tutorial.xml
+++ /dev/null
@@ -1,645 +0,0 @@
-<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="lua-tutorial">
-
-<title>Lua tutorial</title>
-
-<section xml:id="lua-tutorial-insert">
-<title>Insert one million tuples with a Lua stored procedure</title>
-
-<para>
-This is an exercise assignment: <quote>Insert one million tuples.
-Each tuple should have a constantly-increasing numeric primary-key field
-and a random alphabetic 10-character string field.</quote>
-</para>
-
-<para>
-The purpose of the exercise is to show what Lua functions
-look like inside Tarantool. It will be necessary to employ
-the Lua math library, the Lua string library, the Tarantool
-box library, the Tarantool box.tuple library, loops, and concatenations. It should be easy
-to follow even for a person who has not used either Lua
-or Tarantool before. The only requirement is a knowledge
-of how other programming languages work and a memory of
-the first two chapters of this manual. But for better understanding,
-follow the comments and the links, which point to the Lua
-manual or to elsewhere in this Tarantool manual.
-To further enhance learning, type the statements
-in with the tarantool client while reading along.
-</para>
-
-<para>
-<bridgehead renderas="sect4">Configure</bridgehead>
-We are going to use the "tarantool_sandbox" that was created in section
-<olink targetptr="getting-started-start-stop">Starting Tarantool and making your first database</olink>.
-So there is a single space, and a numeric primary key,
-and a running tarantool server which also serves as a client.
-</para>
-
-<para>
-<bridgehead renderas="sect4">Delimiter</bridgehead>
-We'll be making functions which go over one line. We don't want the client to send to the server after every line.
-So we <link linkend="utility-tarantool-delim">declare a delimiter</link>.
-This means <quote>Do not send to the server until you see an exclamation mark.</quote>
-
-<programlisting>
-tarantool> <userinput>console = require('console'); console.delimiter('!')</userinput>
-</programlisting>
-From now on it will be possible to use multiple-line statements,
-but it will be necessary to end all statements with exclamation marks.
-</para>
-
-<para>
-<bridgehead renderas="sect4">Create a function that returns a string</bridgehead>
-
-We will start by making a function that returns a fixed string, <quote>Hello world</quote>.
-<programlisting>
-function string_function()
- return "hello world"
- end!
-</programlisting>
-The word "function" is a Lua keyword -- we're about to go into Lua.
-The function name is string_function.
-The function has one executable statement, <code>return "hello world"</code>.
-The string "hello world" is enclosed in double quotes here,
-although Lua doesn't care -- one could use single quotes instead.
-The word "end" means <quote>this is the end of the Lua function declaration.</quote>
-The word "end" is followed by "!" because "!" happens to be the delimiter that we chose in the previous step.
-
-To confirm that the function works, we can say
-<programlisting>
-string_function()!
-</programlisting>
-Sending <replaceable>function-name</replaceable>() means <quote>invoke the Lua function.</quote>
-The effect is that the string which the function returns will end up on the screen.
-</para>
-
-<para>
-For more about Lua strings see Lua manual chapter 2.4 "Strings"
-<productname xlink:href="http://www.lua.org/pil/2.4.html">http://www.lua.org/pil/2.4.html</productname>.
-
-For more about functions see Lua manual chapter 5 "Functions"
-<productname xlink:href="http://www.lua.org/pil/5.html">http://www.lua.org/pil/5.html</productname>.
-</para>
-
-<para>
-The screen now looks like this:
-<programlisting>
-tarantool> <userinput>function string_function()</userinput>
- -> <userinput>return "hello world"</userinput>
- -> <userinput>end!</userinput>
----
-...
-tarantool> <userinput>string_function()!</userinput>
----
-- hello world
-...
-tarantool>
-</programlisting>
-</para>
-
- <para>
-<bridgehead renderas="sect4">Create a function that calls another function and sets a variable</bridgehead>
-
-Now that string_function exists, we can invoke it from another function.
-<programlisting>
-function main_function()
- local string_value
- string_value = string_function()
- return string_value
- end!
-</programlisting>
-We begin by declaring a variable "string_value".
-The word "local" means that string_value appears only in main_function.
-If we didn't use "local" then string_value would be visible everywhere
--- even by other users using other clients connected to this server!
-Sometimes that's a very desirable feature for inter-client communication, but not this time.
-</para>
-
-<para>
-Then we assign a value to string_value, namely, the result of string_function().
-Soon we will invoke main_function() to check that it got the value.
-</para>
-
-<para>
-For more about Lua variables see Lua manual chapter 4.2 "Local Variables and Blocks"
-<productname xlink:href="http://www.lua.org/pil/4.2.html">http://www.lua.org/pil/4.2.html</productname>.
-</para>
-
-<para>
-The screen now looks like this:
-<programlisting>
-tarantool> <userinput>function main_function()</userinput>
- -> <userinput>local string_value</userinput>
- -> <userinput>string_value = string_function()</userinput>
- -> <userinput>return string_value</userinput>
- -> <userinput>end!</userinput>
----
-...
-tarantool> <userinput>main_function()!</userinput>
----
-- hello world
-...
-tarantool>
-</programlisting>
-</para>
-
-<para>
-<bridgehead renderas="sect4">Modify the function so it returns a one-letter random string</bridgehead>
-
-Now that it's a bit clearer how to make a variable, we can change string_function()
-so that, instead of returning a fixed literal 'Hello world", it returns a random letter between 'A' and 'Z'.
-<programlisting>
-function string_function()
- local random_number
- local random_string
- random_number = math.random(65, 90)
- random_string = string.char(random_number)
- return random_string
- end!
-</programlisting>
-It is not necessary to destroy the old string_function() contents, they're simply overwritten.
-The first assignment invokes a random-number function in Lua's math library; the parameters mean <quote>the number must be an integer between 65 and 90.</quote>
-The second assignment invokes an integer-to-character function in Lua's string library; the parameter is the code point of the character.
-Luckily the ASCII value of 'A' is 65 and the ASCII value of 'Z' is 90 so the result will always be a letter between A and Z.
-</para>
-
-<para>
-For more about Lua math-library functions see Lua users "Math Library Tutorial"
-<productname xlink:href="http://lua-users.org/wiki/MathLibraryTutorial">http://lua-users.org/wiki/MathLibraryTutorial</productname>.
-For more about Lua string-library functions see Lua users "String Library Tutorial"
-<productname xlink:href="http://lua-users.org/wiki/StringLibraryTutorial">http://lua-users.org/wiki/StringLibraryTutorial</productname>.
-</para>
-
-<para>
-Once again the string_function() can be invoked from main_function() which can be invoked with
-</para>
-<para>
-main_function()!
-</para>
-
-<para>
-The screen now looks like this:
-<programlisting>
-tarantool> <userinput>function string_function()</userinput>
- -> <userinput>local random_number</userinput>
- -> <userinput>local random_string</userinput>
- -> <userinput>random_number = math.random(65, 90)</userinput>
- -> <userinput>random_string = string.char(random_number)</userinput>
- -> <userinput>return random_string</userinput>
- -> <userinput>end!</userinput>
----
-...
-tarantool> <userinput>main_function()!</userinput>
----
-- C
-...
-tarantool>
-</programlisting>
-... Well, actually it won't always look like this because math.random() produces random numbers.
-But for the illustration purposes it won't matter what the random string values are.
-</para>
-
-<para>
-<bridgehead renderas="sect4">Modify the function so it returns a ten-letter random string</bridgehead>
-Now that it's clear how to produce one-letter random strings, we can reach our goal
-of producing a ten-letter string by concatenating ten one-letter strings, in a loop.
-<programlisting>
-function string_function()
- local random_number
- local random_string
- random_string = ""
- for x = 1,10,1 do
- random_number = math.random(65, 90)
- random_string = random_string .. string.char(random_number)
- end
- return random_string
- end!
-</programlisting>
-The words "for x = 1,10,1" mean <quote>start with x equals 1, loop until x equals 10, increment x by 1 for each iteration.</quote>
-The symbol ".." means "concatenate", that is, add the string on the right of the ".." sign to the string on the left of the ".." sign.
-Since we start by saying that random_string is "" (a blank string), the end result is that random_string has 10 random letters.
-
-Once again the string_function() can be invoked from main_function() which can be invoked with
-</para>
-<para>
-main_function()!
-</para>
-
-<para>
-For more about Lua loops see Lua manual chapter 4.3.4 "Numeric for"
-<productname xlink:href="http://www.lua.org/pil/4.3.4.html">http://www.lua.org/pil/4.3.4.html</productname>.
-</para>
-
-<para>
-The screen now looks like this:
-<programlisting>
-tarantool> <userinput>function string_function()</userinput>
- -> <userinput>local random_number</userinput>
- -> <userinput>local random_string</userinput>
- -> <userinput>random_string = ""</userinput>
- -> <userinput>for x = 1,10,1 do</userinput>
- -> <userinput>random_number = math.random(65, 90)</userinput>
- -> <userinput>random_string = random_string .. string.char(random_number)</userinput>
- -> <userinput>end</userinput>
- -> <userinput>return random_string</userinput>
- -> <userinput>end!</userinput>
----
-...
-tarantool> <userinput>main_function()!</userinput>
----
-- 'ZUDJBHKEFM'
-...
-tarantool>
-</programlisting>
-</para>
-
-<para>
-<bridgehead renderas="sect4">Make a tuple out of a number and a string</bridgehead>
-
-Now that it's clear how to make a 10-letter random string, it's possible to
-make a tuple that contains a number and a 10-letter random string, by invoking
-a function in Tarantool's library of Lua functions.
-<programlisting>
-function main_function()
- local string_value
- string_value = string_function()
- t = box.tuple.new({1, string_value})
- return t
- end!
-</programlisting>
-Once this is done, t will be the value of a new tuple which has two
-fields. The first field is numeric: 1. The second field is a random string.
-
-Once again the string_function() can be invoked from main_function() which can be invoked with
-</para>
-<para>
-main_function()!
-</para>
-
-<para>
-For more about Tarantool tuples see Tarantool manual section
-<olink targetptr="sp-box-tuple">Package box.tuple</olink>.
-</para>
-
-<para>
-The screen now looks like this:
-<programlisting>
-tarantool> <userinput>function main_function()</userinput>
- -> <userinput>local string_value</userinput>
- -> <userinput>string_value = string_function()</userinput>
- -> <userinput>t = box.tuple.new({1, string_value})</userinput>
- -> <userinput>return t</userinput>
- -> <userinput>end!</userinput>
----
-...
-tarantool> <userinput>main_function()!</userinput>
----
-- [1, 'PNPZPCOOKA']
-...
-tarantool>
-</programlisting>
-</para>
-
-<para>
-<bridgehead renderas="sect4">Modify main_function to insert a tuple into the database</bridgehead>
-
-Now that it's clear how to make a tuple that contains a number and a 10-letter random string,
-the only trick remaining is putting that tuple into tester. Remember that tester is
-the first space that was defined in the sandbox, so it's like a database table.
-<programlisting>
-function main_function()
- local string_value
- string_value = string_function()
- t = box.tuple.new({1,string_value})
- box.space.tester:replace(t)
- end!
-</programlisting>
-The new line here is box.space.tester:replace(t). The name contains 'tester' because the
-insertion is going to be to tester. The second parameter is the tuple value.
-To be perfectly correct we could have said box.space.tester:insert(t) here, rather than
-box.space.tester:replace(t), but "replace" means <quote>insert even if there is already a tuple
-whose primary-key value is a duplicate</quote>, and that makes it easier to re-run
-the exercise even if the sandbox database isn't empty.
-
-Once this is done, tester will contain a tuple with two fields. The first
-field will be 1. The second field will be a random 10-letter string.
-
-Once again the string_function() can be invoked from main_function() which can be invoked with
-<code>main_function()!</code>. But main_function() won't tell the whole story, because it does not
-return t, it only puts t into the database. To confirm that something got inserted, we'll
-use a SELECT request.
-
-<programlisting>
-main_function()!
-box.space.tester:select{1}!
-</programlisting>
-</para>
-
-<para>
-For more about Tarantool insert and replace calls, see Tarantool manual section
-<olink targetptr="sp-box">Package box</olink>.
-</para>
-
-<para>
-The screen now looks like this:
-<programlisting>
-tarantool> <userinput>function main_function()</userinput>
- -> <userinput>local string_value</userinput>
- -> <userinput>string_value = string_function()</userinput>
- -> <userinput>t = box.tuple.new({1,string_value})</userinput>
- -> <userinput>box.space.tester:replace(t)</userinput>
- -> <userinput>end!</userinput>
----
-...
-tarantool> <userinput>main_function()!</userinput>
----
-...
-tarantool> <userinput>box.space.tester:select{1}!</userinput>
----
-- - [1, 'EUJYVEECIL']
-...
-tarantool>
-</programlisting>
-</para>
-
-<para>
-<bridgehead renderas="sect4">Modify main_function to insert a million tuples into the database</bridgehead>
-
-Now that it's clear how to insert one tuple into the database,
-it's no big deal to figure out how to scale up: instead of
-inserting with a literal value = 1 for the primary key, insert
-with a variable value = between 1 and 1 million, in a loop.
-Since we already saw how to loop, that's a simple thing.
-The only extra wrinkle that we add here is a timing function.
-<programlisting>
-function main_function()
- local string_value
- start_time = os.clock()
- for i = 1,1000000,1 do
- string_value = string_function()
- t = box.tuple.new({i,string_value})
- box.space.tester:replace(t)
- end
- end_time = os.clock()
- end!
-main_function()!
-'insert done in ' .. end_time - start_time .. ' seconds'!
-</programlisting>
-
-The Lua os.clock() function will return the number of seconds since the start.
-Therefore, by getting start_time = number of seconds just before the inserting,
-and then getting end_time = number of seconds just after the inserting,
-we can calculate (end_time - start_time) = elapsed time in seconds.
-We will display that value by putting it in a request without any assignments,
-which causes Tarantool to send the value to the client, which prints it.
-(Lua's answer to the C printf() function, which is print(), will also work.)
-</para>
-
-<para>
-For more on Lua os.clock() see Lua manual chapter 22.1 "Date and Time"
-<productname xlink:href="http://www.lua.org/pil/22.1.html">http://www.lua.org/pil/22.1.html</productname>.
-For more on Lua print() see Lua manual chapter 5 "Functions"
-<productname xlink:href="http://www.lua.org/pil/5.html">http://www.lua.org/pil/5.html</productname>.
-</para>
-
-<para>
-Since this is the grand finale, we will redo the final versions of all the necessary
-requests: the console.delimiter('!') request, the request that created string_function(),
-the request that created main_function(), and the request that invokes main_function().
-
-
-<programlisting>
-#Skip the following statement if you have already said "console.delimiter('!')"
-console = require('console'); console.delimiter('!')
-
-function string_function()
- local random_number
- local random_string
- random_string = ""
- for x = 1,10,1 do
- random_number = math.random(65, 90)
- random_string = random_string .. string.char(random_number)
- end
- return random_string
- end!
-
-function main_function()
- local string_value
- start_time = os.clock()
- for i = 1,1000000,1 do
- string_value = string_function()
- t = box.tuple.new({i,string_value})
- box.space.tester:replace(t)
- end
- end_time = os.clock()
- end!
-main_function()!
-'insert done in ' .. end_time - start_time .. ' seconds'!
-</programlisting>
-
-The screen now looks like this:
-
-<programlisting>
-tarantool> <userinput>console = require('console'); console.delimiter('!')</userinput>
-tarantool> <userinput>function string_function()</userinput>
- -> <userinput>local random_number</userinput>
- -> <userinput>local random_string</userinput>
- -> <userinput>random_string = ""</userinput>
- -> <userinput>for x = 1,10,1 do</userinput>
- -> <userinput>random_number = math.random(65, 90)</userinput>
- -> <userinput>random_string = random_string .. string.char(random_number)</userinput>
- -> <userinput>end</userinput>
- -> <userinput>return random_string</userinput>
- -> <userinput>end!</userinput>
----
-...
-tarantool> <userinput>function main_function()</userinput>
- -> <userinput>local string_value</userinput>
- -> <userinput>start_time = os.clock()</userinput>
- -> <userinput>for i = 1,1000000,1 do</userinput>
- -> <userinput>string_value = string_function()</userinput>
- -> <userinput>t = box.tuple.new({i,string_value})</userinput>
- -> <userinput>box.space.tester:replace(t)</userinput>
- -> <userinput>end</userinput>
- -> <userinput>end_time = os.clock()</userinput>
- -> <userinput>end!</userinput>
----
-...
-tarantool> <userinput>main_function()!</userinput>
----
-...
-tarantool> <userinput>'insert done in ' .. end_time - start_time .. ' seconds'!</userinput>
----
-- insert done in 60.62 seconds
-...
-tarantool>
-</programlisting>
-</para>
-
-<para>
-What has been shown is that Lua functions are quite expressive
-(in fact one can do more with Tarantool's Lua stored procedures
-than one can do with stored procedures in some SQL DBMSs), and
-that it's straightforward to combine Lua-library functions and
-Tarantool-library functions.
-</para>
-
-<para>
-What has also been shown is that inserting a million
-tuples took 60 seconds. The host computer was a Toshiba
-laptop with a 2.2-GHz Intel Core Duo CPU.
-</para>
-
-</section>
-
-<section xml:id="lua-tutorial-sum">
-<title>Sum a JSON field for all tuples</title>
-
-<para>
-This is an exercise assignment: <quote>Assume that inside every tuple there
-is a string formatted as JSON. Inside that string there is a JSON numeric
-field. For each tuple, find the numeric field's value and add it to a
-'sum' variable. At end, return the 'sum' variable.</quote>
-The purpose of the exercise is to get experience in one way
-to read and process tuples.
-</para>
-
-<programlisting language="lua">
-console = require('console'); console.delimiter('!')
-function sum_json_field(field_name)
- json = require('json')
- local v, t, sum, field_value, is_valid_json, lua_table --[[1]]
- sum = 0 --[[2]]
- for v, t in box.space.tester:pairs() do --[[3]]
- is_valid_json, lua_table = pcall(json.decode, t[2]) --[[4]]
- if is_valid_json then --[[5]]
- field_value = lua_table[field_name] --[[6]]
- if type(field_value) == "number" then sum = sum + field_value end --[[7]]
- end --[[8]]
- end --[[9]]
- return sum --[[10]]
- end!
-console.delimiter('')!
-</programlisting>
-
-<para>
-LINE 1: WHY "LOCAL". This line declares all the variables that will be used
-in the function. Actually it's not necessary to declare all variables at the start,
-and in a long function it would be better to declare variables just before using
-them. In fact it's not even necessary to declare variables at all, but an
-undeclared variable is "global". That's not desirable for any of the variables
-that are declared in line 1, because all of them are for use only within the
-function.
-</para>
-
-<para>
-LINE 3: WHY PAIRS()". Our job is to go through all the rows and there are two ways
-to do it: with box.space.<replaceable>space-name</replaceable>:pairs() or with
-<olink targetptr="box.index.iterator">index.iterator</olink>. We preferred
-pairs() because it is simpler.
-</para>
-
-<para>
-LINE 3: START THE MAIN LOOP. Everything inside this "<code>for</code>" loop will be repeated
-as long as there is another index key. A tuple is fetched and can be referenced
-with variable <code>t</code>.
-</para>
-
-<para>
-LINE 4: WHY "PCALL". If we simply said "<code>lua_table = json.decode(t[2]))</code>",
-then the function would abort with an error if it encountered something wrong
-with the JSON string -- a missing colon, for example. By putting the function
-inside "<code>pcall</code>" (<link xlink:href="http://www.lua.org/pil/8.4.html">protected call</link>), we're saying: we want to intercept that sort
-of error, so if there's a problem just set <code>is_valid_json = false</code> and we
-will know what to do about it later.
-</para>
-
-<para>
-LINE 4: MEANING. The function is <olink targetptr="box.cjson">json.decode</olink> which means decode a JSON
-string, and the parameter is <code>t[2]</code> which is a reference to a JSON string.
-There's a bit of hard coding here, we're assuming that the second
-field in the tuple is where the JSON string was inserted. For example, we're assuming a tuple looks like <programlisting>field[1]: 444
-field[2]: '{"Hello": "world", "Quantity": 15}'
-</programlisting>meaning that the tuple's first field, the primary key field, is a number
-while the tuple's second field, the JSON string, is a string. Thus the
-entire statement means "decode <code>t[2]</code> (the tuple's second field) as a JSON
-string; if there's an error set <code>is_valid_json = false</code>; if there's no error
-set <code>is_valid_json = true</code> and set <code>lua_table</code> = a Lua table which has the
-decoded string".
-</para>
-
-<para>
-LINE 6. At last we are ready to get the JSON field value from the Lua
-table that came from the JSON string.
-The value in <code>field_name</code>, which is the parameter for the whole function,
-must be a name of a JSON field. For example, inside the JSON string
-'{"Hello": "world", "Quantity": 15}', there are two JSON fields: "Hello"
-and "Quantity". If the whole function is invoked with <code>sum_json_field("Quantity")</code>,
-then <code>field_value = lua_table[field_name]</code> is effectively the same as
-<code>field_value = lua_table["Quantity"]</code> or even <code>field_value = lua_table.Quantity</code>.
-Those are just three different ways of saying: for the Quantity field
-in the Lua table, get the value and put it in variable <code>field_value</code>.
-</para>
-
-<para>
-LINE 7: WHY "IF". Suppose that the JSON string is well formed but the
-JSON field is not a number, or is missing. In that case, the function
-would be aborted when there was an attempt to add it to the sum.
-By first checking <code>type(field_value) == "number"</code>, we avoid that abortion.
-Anyone who knows that the database is in perfect shape can skip this kind of thing.
-</para>
-
-<para>
-And the function is complete. Time to test it.
-Starting with an empty database, defined the same way as the
-sandbox database that was introduced in
-<olink
-targetptr="getting-started-start-stop"><quote>Starting Tarantool and making your first database</quote></olink>,
-
-<programlisting>
-box.space.tester:drop() -- if tester is left over from some previous test, destroy it
-box.schema.space.create('tester')
-box.space.tester:create_index('primary', {parts = {1, 'NUM'}})
-</programlisting>
-then add some tuples where the first field is a number and the second field is a string.
-</para>
-<programlisting>
-box.space.tester:insert{444, '{"Item": "widget", "Quantity": 15}'}
-box.space.tester:insert{445, '{"Item": "widget", "Quantity": 7}'}
-box.space.tester:insert{446, '{"Item": "golf club", "Quantity": "sunshine"}'}
-box.space.tester:insert{447, '{"Item": "waffle iron", "Quantit": 3}'}
-</programlisting>
-<para>
-Since this is a test, there are deliberate errors. The "golf club" and
-the "waffle iron" do not have numeric Quantity fields, so must be ignored.
-Therefore the real sum of the Quantity field in the JSON strings should be:
-15 + 7 = 22.
-</para>
-
-<para>
-Invoke the function with <code>sum_json_field("Quantity")</code>.
-<programlisting language="lua">
-<prompt>tarantool></prompt> <userinput>sum_json_field("Quantity")</userinput>
----
-- 22
-...
-</programlisting>
-</para>
-
-<para>
-It works. We'll just leave, as exercises for future improvement, the possibility
-that the "hard coding" assumptions could be removed, that there might have to be
-an overflow check if some field values are huge, and that the function should
-contain a "yield" instruction if the count of tuples is huge.
-</para>
-
-</section>
-
-</appendix>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
-
diff --git a/doc/user/olinkdb.xml b/doc/user/olinkdb.xml
deleted file mode 100644
index affaca2bee9efeccb94b1efc99ee721576eaef4f..0000000000000000000000000000000000000000
--- a/doc/user/olinkdb.xml
+++ /dev/null
@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<targetset>
- <document targetdoc="tarantool-user-guide">
- <xi:include href="target.db" xmlns:xi="http://www.w3.org/2001/XInclude"/>
- </document>
-</targetset>
diff --git a/doc/user/persistence-architecture.xml b/doc/user/persistence-architecture.xml
deleted file mode 100644
index f5c7a71d3054e73fa1ec0103d331cbb06c1d6359..0000000000000000000000000000000000000000
--- a/doc/user/persistence-architecture.xml
+++ /dev/null
@@ -1,133 +0,0 @@
-<!DOCTYPE section [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="data-persistence">
-<title>Data persistence</title>
-<para>
-To maintain data persistence, Tarantool writes each data change
-request (INSERT, UPDATE, DELETE, REPLACE) into a write-ahead log (WAL)
-file in the <olink targetptr="wal_dir"/> directory.
-A new WAL file is created for every <olink
-targetptr="rows_per_wal"/> records. Each data change request
-gets assigned a continuously growing 64-bit log sequence number.
-The name of the WAL file is based on the log sequence
-number of the first record in the file, plus an extension <filename>.xlog</filename>.
-</para>
-
-<para>Apart from a log sequence number and the data change request
-(its format is the same as in the binary protocol and is described
-in <link
-xlink:href="http://tarantool.org/doc/box-protocol.html"><filename>doc/box-protocol.html</filename></link>),
-each WAL record contains a header, some metadata, and then the data formatted
-according to <link xlink:href="https://github.com/msgpack/msgpack/blob/master/spec.md">msgpack rules</link>.
-For example this is what the WAL file looks like after the first INSERT
-request ("s:insert({1})") for the introductory sandbox exercise
-<olink
-targetptr="getting-started-start-stop"><quote>Starting Tarantool and making your first database</quote></olink>.
-On the left are the hexadecimal bytes that one would see with
-<programlisting><prompt>$ </prompt><userinput>hexdump 00000000000000000001.xlog</userinput></programlisting>
-and on the right are comments.
-<programlisting>
-Hex dump of WAL file Comment
--------------------- -------
-58 4c 4f 47 0a File header: "XLOG\n"
-30 2e 31 32 0a 0a File header: "0.12\n\n" = version
-... (not shown = inserted tuples for LSN and system spaces)
-d5 ba 0b ab Magic row marker always = 0xab0bbad5 if version 0.12
-19 00 Length, not including length of header, = 25 bytes
-ce 16 a4 38 6f Record header: previous crc32, current crc32,
-a7 cc 73 7f 00 00 66 39
-84 msgpack code meaning "Map of 4 elements" follows
-00 02 02 01 the 4 elements, including 0x02 which is IPROTO_INSERT
-03 04 04 additional information
-cb 41 d4 e2 2f 62 fd d5 d4 msgpack code meaning "Double" follows, for next 8 bytes
-82 msgpack code meaning "map of 2 elements" follows
-10 IPROTO_SPACE_ID which is #defined as 16 (hex 10)
-cd msgpack code meaning 2-digit number follows
-02 00 the id of "tester" which is 513, it's biggest byte first
-21 Flags = IPROTO_TUPLE which is #defined as hex 21
-91 msgpack code meaning "1-element fixed array" follows
-01 Tuple: field[1] value = 1
-</programlisting>
-</para>
-
-<para>
-Tarantool processes requests atomically: a change is either
-accepted and recorded in the WAL, or discarded completely.
-Let's clarify how this happens, using the REPLACE request as an
-example:
-<orderedlist>
- <listitem><para>
- The server attempts to locate the original tuple by
- primary key. If found, a reference to the tuple is retained
- for later use.
- </para></listitem>
- <listitem><para>
- The new tuple is then <emphasis>validated</emphasis>. If
- for example it does not contain an indexed field,
- or it has an indexed field whose type does not
- match the type according to the index definition,
- the change is aborted.
- </para></listitem>
- <listitem><para>
- The new tuple replaces the old tuple in all
- existing indexes.
- </para></listitem>
- <listitem><para>
- A message is sent to WAL writer running in a
- separate thread, requesting that the change be recorded in the WAL.
- The server switches to work on the next request until the write
- is acknowledged.
- </para></listitem>
- <listitem><para>
- On success, a confirmation is sent to the client. Upon
- failure, a rollback procedure is begun. During the rollback
- procedure, the transaction processor rolls back all changes to
- the database which occurred after the first failed change, from
- latest to oldest, up to the first failed change. All rolled back
- requests are aborted with <olink targetptr="ER_WAL_IO"/>
- error. No new change is applied while rollback is in progress.
- When the rollback procedure is finished, the server restarts
- the processing pipeline.
- </para></listitem>
-</orderedlist>
-</para>
-
-<para>
-One advantage of the described algorithm is that complete request
-pipelining is achieved, even for requests on the same value of the
-primary key. As a result, database performance doesn't degrade
-even if all requests touch upon the same key in the same space.
-</para>
-
-<para>
-The transaction processor thread communicates with the WAL writer thread
-using asynchronous (yet reliable) messaging; the transaction
-processor thread, not being blocked on WAL tasks, continues to
-handle requests quickly even at high volumes of disk I/O. A
-response to a request is sent as soon as it is ready, even if
-there were earlier incomplete requests on the same connection. In
-particular, SELECT performance, even for SELECTs running on a
-connection packed with UPDATEs and DELETEs, remains unaffected by
-disk load.
-</para>
-
-<para>
-The WAL writer employs a number of durability modes, as defined
-in configuration variable <olink targetptr="wal_mode"/>. It is
-possible to turn the write-ahead log completely off, by setting
-<olink targetptr="wal_mode"/> to <emphasis>none</emphasis>.
-Even without the write-ahead log it's still possible to take a
-persistent copy of the entire data set with the
-<olink targetptr="box.snapshot"/> statement.
-</para>
-
-
-</section>
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/plugins.xml b/doc/user/plugins.xml
deleted file mode 100644
index 029edf6a38aa0fa88007981aa022b632bff083b8..0000000000000000000000000000000000000000
--- a/doc/user/plugins.xml
+++ /dev/null
@@ -1,318 +0,0 @@
-<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="plugins">
-
-<title>Plugins</title>
-
-<para>
-A plugin is an optional library which enhances Tarantool functionality.
-</para>
-
-<para>
-The details of creating one's own plugin are described on
-<productname xlink:href="https://github.com/tarantool/tarantool/wiki/Plugin-API">the Tarantool Plugin API wiki page</productname>.
-</para>
-
-<para>
-The discussion here in the user guide is about incorporating and using
-two plugins that have already been created: the "SQL DBMS plugins" for
-MySQL and PostgreSQL.
-</para>
-
-<para xml:id="plugin-sql-dbms-plugins">
-<bridgehead renderas="sect4">SQL DBMS Plugins</bridgehead>
-To call another DBMS from Tarantool, the essential requirements are:
-another DBMS, and Tarantool.
-</para>
-
-<para>
-It will be necessary to build Tarantool from source,
-as described in
-<olink
-targetptr="getting-started-source"><quote>Downloading and building a source package</quote></olink>.
-</para>
-
-<para>
-The Tarantool plugins allow for connecting to an SQL server
-and executing SQL statements the same way that a MySQL or PostgreSQL client does.
-The SQL statements are visible as Lua methods. Thus Tarantool can
-serve as a "MySQL Lua Connector" or "PostgreSQL Lua Connector", which would be useful even if
-that was all Tarantool could do. But of course Tarantool is also
-a DBMS, so the plugin also is useful for any operations, such as
-database copying and accelerating, which work best when the application
-can work on both SQL and Tarantool inside the same Lua routine.
-</para>
-
-<para>
-The connection method is
-<code>box.net.sql.connect('mysql'|'pg', <replaceable>host</replaceable>, <replaceable>port</replaceable>, <replaceable>user</replaceable>, <replaceable>password</replaceable>, <replaceable>database</replaceable>)</code>.
-The methods for select/insert/etc. are the same as the ones in <link linkend="sp-net-box">the net.box package</link>.
-</para>
-
-<para xml:id="plugin-mysql-example">
-<bridgehead renderas="sect4">MySQL Example</bridgehead>
-This example assumes that MySQL 5.5 or MySQL 5.6 has been installed
-(recent MariaDB versions should also work).
-</para>
-
-<para>
-The example was run on a Linux machine where the base directory
-had a copy of the Tarantool source on ~/tarantool, and
-a copy of MySQL on ~/mysql-5.5. The mysqld server is already running
-on the local host 127.0.0.1.
-</para>
-
-<programlisting>
-# Check that the include subdirectory exists by looking for .../include/mysql.h.
-# (If this fails, there's a chance that it's in .../include/mysql/mysql.h instead.)
-<prompt>$ </prompt><userinput>[ -f ~/mysql-5.5/include/mysql.h ] && echo "OK" || echo "Error"</userinput>
-OK
-
-# Check that the library subdirectory exists and has the necessary .so file.
-<prompt>$ </prompt><userinput>[ -f ~/mysql-5.5/lib/libmysqlclient.so ] && echo "OK" || echo "Error"</userinput>
-OK
-
-# Check that the mysql client can connect using some factory defaults:
-# port = 3306, user = 'root', user password = '', database = 'test'.
-# These can be changed, provided one uses the changed values in
-# all places.
-<prompt>$ </prompt><userinput>~/mysql-5.5/bin/mysql --port=3306 -h 127.0.0.1 --user=root --password= --database=test</userinput>
-Welcome to the MySQL monitor. Commands end with ; or \g.
-Your MySQL connection id is 25
-Server version: 5.5.35 MySQL Community Server (GPL)
-...
-Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
-
-<prompt>mysql></prompt>
-
-# Insert a row in database test, and quit.
-<prompt>mysql></prompt> <userinput>CREATE TABLE IF NOT EXISTS test (s1 INT, s2 VARCHAR(50));</userinput>
-Query OK, 0 rows affected (0.13 sec)
-<prompt>mysql></prompt> <userinput>INSERT INTO test.test VALUES (1,'MySQL row');</userinput>
-Query OK, 1 row affected (0.02 sec)
-<prompt>mysql></prompt> <userinput>QUIT</userinput>
-Bye
-
-# Build the Tarantool server. Make certain that "cmake" gets the right
-# paths for the MySQL include directory and the MySQL libmysqlclient
-# library which were checked earlier.
-<prompt>$ </prompt><userinput>cd ~/tarantool</userinput>
-<prompt>$ </prompt><userinput>make clean</userinput>
-<prompt>$ </prompt><userinput>rm CMakeCache.txt</userinput>
-<prompt>$ </prompt><userinput>cmake . -DWITH_MYSQL=on -DMYSQL_INCLUDE_DIR=~/mysql-5.5/include\</userinput>
-<prompt>> </prompt><userinput> -DMYSQL_LIBRARIES=~/mysql-5.5/lib/libmysqlclient.so</userinput>
-...
--- Found MySQL includes: ~/mysql-5.5/include/mysql.h
--- Found MySQL library: ~/mysql-5.5/lib/libmysqlclient.so
-...
--- Configuring done
--- Generating done
--- Build files have been written to: ~/tarantool
-<prompt>$ </prompt><userinput>make</userinput>
-...
-Scanning dependencies of target mysql
-[ 79%] Building CXX object src/module/mysql/CMakeFiles/mysql.dir/mysql.cc.o
-Linking CXX shared library libmysql.so
-[ 79%] Built target mysql
-...
-[100%] Built target man
-<prompt>$ </prompt>
-
-# The MySQL module should now be in ./src/module/mysql/mysql.so.
-# If a "make install" had been done, then mysql.so would be in a
-# different place, for example
-# /usr/local/lib/x86_64-linux-gnu/tarantool/box/net/mysql.so.
-# In that case there should be additional cmake options such as
-# -DCMAKE_INSTALL_LIBDIR and -DCMAKE_INSTALL_PREFIX.
-# For this example we assume that "make install" is not done.
-
-# Change directory to a directory which can be used for temporary tests.
-# For this example we assume that the name of this directory is
-# /home/pgulutzan/tarantool_sandbox. (Change "/home/pgulutzan" to whatever
-# is the actual base directory for the machine that's used for this test.)
-# Now, to help tarantool find the essential mysql.so file, execute these lines:
-<userinput>cd /home/pgulutzan/tarantool_sandbox</userinput>
-<userinput>mkdir box</userinput>
-<userinput>mkdir box/net</userinput>
-<userinput>cp ~/tarantool/src/module/mysql/mysql.so ./box/net/mysql.so</userinput>
-
-# Start the Tarantool server. Do not use a Lua initialization file.
-
-<prompt>$ </prompt><userinput>~/tarantool/src/tarantool</userinput>
-~/tarantool/src/tarantool: version 1.6.3-439-g7e1011b
-type 'help' for interactive help
-<prompt>tarantool> </prompt> <userinput>box.cfg{}</userinput>
-...
-# Enter the following lines on the prompt (again, change "/home/pgulutzan"
-# to whatever the real directory is that contains tarantool):
-package.path = "/home/pgulutzan/tarantool/src/module/sql/?.lua;"..package.path
-require("sql")
-if type(box.net.sql) ~= "table" then error("net.sql load failed") end
-require("box.net.mysql")
-# ... Make sure that tarantool replies "true" for both calls to "require()".
-
-# Create a Lua function that will connect to the MySQL server,
-# (using some factory default values for the port and user and password),
-# retrieve one row, and display the row.
-# For explanations of the statement types used here, read the
-# Lua tutorial earlier in the Tarantool user manual.
-<prompt>tarantool> </prompt><userinput>console = require('console'); console.delimiter('!')</userinput>
-<prompt>tarantool> </prompt><userinput>function mysql_select ()</userinput>
- <prompt>-> </prompt><userinput> local dbh = box.net.sql.connect(</userinput>
- <prompt>-> </prompt><userinput> 'mysql', '127.0.0.1', 3306, 'root', '', 'test')</userinput>
- <prompt>-> </prompt><userinput> local test = dbh:select('SELECT * FROM test WHERE s1 = 1')</userinput>
- <prompt>-> </prompt><userinput> local row = ''</userinput>
- <prompt>-> </prompt><userinput> for i, card in pairs(test) do</userinput>
- <prompt>-> </prompt><userinput> row = row .. card.s2 .. ' '</userinput>
- <prompt>-> </prompt><userinput> end</userinput>
- <prompt>-> </prompt><userinput> return row</userinput>
- <prompt>-> </prompt><userinput> end!</userinput>
----
-...
-<prompt>tarantool> </prompt><userinput>console.delimiter('')!</userinput>
-<prompt>tarantool> </prompt>
-
-# Execute the Lua function.
-<prompt>tarantool> </prompt><userinput>mysql_select()</userinput>
----
-- 'MySQL row '
-...
-# Observe the result. It contains "MySQL row".
-# So this is the row that was inserted into the MySQL database.
-# And now it's been selected with the Tarantool client.
-</programlisting>
-
-<para xml:id="plugin-postgresql-example">
-<bridgehead renderas="sect4">PostgreSQL Example</bridgehead>
-This example assumes that a recent version of PostgreSQL has been installed.
-The PostgreSQL library and include files are also necessary.
-On Ubuntu they can be installed with <programlisting><prompt>$ </prompt><userinput>sudo apt-get install libpq-dev</userinput></programlisting>
-If that works, then cmake will find the necessary files without requiring any special user input.
-However, because not all platforms are alike, for this example the assumption is
-that the user must check that the appropriate PostgreSQL files are present and
-must explicitly state where they are when building Tarantool from source.
-</para>
-
-<para>
-The example was run on a Linux machine where the base directory
-had a copy of the Tarantool source on ~/tarantool, and
-a copy of PostgreSQL on /usr. The postgres server is already running
-on the local host 127.0.0.1.
-</para>
-
-<programlisting>
-# Check that the include subdirectory exists
-# by looking for /usr/include/postgresql/libpq-fe-h.
-<prompt>$ </prompt><userinput>[ -f /usr/include/postgresql/libpq-fe.h ] && echo "OK" || echo "Error"</userinput>
-OK
-
-# Check that the library subdirectory exists and has the necessary .so file.
-<prompt>$ </prompt><userinput>[ -f /usr/lib/libpq.so ] && echo "OK" || echo "Error"</userinput>
-OK
-
-# Check that the psql client can connect using some factory defaults:
-# port = 5432, user = 'postgres', user password = 'postgres', database = 'postgres'.
-# These can be changed, provided one changes them in all places.
-# Insert a row in database postgres, and quit.
-<prompt>$ </prompt><userinput>psql -h 127.0.0.1 -p 5432 -U postgres -d postgres</userinput>
-Password for user postgres:
-psql (9.3.0, server 9.3.2)
-SSL connection (cipher: DHE-RSA-AES256-SHA, bits: 256)
-Type "help" for help.
-
-<prompt>postgres=#</prompt> <userinput>CREATE TABLE test (s1 INT, s2 VARCHAR(50));</userinput>
-CREATE TABLE
-<prompt>postgres=#</prompt> <userinput>INSERT INTO test VALUES (1,'PostgreSQL row');</userinput>
-INSERT 0 1
-<prompt>postgres=#</prompt> <userinput>\q</userinput>
-<prompt>$ </prompt>
-
-# Build the Tarantool server. Make certain that "cmake" gets the right
-# paths for the PostgreSQL include directory and the PostgreSQL libpq
-# library which were checked earlier.
-<prompt>$ </prompt><userinput>cd ~/tarantool</userinput>
-<prompt>$ </prompt><userinput>make clean</userinput>
-<prompt>$ </prompt><userinput>rm CMakeCache.txt</userinput>
-<prompt>$ </prompt><userinput>cmake . -DWITH_POSTGRESQL=on -DPostgreSQL_LIBRARY=/usr/lib/libpq.so\</userinput>
-<prompt>> </prompt><userinput> -DPostgreSQL_INCLUDE_DIR=/usr/include/postgresql</userinput>
-...
--- Found PostgreSQL: /usr/lib/libpq.so (found version "9.3.2")
-...
--- Configuring done
--- Generating done
--- Build files have been written to: ~/tarantool
-<prompt>$ </prompt><userinput>make</userinput>
-...
-[ 79%] Building CXX object src/plugin/pg/CMakeFiles/pg.dir/pg.cc.o
-Linking CXX shared library libpg.so
-[ 79%] Built target pg
-...
-[100%] Built target man
-<prompt>$ </prompt>
-
-# Change directory to a directory which can be used for temporary tests.
-# For this example we assume that the name of this directory is
-# /home/pgulutzan/tarantool_sandbox. (Change "/home/pgulutzan" to whatever
-# is the actual base directory for the machine that's used for this test.)
-# Now, to help tarantool find the essential mysql.so file, execute these lines:
-<userinput>cd /home/pgulutzan/tarantool_sandbox</userinput>
-<userinput>mkdir box</userinput>
-<userinput>mkdir box/net</userinput>
-<userinput>cp ~/tarantool/src/module/pg/pg.so ./box/net/pg.so</userinput>
-
-# Start the Tarantool server. Do not use a Lua initialization file.
-
-<prompt>$ </prompt><userinput>~/tarantool/src/tarantool</userinput>
-~/tarantool/src/tarantool: version 1.6.3-439-g7e1011b
-type 'help' for interactive help
-<prompt>tarantool> </prompt> <userinput>box.cfg{}</userinput>
-
-# Enter the following lines on the prompt (again, change "/home/pgulutzan"
-# to whatever the real directory is that contains tarantool):
-package.path = "/home/pgulutzan/tarantool/src/module/sql/?.lua;"..package.path
-require("sql")
-if type(box.net.sql) ~= "table" then error("net.sql load failed") end
-require("box.net.pg")
-# ... Make sure that tarantool replies "true" for the calls to "require()".
-
-# Create a Lua function that will connect to the PostgreSQL server,
-# retrieve one row, and display the row.
-# For explanations of the statement types used here, read the
-# Lua tutorial in the Tarantool user manual.
-<prompt>tarantool> </prompt><userinput>console = require('console'); console.delimiter('!')</userinput>
-<prompt>tarantool> </prompt><userinput>function postgresql_select ()</userinput>
- <prompt>-> </prompt><userinput> local dbh = box.net.sql.connect(</userinput>
- <prompt>-> </prompt><userinput> 'pg', '127.0.0.1', 5432, 'postgres', 'postgres', 'postgres')</userinput>
- <prompt>-> </prompt><userinput> local test = dbh:select('SELECT * FROM test WHERE s1 = 1')</userinput>
- <prompt>-> </prompt><userinput> local row = ''</userinput>
- <prompt>-> </prompt><userinput> for i, card in pairs(test) do</userinput>
- <prompt>-> </prompt><userinput> row = row .. card.s2 .. ' '</userinput>
- <prompt>-> </prompt><userinput> end</userinput>
- <prompt> > </prompt><userinput> return row</userinput>
- <prompt>-> </prompt><userinput> end!</userinput>
----
-...
-<prompt>tarantool> </prompt><userinput>console.delimiter('')!</userinput>
-<prompt>tarantool> </prompt>
-
-# Execute the Lua function.
-<prompt>tarantool> </prompt><userinput>postgresql_select()</userinput>
----
-- 'PostgreSQL row '
-...
-
-# Observe the result. It contains "PostgreSQL row".
-# So this is the row that was inserted into the PostgreSQL database.
-# And now it's been selected with the Tarantool client.
-</programlisting>
-
-
-</appendix>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
-
-
-
diff --git a/doc/user/preface.xml b/doc/user/preface.xml
deleted file mode 100644
index 9f56fadea76f5e0cf225fa1cd0e683db05ebfa1d..0000000000000000000000000000000000000000
--- a/doc/user/preface.xml
+++ /dev/null
@@ -1,229 +0,0 @@
-<!DOCTYPE book [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="preface">
-<title>Preface</title>
-<section xml:id="tarantool-overview">
- <title>Tarantool: an overview</title>
- <para>
- <productname>Tarantool</productname> is a Lua application server integrated with a database management system.
- It has a "fiber" model which means that many applications can run simultaneously on a single
- thread, while the Tarantool server can run multiple threads for input-output and background maintenance.
- It integrates the LuaJIT -- "Just In Time" -- Lua compiler, Lua libraries for most common
- applications, and the Tarantool Database Server which is an established
- NoSQL DBMS. Thus it serves all the purposes that have made node.js and Twisted popular in
- other environments, with the additional twist that it has a data persistence level.
- </para>
-
- <para>
- The code is free. The open-source license is <citetitle
- xlink:href="http://www.gnu.org/licenses/license-list.html#ModifiedBSD">BSD
- license</citetitle>. The supported platforms are GNU/Linux, Mac OS
- and FreeBSD.
- </para>
-
- <para>
- Tarantool's creator and biggest user is <citetitle xlink:href="https://en.wikipedia.org/wiki/Mail.ru">Mail.Ru</citetitle>,
- the largest internet company in Russia, with 30 million users, 25 million emails per day,
- and a web site whose Alexa global rank is in the <link xlink:href="http://www.alexa.com/siteinfo/mail.ru">top 40</link> worldwide.
- Tarantool services Mail.Ru's hottest data, such as the session data of online users,
- the properties of online applications, the caches of the underlying data,
- the distribution and sharding algorithms, and much more.
- Outside Mail.Ru the software is used by a growing
- number of projects in online gaming, digital marketing, and social
- media industries. While product development is sponsored by Mail.Ru, the
- roadmap, the bugs database and the development process are fully
- open. The software incorporates patches from dozens of
- community contributors. The Tarantool community writes and maintains
- most of the drivers for programming languages.
- The greater Lua community has hundreds of useful packages
- which can become Tarantool extensions.
- </para>
-
- <para>
- Users can create, modify and drop <emphasis
- role="strong">Lua functions</emphasis> at runtime.
- Or they can define <emphasis role="strong">Lua programs</emphasis>
- that are loaded during startup for triggers, background tasks,
- and interacting with networked peers.
- Unlike popular application development frameworks based on
- a "reactor" pattern, networking in server-side Lua is
- sequential, yet very efficient, as it is built on top of the
- <emphasis role="strong">cooperative multitasking</emphasis>
- environment that Tarantool itself uses.
- A key feature is that the functions
- can access and modify databases atomically.
- Thus some developers look at it as a DBMS with a popular stored procedure language,
- while others look at it as a replacement for multiple components
- of multi-tier Web application architectures.
- Performance is a few thousand transactions per second
- on a laptop, scalable upwards or outwards to server farms.
- </para>
-
- <para>
- <emphasis role="strong">Tarantool is lock-free</emphasis>.
- Instead of the operating system's concurrency primitives, such
- as mutexes, Tarantool uses cooperative
- multitasking to handle thousands of connections simultaneously.
- There is a fixed number of independent execution threads.
- The threads do not share state. Instead they
- exchange data using low-overhead message queues. While this
- approach limits the number of cores that the server will use,
- it removes competition for the memory bus and ensures peak
- scalability of memory access and network throughput.
- CPU utilization of a typical highly-loaded
- Tarantool server is under 10%.
- </para>
-
- <para>
- Although Tarantool can run without it, the database management component is a
- strong distinguishing feature. So here is a closer look at "The Box",
- or DBMS server.
- </para>
-
- <para>
- Ordinarily the server <emphasis role="strong">keeps all the data in
- random-access memory</emphasis>, and therefore has very low read
- latency.
- The server <emphasis role="strong">keeps persistent copies of
- the data in non-volatile storage</emphasis>, such as disk,
- when users request "snapshots". The server <emphasis role="strong">
- maintains a write-ahead log (WAL)</emphasis> to ensure
- consistency and crash safety of the persistent copies.
- The server <emphasis role="strong">performs inserts and updates atomically</emphasis> --
- changes are not considered complete until the WAL is written.
- The logging subsystem supports group commit.
- </para>
-
- <para>
- When the rate of data changes is high, the write-ahead log file
- (or files) can grow quickly. This uses up disk space, and
- increases the time necessary to restart the server (because
- the server must start with the last snapshot, and then replay
- the transactions that are in the log). The solution is to
- make snapshots frequently. Therefore the server ensures that
- <emphasis role="strong">snapshots are quick, resource-savvy, and non-blocking
- </emphasis>. To accomplish this, the server uses delayed garbage
- collection for data pages and uses a copy-on-write technique for
- index pages. This ensures that the snapshot process has a
- consistent read view.
- </para>
-
- <para>
- Unlike most NoSQL DBMSs, Tarantool supports
- <emphasis role="strong">secondary index keys</emphasis> as well as primary keys, and
- <emphasis role="strong">multi-part index keys</emphasis>.
- The possible index types are
- HASH, TREE, BITSET, and RTREE.
- </para>
-
- <para>
- Tarantool supports
- <emphasis role="strong">asynchronous replication</emphasis>,
- locally or to remote hosts.
- In this latest version the replication architecture can be
- <emphasis role="strong">master-master</emphasis>, that is,
- many nodes may both handle the loads and receive what others
- have handled, for the same data sets.
- </para>
-
-
-</section>
-<section xml:id="manual-conventions">
- <title>Conventions</title>
- <para>
- This manual is written in <citetitle
- xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html">DocBook
- 5</citetitle> XML markup language and is using the standard <citetitle
- xlink:href="http://docbook.sourceforge.net/release/xsl/current/doc/">DocBook
- XSL</citetitle> formatting conventions:</para>
- <para>
- UNIX shell command input is prefixed with '$ ' and is in
- a fixed-width font:
- <programlisting><prompt>$ </prompt>tarantool <option>--help</option></programlisting>
- </para>
- <para>
- File names are also in a fixed-width font:
- <programlisting><filename>/path/to/var/dir</filename></programlisting>
- </para>
- <para>
- Text that represents user input is in boldface:
- <programlisting><prompt>$ </prompt><userinput>your input here</userinput></programlisting>
- </para>
- <para>
- Within user input, replaceable items are in italics:
- <programlisting><prompt>$ </prompt><userinput>tarantool <replaceable>--option</replaceable></userinput></programlisting>
- </para>
-</section>
-
-<section xml:id="how-to-read">
- <title>How to read the documentation</title>
- <para>
- To get started, one can either download the whole package as described in
- the first part of Chapter 2 "Getting started", or one can initially skip
- the download and connect to the online Tarantool server running on the web at
- <link xlink:href="http://try.tarantool.org">http://try.tarantool.org</link>.
- Either way, the first tryout can be a matter of following the example
- in the second part of chapter 2: <link linkend="getting-started-start-stop">"Starting Tarantool and making your first
- database"</link>.
- </para>
- <para>
- Chapter 3 <link linkend="lua-and-packages">"Lua and the Tarantool Lua packages"</link> begins with explanations
- about Lua and Tarantool's connection with Lua. Those explanations are
- necessary; however, the detailed instructions about each package can be
- regarded as reference material, skip over them lightly until their
- functionality is needed.
- </para>
- <para>
- Chapter 4 <link linkend="databases">"Databases"</link> is about the Tarantool NoSQL DBMS.
- If the only intent is to use Tarantool as a Lua application server,
- most of the material in this chapter and in the following chapter
- (Chapter 5 <link linkend="replication">"Replication"</link>) will not be necessary. Once again, the
- detailed instructions about each package can be regarded as reference
- material.
- </para>
- <para>
- Chapter 6 <link linkend="server-administration">"Server administration"</link> and Chapter 7 <link linkend="configuration-reference">"Configuration reference"</link>
- are primarily for administrators; however, every user should know
- something about how the server is configured so the section about
- <code>box.cfg</code> is not skippable. Chapter 8 <link linkend="connectors">"Connectors"</link> is strictly for
- users who are connecting from a different language such as C or Perl or
- Python -- other users will find no immediate need for this chapter.
- </para>
- <para>
- The two long tutorials in Appendix C -- <link linkend="lua-tutorial-insert">"Insert one million tuples with a Lua
- stored procedure"</link> and <link linkend="lua-tutorial-sum">"Sum a JSON field for all tuples"</link> -- start
- slowly and contain commentary that is especially aimed at users
- who may not consider themselves experts at either Lua or NoSQL
- database management.
- </para>
- <para>
- Finally, Appendix D <link linkend="plugins">"Plugins"</link> has examples that will be essential
- for those users who want to connect the Tarantool server to another
- DBMS: MySQL or PostgreSQL.
- </para>
- <para>
- For experienced users, there is also a developer's guide
- and an extensive set of comments in the source code.
- </para>
-</section>
-
-<section xml:id="reporting-bugs">
- <title>Reporting bugs</title>
- <para>
- Please report bugs in Tarantool at <link
- xlink:href="http://github.com/tarantool/tarantool/issues"/>. You can
- contact developers directly on the
- <link xlink:href="irc://irc.freenode.net#tarantool">#tarantool</link>
- IRC channel on freenode, or via a mailing list,
- <link xlink:href="https://googlegroups.com/group/tarantool">Tarantool Google group</link>.
- </para>
-</section>
-
-</chapter>
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en
--->
diff --git a/doc/user/proctitle.xml b/doc/user/proctitle.xml
deleted file mode 100644
index a3e5cd19864d714ccefc2cb5dc2dc6c1ac223817..0000000000000000000000000000000000000000
--- a/doc/user/proctitle.xml
+++ /dev/null
@@ -1,66 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE book [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="proctitle">
-
-<title>Server process titles</title>
-
-<para>
- Linux and FreeBSD operating systems allow a running process to
- modify its title, which otherwise contains the program name.
- Tarantool uses this feature to help meet the needs of system
- administration, such as figuring out what services are running
- on a host, their status, and so on.
-</para>
-<para>
- A Tarantool server process title follows the following naming scheme:
- <command><replaceable>program_name</replaceable>: <replaceable>role</replaceable>[@<olink targetptr="custom_proc_title"/>]</command>
-</para>
-<para>
- <emphasis role="strong">program_name</emphasis> is typically
- <command>tarantool</command>. The role can be one of the
- following:
- <itemizedlist>
-
- <listitem><para>
- <emphasis role="strong">running</emphasis> -- ordinary node "ready to accept requests",
- </para></listitem>
- <listitem><para>
- <emphasis role="strong">loading</emphasis> -- ordinary node recovering from old snap and wal files,
- </para></listitem>
- <listitem><para>
- <emphasis role="strong">orphan</emphasis> -- not in a cluster,
- </para></listitem>
- <listitem><para>
- <emphasis role="strong">hot_standby</emphasis> -- see section <olink targetptr="local_hot_standby"/>,
- </para></listitem>
- <listitem><para>
- <emphasis role="strong">dumper + process-id</emphasis> -- saving files before exiting,
- </para></listitem>
- <listitem><para>
- <emphasis role="strong">spawner</emphasis> -- controls other processes,
- </para></listitem>
- <listitem><para>
- <emphasis role="strong">replica + URI/status</emphasis> -- replication node accepting connections on <olink targetptr="replication_port"/>,
- </para></listitem>
- <listitem><para>
- <emphasis role="strong">relay + sockaddr</emphasis> -- serves a single replication connection,
- </para></listitem>
- </itemizedlist>
-</para>
-<para>
-For example:<programlisting><prompt>$</prompt> <userinput>ps -A -f | grep tarantool</userinput>
-1000 17701 2778 0 08:27 pts/0 00:00:00 tarantool: running
-1000 17704 17701 0 08:27 pts/0 00:00:00 tarantool: spawner</programlisting>
-</para>
-</appendix>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
-
diff --git a/doc/user/replication.xml b/doc/user/replication.xml
deleted file mode 100644
index 6ff136b0452322b2797825e84d85bff577bab24f..0000000000000000000000000000000000000000
--- a/doc/user/replication.xml
+++ /dev/null
@@ -1,805 +0,0 @@
-<!DOCTYPE book [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="replication">
-
-<title>Replication</title>
-
-<para>
-Replication allows multiple Tarantool servers to work on
-copies of the same databases. The databases are kept in
-synch because each server can communicate its changes to
-all the other servers. Servers which share the same databases
-are a "cluster". Each server in a cluster also has a numeric
-identifier which is unique within the cluster, known as the
-"server id".
-</para>
-
-<blockquote><para>
- To set up replication, it's necessary to set up the master
- servers which make the original data-change requests,
- set up the replica servers which copy data-change requests
- from masters, and establish procedures for recovery from
- a degraded state.
-</para></blockquote>
-
-<section xml:id="replication-architecture">
- <title>Replication architecture</title>
- <para>
- A replica gets all updates from the master by continuously
- fetching and applying its write-ahead log (WAL).
- Each record in the WAL represents a single Tarantool
- data-change request such as INSERT or UPDATE or DELETE, and is assigned
- a monotonically growing log sequence number (LSN).
- In essence, Tarantool replication is row-based:
- each data change command is fully deterministic and operates
- on a single tuple.
- </para>
- <para>
- A stored program invocation
- <!-- , unless requested explicitly, -->
- is not written to the write-ahead log. Instead, log events
- for actual data-change requests, performed by the Lua code,
- are written to the log. This ensures that possible
- non-determinism of Lua does not cause replication
- to go out of sync.
- </para>
-<!--
- <para>
- It is still sometimes necessary to replicate stored program
- CALLs, rather than their effects: for example, when the
- procedure is fully deterministic and CALL representation in
- the WAL is known to be significantly more compact. Another
- example would be when a procedure is written to do one thing
- on the master, and another on a replica. BOX_RPL_STMT
- flag of the binary protocol can be used
- to replicate CALLs as statements.
- </para>
--->
-
-</section>
-
-<section xml:id="setting-up-the-master">
- <title>Setting up the master</title>
- <para>
- To prepare the master for connections from the replica, it's only
- necessary to include "listen" in the initial <code>box.cfg</code>
- request, for example <code>box.cfg{listen=3301}</code>.
- A master with enabled "listen" <link linkend="URI">URI</link> can accept connections
- from as many replicas as necessary on that URI. Each replica
- has its own replication state.
- </para>
-</section>
-<section xml:id="settin-up-a-replica">
- <title>Setting up a replica</title>
- <para>
- A server requires a valid snapshot (.snap) file.
- A snapshot file is created for a server the first time that
- <code>box.cfg</code> occurs for it.
- If this first <code>box.cfg</code> request occurs without
- a "replication_source" clause, then the server is a master
- and starts its own new cluster with a new unique UUID.
- If this first <code>box.cfg</code> request occurs with
- a "replication_source" clause, then the server is a replica
- and its snapshot file, along with the cluster information,
- is constructed from the write-ahead logs of the master. Therefore,
- to start replication, specify <olink
- targetptr="replication_source"/> in a <code>box.cfg</code> request.
- When a replica contacts a master for the first time, it becomes part of a cluster.
- On subsequent occasions, it should always contact a master in the same cluster.
- </para>
- <para>
- Once connected to the master, the replica requests all changes
- that happened after the latest local LSN. It is therefore
- necessary to keep WAL files on the master host as long as
- there are replicas that haven't applied them yet.
- A replica can be "re-seeded" by deleting all its files (the snapshot .snap file
- and the WAL .xlog files), then starting replication again -- the replica will
- then catch up with the master by retrieving all the master's tuples.
- Again, this procedure works only if the master's WAL files are present.
- </para>
- <note><simpara>
- Replication parameters are "dynamic", which allows the
- replica to become a master and vice versa with the help of the
- <olink targetptr="box.cfg">box.cfg</olink> statement.
- </simpara></note>
- <note><simpara>
- The replica does not inherit the master's configuration parameters,
- such as the ones that cause the <link linkend="snapshot-daemon">snapshot daemon</link>
- to run on the master. To get the same behavior,
- one would have to set the relevant parameters explicitly
- so that they are the same on both master and replica.
- </simpara></note>
-
-</section>
-<section xml:id="recovering-from-a-degraded-state">
- <title>Recovering from a degraded state</title>
- <para>
- "Degraded state" is a situation when the master becomes
- unavailable -- due to hardware or network failure, or due to a
- programming bug. There is no automatic way for a replica to detect
- that the master is gone for good, since sources of failure and
- replication environments vary significantly.
- So the detection of degraded state requires a human inspection.
- </para>
- <para>
- However, once a master failure is detected, the recovery
- is simple: declare that the replica is now the new master,
- by saying <code>box.cfg{... listen=URI}</code>.
- Then, if there are updates on the old master that were not
- propagated before the old master went down, they would have
- to be re-applied manually.
- </para>
- </section>
- <section>
- <title>Instructions for quick startup of a new two-server simple cluster</title>
-<para>
-Step 1. Start the first server thus:<programlisting><userinput>box.cfg{listen=<replaceable>uri#1</replaceable>}</userinput>
-<userinput>box.schema.user.grant('guest','read,write,execute','universe') -- replace with more restrictive request</userinput>
-<userinput>box.snapshot()</userinput></programlisting>... Now a new cluster exists.
-</para>
-<para>
-Step 2. Check where the second server's files will go by looking at
-its directories (<olink targetptr="snap_dir">snap_dir</olink> for snapshot files,
-<olink targetptr="wal_dir">wal_dir</olink> for .xlog files). They must be empty --
-when the second server joins for the first time, it has to
-be working with a clean slate so that the initial copy of
-the first server's databases can happen without conflicts.
-</para>
-<para>
-Step 3. Start the second server thus:<programlisting><userinput>box.cfg{listen=<replaceable>uri#2</replaceable>, replication_source=<replaceable>uri#1</replaceable>}</userinput></programlisting>
-... where uri#1 = the URI that the first server is listening on.
-</para>
-<para>
-That's all.
-</para>
-<para>
-In this configuration, the first server is the "master" and
-the second server is the "replica". Henceforth every change
-that happens on the master will be visible on the replica.
-A simple two-server cluster with the master on one computer
-and the replica on a different computer is very common and
-provides two benefits: FAILOVER (because if the master goes
-down then the replica can take over), or LOAD BALANCING
-(because clients can connect to either the master or the
-replica for select requests).
-</para>
-</section>
-
-<section>
-<title>Master-Master Replication</title>
-<para>
- In the simple master-replica configuration, the master's
- changes are seen by the replica, but not vice versa,
- because the master was specified as the sole replication source.
- Starting with Tarantool 1.6, it's possible to go both ways.
- Starting with the simple configuration, the first server has to say:
- <code>box.cfg{replication_source=<replaceable>uri#2</replaceable>}</code>.
- This request can be performed at any time.
- </para>
- <para>
- In this configuration, both servers are "masters" and
- both servers are "replicas". Henceforth every change
- that happens on either server will be visible on the other.
- The failover benefit is still present, and the load-balancing
- benefit is enhanced (because clients can connect to either
- server for data-change requests as well as select requests).
- </para>
- <para>
- If two operations for the same tuple take place "concurrently"
- (which can involve a long interval because replication is asynchronous),
- and one of the operations is <code>delete</code> or <code>replace</code>,
- there is a possibility that servers will end up with different
- contents.
- </para>
-</section>
-<section>
- <title>All the "What If?" Questions</title>
- <para>
- <emphasis>What if there are more than two servers with master-master?</emphasis>
- ... On each server, specify the replication_source for all
- the others. For example, server #3 would have a request:
- <code>box.cfg{replication_source=<replaceable>uri#1</replaceable>, replication_source=<replaceable>uri#2</replaceable>}</code>.
- </para>
- <para>
- <emphasis>What if a a server should be taken out of the cluster?</emphasis>
- ... Run box.cfg{} again specifying a blank replication source:
- <code>box.cfg{replication_source=''}</code>.
- </para>
- <para>
- <emphasis>What if a server leaves the cluster?</emphasis>
- ... The other servers carry on. If the wayward server rejoins,
- it will receive all the updates that the other servers made
- while it was away.
- </para>
- <para>
- <emphasis>What if two servers both change the same tuple?</emphasis>
- ... The last changer wins. For example, suppose that server#1 changes
- the tuple, then server#2 changes the tuple. In that case server#2's
- change overrides whatever server#1 did. In order to
- keep track of who came last, Tarantool implements a
- <link xlink:href="https://en.wikipedia.org/wiki/Vector_clock">vector clock</link>.
- </para>
- <para>
- <emphasis>What if a master disappears and the replica must take over?</emphasis>
- ... A message will appear on the replica stating that the
- connection is lost. The replica must now become independent,
- which can be done by saying
- <code>box.cfg{replication_source=''}</code>.
- </para>
- <para>
- <emphasis>What if it's necessary to know what cluster a server is in?</emphasis>
- ... The identification of the cluster is a UUID which is generated
- when the first master starts for the first time. This UUID is
- stored in a tuple of the _<code>_cluster</code> system space,
- and in a tuple of the <code>_schema</code> system space. So to
- see it, say:
- <code>box.space._schema:select{'cluster'}</code>
- </para>
- <para>
- <emphasis>What if one of the server's files is corrupted or deleted?</emphasis>
- ... Stop the server, destroy all the database files (the
- ones with extension "snap" or "xlog" or ".inprogress"),
- restart the server, and catch up with the master by contacting it again
- (just say <code>box.cfg{...replication_source=...}</code>).
- </para>
- <para>
- <emphasis>What if replication causes security concerns?</emphasis>
- ... Prevent unauthorized replication sources by associating a password
- with every user that has access privileges for the relevant spaces.
- That way, the <link linkend="URI">URI</link> for the replication_source parameter
- will always have to have the long form <code>replication_source='username:password@host:port'</code>.
- </para>
- </section>
- <section>
- <title>Hands-On Replication Tutorial</title>
- <para>
- After following the steps here,
- an administrator will have experience
- creating a cluster and adding a replica.
- </para>
- <para>
- Start two shells. Put them side by side on the screen.
- <informaltable>
- <tgroup cols="2" align="left" colsep="1" rowsep="0">
- <thead>
- <row><entry>______________TERMINAL #1______________</entry><entry>______________TERMINAL #2______________</entry></row>
- </thead>
- <tbody>
- <row><entry><programlisting><prompt>$</prompt></programlisting></entry>
- <entry><programlisting><prompt>$</prompt></programlisting></entry></row>
- </tbody>
- </tgroup>
- </informaltable>
- On the first shell, which we'll call Terminal #1,
- execute these commands:
-<programlisting>
-<userinput># Terminal 1</userinput>
-<userinput>mkdir -p ~/tarantool_test_node_1</userinput>
-<userinput>cd ~/tarantool_test_node_1</userinput>
-<userinput>rm -R ~/tarantool_test_node_1/*</userinput>
-<userinput>~/tarantool-master/src/tarantool</userinput>
-<userinput>box.cfg{listen=3301}</userinput>
-<userinput>box.schema.user.create('replication', {password = 'password'})</userinput>
-<userinput>box.schema.user.grant('replication','read,write','universe')</userinput>
-<userinput>box.space._cluster:select({0},{iterator='GE'})</userinput>
-</programlisting>
-</para>
-<para>
-The result is that a new cluster is set up, and
-the UUID is displayed.
-Now the screen looks like this: (except that UUID values are always different):
- <informaltable>
- <tgroup cols="2" align="left" colsep="1" rowsep="0">
- <thead>
- <row><entry align="center">TERMINAL #1</entry><entry align="center">TERMINAL #2</entry></row>
- </thead>
- <tbody>
- <row><entry><programlisting>$ <userinput># Terminal 1</userinput>
-$ <userinput>mkdir -p ~/tarantool_test_node_1</userinput>
-$ <userinput>cd ~/tarantool_test_node_1</userinput>
-~/tarantool_test_node_1$ <userinput>rm -R ~/tarantool_test_node_1/*</userinput>
-~/tarantool_test_node_1$ <userinput>~/tarantool-master/src/tarantool</userinput>
-~/tarantool-master/src/tarantool: version 1.6.3-1724-g033ed69
-type 'help' for interactive help
-tarantool> <userinput>box.cfg{listen=3301}</userinput>
-... ...
-tarantool> <userinput>box.schema.user.create('replication', {password = 'password'})</userinput>
-2014-10-13 11:12:56.052 [25018] wal I> creating `./00000000000000000000.xlog.inprogress'
----
-...
-tarantool> <userinput>box.schema.user.grant('replication','read,write','universe')</userinput>
----
-...
-tarantool> <userinput>box.space._cluster:select({0},{iterator='GE'})</userinput>
----
-- - [1, '6190d919-1133-4452-b123-beca0b178b32']
-...
-</programlisting></entry>
- <entry><programlisting>$
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-</programlisting></entry></row>
- </tbody>
- </tgroup>
- </informaltable>
-
-On the second shell, which we'll call Terminal #2,
-execute these commands:<programlisting>
-<userinput># Terminal 2</userinput>
-<userinput>mkdir -p ~/tarantool_test_node_2</userinput>
-<userinput>cd ~/tarantool_test_node_2</userinput>
-<userinput>rm -R ~/tarantool_test_node_2/*</userinput>
-<userinput>~/tarantool-master/src/tarantool</userinput>
-<userinput>box.cfg{listen=3302, replication_source='replication:password@localhost:3301'}</userinput>
-<userinput>box.space._cluster:select({0},{iterator='GE'})</userinput></programlisting>
-The result is that a replica is set up.
-Messages appear on Terminal #1 confirming that the
-replica has connected and that the WAL contents
-have been shipped to the replica.
-Messages appear on Terminal #2 showing that
-replication is starting.
-Also on Terminal#2 the _cluster UUID value is displayed, and it is
-the same as the _cluster UUID value that
-was displayed on Terminal #1, because both
-servers are in the same cluster.
-
- <informaltable>
- <tgroup cols="2" align="left" colsep="1" rowsep="0">
- <thead>
- <row><entry align="center">TERMINAL #1</entry><entry align="center">TERMINAL #2</entry></row>
- </thead>
- <tbody>
- <row><entry><programlisting>... ...
-tarantool> box.space._cluster:select({0},{iterator='GE'})
----
-- - [1, '6190d919-1133-4452-b123-beca0b178b32']
-...
-tarantool> 2014-10-13 11:20:08.691 [25020] main/101/spawner I> created a replication relay: pid = 25583
-2014-10-13 11:20:08.691 [25583] main/101/relay/127.0.0.1:50883 I> recovery start
-2014-10-13 11:20:08.691 [25583] main/101/relay/127.0.0.1:50883 I> recovering from `./00000000000000000000.snap'
-2014-10-13 11:20:08.692 [25583] main/101/relay/127.0.0.1:50883 I> snapshot sent
-2014-10-13 11:20:08.789 [25020] main/101/spawner I> created a replication relay: pid = 25585
-2014-10-13 11:20:08.890 [25585] main/101/relay/127.0.0.1:50884 I> recover from `./00000000000000000000.xlog'
-</programlisting></entry>
-<entry><programlisting><prompt>$</prompt> <userinput># Terminal 2</userinput>
-~/tarantool_test_node_2$ <userinput>mkdir -p ~/tarantool_test_node_2</userinput>
-~/tarantool_test_node_2$ <userinput>cd ~/tarantool_test_node_2</userinput>
-~/tarantool_test_node_2$ <userinput>rm -R ~/tarantool_test_node_2/*</userinput>
-~/tarantool_test_node_2$ <userinput>~/tarantool-master/src/tarantool</userinput>
-/home/username/tarantool-master/src/tarantool: version 1.6.3-1724-g033ed69
-type 'help' for interactive help
-tarantool> <userinput>box.cfg{listen=3302, replication_source='replication:password@localhost:3301'}</userinput>
-... ...
----
-...
-tarantool> <userinput>box.space._cluster:select({0},{iterator='GE'})</userinput>
-2014-10-13 11:20:08.789 [25579] main/103/replica/localhost:3301 C> connected to 127.0.0.1:3301
-2014-10-13 11:20:08.789 [25579] main/103/replica/localhost:3301 I> authenticated
-2014-10-13 11:20:08.901 [25579] wal I> creating `./00000000000000000000.xlog.inprogress'
----
-- - [1, '6190d919-1133-4452-b123-beca0b178b32']
- - [2, '236230b8-af3e-406b-b709-15a60b44c20c']
-...</programlisting></entry></row>
- </tbody>
- </tgroup>
- </informaltable>
-
-On Terminal #1, execute these requests:
-<programlisting><userinput>s = box.schema.space.create('tester')</userinput>
-<userinput>i = s:create_index('primary', {})</userinput>
-<userinput>s:insert{1,'Tuple inserted on Terminal #1'}</userinput></programlisting>
-Now the screen looks like this:
- <informaltable>
- <tgroup cols="2" align="left" colsep="1" rowsep="0">
- <thead>
- <row><entry align="center">TERMINAL #1</entry><entry align="center">TERMINAL #2</entry></row>
- </thead>
- <tbody>
- <row><entry><programlisting>... ...
-tarantool> 2014-10-13 11:20:08.691 [25020] main/101/spawner I> created a replication relay: pid = 25583
-2014-10-13 11:20:08.691 [25583] main/101/relay/127.0.0.1:50883 I> recovery start
-2014-10-13 11:20:08.691 [25583] main/101/relay/127.0.0.1:50883 I> recovering from `./00000000000000000000.snap'
-2014-10-13 11:20:08.692 [25583] main/101/relay/127.0.0.1:50883 I> snapshot sent
-2014-10-13 11:20:08.789 [25020] main/101/spawner I> created a replication relay: pid = 25585
-2014-10-13 11:20:08.890 [25585] main/101/relay/127.0.0.1:50884 I> recover from `./00000000000000000000.xlog'
----
-...
-tarantool> <userinput>s = box.schema.space.create('tester')</userinput>
----
-...
-tarantool> <userinput>i = s:create_index('primary', {})</userinput>
----
-...
-tarantool> <userinput>s:insert{1,'Tuple inserted on Terminal #1'}</userinput>
----
-- [1, 'Tuple inserted on Terminal #1']
-...
-</programlisting></entry>
- <entry><programlisting><prompt>$ # Terminal 2
-~/tarantool_test_node_2$ mkdir -p ~/tarantool_test_node_2
-~/tarantool_test_node_2$ cd ~/tarantool_test_node_2
-~/tarantool_test_node_2$ rm -R ~/tarantool_test_node_2/*
-~/tarantool_test_node_2$ ~/tarantool-master/src/tarantool
-/home/username/tarantool-master/src/tarantool: version 1.6.3-1724-g033ed69
-type 'help' for interactive help
-tarantool> box.cfg{listen=3302, replication_source='replication:password@localhost:3301'}
-... ...
----
-...
-tarantool> box.space._cluster:select({0},{iterator='GE'})
-2014-10-13 11:20:08.789 [25579] main/103/replica/localhost:3301 C> connected to 127.0.0.1:3301
-2014-10-13 11:20:08.789 [25579] main/103/replica/localhost:3301 I> authenticated
-2014-10-13 11:20:08.901 [25579] wal I> creating `./00000000000000000000.xlog.inprogress'
-
----
-- - [1, '6190d919-1133-4452-b123-beca0b178b32']
- - [2, '236230b8-af3e-406b-b709-15a60b44c20c']
-...</prompt></programlisting></entry></row>
- </tbody>
- </tgroup>
- </informaltable>
-
-The creation and insertion were successful on Terminal #1.
-Nothing has happened on Terminal #2.
-</para>
-<para>
-On Terminal #2, execute these requests:<programlisting>
-<userinput>s = box.space.tester</userinput>
-<userinput>s:select({1},{iterator='GE'})</userinput>
-<userinput>s:insert{2,'Tuple inserted on Terminal #2'}</userinput></programlisting>
-Now the screen looks like this:
-
- <informaltable>
- <tgroup cols="2" align="left" colsep="1" rowsep="0">
- <thead>
- <row><entry align="center">TERMINAL #1</entry><entry align="center">TERMINAL #2</entry></row>
- </thead>
- <tbody>
- <row><entry><programlisting><prompt>...
-tarantool> 2014-10-13 11:20:08.691 [25020] main/101/spawner I> created a replication relay: pid = 25583
-2014-10-13 11:20:08.691 [25583] main/101/relay/127.0.0.1:50883 I> recovery start
-2014-10-13 11:20:08.691 [25583] main/101/relay/127.0.0.1:50883 I> recovering from `./00000000000000000000.snap'
-2014-10-13 11:20:08.692 [25583] main/101/relay/127.0.0.1:50883 I> snapshot sent
-2014-10-13 11:20:08.789 [25020] main/101/spawner I> created a replication relay: pid = 25585
-2014-10-13 11:20:08.890 [25585] main/101/relay/127.0.0.1:50884 I> recover from `./00000000000000000000.xlog'
----
-...
-tarantool> s = box.schema.space.create('tester')
----
-...
-tarantool> i = s:create_index('primary', {})
----
-...
-tarantool> s:insert{1,'Tuple inserted on Terminal #1'}
----
-- [1, 'Tuple inserted on Terminal #1']
-...</prompt></programlisting></entry>
- <entry><programlisting>... ...
-tarantool> box.space._cluster:select({0},{iterator='GE'})
-2014-10-13 11:20:08.789 [25579] main/103/replica/localhost:3301 C> connected to 127.0.0.1:3301
-2014-10-13 11:20:08.789 [25579] main/103/replica/localhost:3301 I> authenticated
-2014-10-13 11:20:08.901 [25579] wal I> creating `./00000000000000000000.xlog.inprogress'
----
-- - [1, '6190d919-1133-4452-b123-beca0b178b32']
- - [2, '236230b8-af3e-406b-b709-15a60b44c20c']
-...
-tarantool> <userinput>s = box.space.tester</userinput>
----
-...
-tarantool> <userinput>s:select({1},{iterator='GE'})</userinput>
----
-- - [1, 'Tuple inserted on Terminal #1']
-...
-tarantool> <userinput>s:insert{2,'Tuple inserted on Terminal #2'}</userinput>
----
-- [2, 'Tuple inserted on Terminal #2']
-...
-</programlisting></entry></row>
- </tbody>
- </tgroup>
- </informaltable>
-
-The selection and insertion were successful on Terminal #2.
-Nothing has happened on Terminal #1.
-</para>
-<para>
-On Terminal #1, execute these Tarantool requests and shell commands:<programlisting>
-<userinput>os.exit()</userinput>
-<userinput>ls -l ~/tarantool_test_node_1</userinput>
-<userinput>ls -l ~/tarantool_test_node_2</userinput></programlisting>
-Now Tarantool #1 is stopped.
-Messages appear on Terminal #2 announcing that fact.
-The "ls -l" commands show that both servers have
-made snapshots, which have the same size because
-they both contain the same tuples.
-
- <informaltable>
- <tgroup cols="2" align="left" colsep="1" rowsep="0">
- <thead>
- <row><entry align="center">TERMINAL #1</entry><entry align="center">TERMINAL #2</entry></row>
- </thead>
- <tbody>
- <row><entry><programlisting>... ...
-tarantool> s:insert{1,'Tuple inserted on Terminal #1'}
----
-- [1, 'Tuple inserted on Terminal #1']
-...
-tarantool> <userinput>os.exit()</userinput>
-2014-10-13 11:45:20.455 [25585] main/101/relay/127.0.0.1:50884 I> done `./00000000000000000000.xlog'
-2014-10-13 11:45:20.531 [25020] main/101/spawner I> Exiting: master shutdown
-2014-10-13 11:45:20.531 [25020] main/101/spawner I> sending signal 15 to 1 children
-2014-10-13 11:45:20.531 [25020] main/101/spawner I> waiting for children for up to 5 seconds
-~/tarantool_test_node_1$ <userinput>ls -l ~/tarantool_test_node_1</userinput>
-total 8
--rw-rw-r-- 1 1781 Oct 13 11:12 00000000000000000000.snap
--rw-rw-r-- 1 518 Oct 13 11:45 00000000000000000000.xlog
-~/tarantool_test_node_1$ <userinput>ls -l ~/tarantool_test_node_2/</userinput>
-total 8
--rw-rw-r-- 1 1781 Oct 13 11:20 00000000000000000000.snap
--rw-rw-r-- 1 588 Oct 13 11:38 00000000000000000000.xlog
-~/tarantool_test_node_1$
-</programlisting></entry>
- <entry><programlisting><prompt>... ...
-tarantool> s:select({1},{iterator='GE'})
----
-- - [1, 'Tuple inserted on Terminal #1']
-...
-tarantool> s:insert{2,'Tuple inserted on Terminal #2'}
----
-- [2, 'Tuple inserted on Terminal #2']
-...
-tarantool> 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> can't read row
-2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 !> SystemError
-unexpected EOF when reading from socket,
-called on fd 10, aka 127.0.0.1:50884, peer of 127.0.0.1:3301: Broken pipe
-2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> will retry every 1 second
-</prompt></programlisting></entry></row>
- </tbody>
- </tgroup>
- </informaltable>
-
-On Terminal #2, ignore the repeated messages saying "failed to connect", and execute these requests:<programlisting>
-<userinput>box.space.tester:select({0},{iterator='GE'})</userinput>
-<userinput>box.space.tester:insert{3,'Another'}</userinput></programlisting>
-Now the screen looks like this (ignoring the repeated messages saying "failed to connect"):
- <informaltable>
- <tgroup cols="2" align="left" colsep="1" rowsep="0">
- <thead>
- <row><entry align="center">TERMINAL #1</entry><entry align="center">TERMINAL #2</entry></row>
- </thead>
- <tbody>
- <row><entry><programlisting><prompt>... ...
-tarantool> s:insert{1,'Tuple inserted on Terminal #1'}
----
-- [1, 'Tuple inserted on Terminal #1']
-...
-tarantool> os.exit()
-2014-10-13 11:45:20.455 [25585] main/101/relay/127.0.0.1:50884 I> done `./00000000000000000000.xlog'
-2014-10-13 11:45:20.531 [25020] main/101/spawner I> Exiting: master shutdown
-2014-10-13 11:45:20.531 [25020] main/101/spawner I> sending signal 15 to 1 children
-2014-10-13 11:45:20.531 [25020] main/101/spawner I> waiting for children for up to 5 seconds
-~/tarantool_test_node_1$ ls -l ~/tarantool_test_node_1
-total 8
--rw-rw-r-- 1 1781 Oct 13 11:12 00000000000000000000.snap
--rw-rw-r-- 1 518 Oct 13 11:45 00000000000000000000.xlog
-~/tarantool_test_node_1$ ls -l ~/tarantool_test_node_2/
-total 8
--rw-rw-r-- 1 1781 Oct 13 11:20 00000000000000000000.snap
--rw-rw-r-- 1 588 Oct 13 11:38 00000000000000000000.xlog
-~/tarantool_test_node_1$
-</prompt></programlisting></entry>
- <entry><programlisting>... ...
-tarantool> s:insert{2,'Tuple inserted on Terminal #2'}
----
-- [2, 'Tuple inserted on Terminal #2']
-...
-tarantool> 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> can't read row
-2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 !> SystemError
-unexpected EOF when reading from socket,
-called on fd 10, aka 127.0.0.1:50884, peer of 127.0.0.1:3301: Broken pipe
-2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> will retry every 1 second
-tarantool> <userinput>box.space.tester:select({0},{iterator='GE'})</userinput>
----
-- - [1, 'Tuple inserted on Terminal #1']
- - [2, 'Tuple inserted on Terminal #2']
-...
-tarantool> <userinput>box.space.tester:insert{3,'Another'}</userinput>
----
-- [3, 'Another']
-...
-</programlisting></entry></row>
- </tbody>
- </tgroup>
- </informaltable>
-
-Terminal #2 has done a select and an insert,
-even though Terminal #1 is down.
-</para>
-<para>
-On Terminal #1 execute these commands:<programlisting>
-<userinput>~/tarantool-master/src/tarantool</userinput>
-<userinput>box.cfg{listen=3301}</userinput>
-<userinput>box.space.tester:select({0},{iterator='GE'})</userinput></programlisting>
-Now the screen looks like this (ignoring the repeated messages on terminal #2 saying "failed to connect"):
- <informaltable>
- <tgroup cols="2" align="left" colsep="1" rowsep="0">
- <thead>
- <row><entry align="center">TERMINAL #1</entry><entry align="center">TERMINAL #2</entry></row>
- </thead>
- <tbody>
- <row><entry><programlisting>... ...
-tarantool> s:insert{1,'Tuple inserted on Terminal #1'}
----
-- [1, 'Tuple inserted on Terminal #1']
-...
-tarantool> os.exit()
-2014-10-13 11:45:20.455 [25585] main/101/relay/127.0.0.1:50884 I> done `./00000000000000000000.xlog'
-2014-10-13 11:45:20.531 [25020] main/101/spawner I> Exiting: master shutdown
-2014-10-13 11:45:20.531 [25020] main/101/spawner I> sending signal 15 to 1 children
-2014-10-13 11:45:20.531 [25020] main/101/spawner I> waiting for children for up to 5 seconds
-~/tarantool_test_node_1$ ls -l ~/tarantool_test_node_1
-total 8
--rw-rw-r-- 1 1781 Oct 13 11:12 00000000000000000000.snap
--rw-rw-r-- 1 518 Oct 13 11:45 00000000000000000000.xlog
-~/tarantool_test_node_1$ ls -l ~/tarantool_test_node_2/
-total 8
--rw-rw-r-- 1 1781 Oct 13 11:20 00000000000000000000.snap
--rw-rw-r-- 1 588 Oct 13 11:38 00000000000000000000.xlog
-~/tarantool_test_node_1$ <userinput>~/tarantool-master/src/tarantool</userinput>
-/home/username/tarantool-master/src/tarantool: version 1.6.3-515-g0a06cce
-type 'help' for interactive help
-tarantool> <userinput>box.cfg{listen=3301}</userinput>
-... ...
----
-...
-tarantool> <userinput>box.space.tester:select({0},{iterator='GE'})</userinput>
-2014-10-13 12:01:55.615 [28989] main/101/spawner I> created a replication relay: pid = 28992
-2014-10-13 12:01:55.716 [28992] main/101/relay/127.0.0.1:51892 I> recover from `./00000000000000000000.xlog'
-2014-10-13 12:01:55.716 [28992] main/101/relay/127.0.0.1:51892 I> done `./00000000000000000000.xlog'
----
-- - [1, 'Tuple inserted on Terminal #1']
-...
-</programlisting></entry>
- <entry><programlisting><prompt>... ...
-tarantool> s:insert{2,'Tuple inserted on Terminal #2'}
----
-- [2, 'Tuple inserted on Terminal #2']
-...
-tarantool> 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> can't read row
-2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 !> SystemError
-unexpected EOF when reading from socket,
-called on fd 10, aka 127.0.0.1:50884, peer of 127.0.0.1:3301: Broken pipe
-2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> will retry every 1 second
-tarantool> box.space.tester:select({0},{iterator='GE'})
----
-- - [1, 'Tuple inserted on Terminal #1']
- - [2, 'Tuple inserted on Terminal #2']
-...
-tarantool> box.space.tester:insert{3,'Another'}
----
-- [3, 'Another']
-...
-tarantool>
-2014-10-13 12:01:55.614 [25579] main/103/replica/localhost:3301 C> connected to 127.0.0.1:3301
-2014-10-13 12:01:55.614 [25579] main/103/replica/localhost:3301 I> authenticated
-</prompt></programlisting></entry></row>
- </tbody>
- </tgroup>
- </informaltable>
-
-
-The master has reconnected to the cluster,
-and has NOT found what the replica wrote
-while the master was away. That is not a
-surprise -- the replica has not been asked
-to act as a replication source.
-</para>
-<para>
-On Terminal #1, say:<programlisting>
-<userinput>box.cfg{replication_source='replication:password@localhost:3302'}</userinput>
-<userinput>box.space.tester:select({0},{iterator='GE'})</userinput></programlisting>
-The screen now looks like this:
- <informaltable>
- <tgroup cols="2" align="left" colsep="1" rowsep="0">
- <thead>
- <row><entry align="center">TERMINAL #1</entry><entry align="center">TERMINAL #2</entry></row>
- </thead>
- <tbody>
- <row><entry><programlisting>... ...
-~/tarantool_test_node_1$ ~/tarantool-master/src/tarantool
-~/tarantool: version 1.6.3-1724-g033ed69
-type 'help' for interactive help
-tarantool> box.cfg{listen=3301}
-... ...
----
-...
-tarantool> box.space.tester:select({0},{iterator='GE'})
-2014-10-13 12:01:55.615 [28989] main/101/spawner I> created a replication relay: pid = 28992
-2014-10-13 12:01:55.716 [28992] main/101/relay/127.0.0.1:51892 I> recover from `./00000000000000000000.xlog'
-2014-10-13 12:01:55.716 [28992] main/101/relay/127.0.0.1:51892 I> done `./00000000000000000000.xlog'
-
----
-- - [1, 'Tuple inserted on Terminal #1']
-...
-tarantool> <userinput>box.cfg{replication_source='replication:password@localhost:3302'}</userinput>
-2014-10-13 12:10:21.485 [28987] main/101/interactive C> starting replication from localhost:3302
----
-...
-2014-10-13 12:10:21.487 [28987] main/104/replica/localhost:3302 C> connected to 127.0.0.1:3302
-2014-10-13 12:10:21.487 [28987] main/104/replica/localhost:3302 I> authenticated
-tarantool> <userinput>box.space.tester:select({0},{iterator='GE'})</userinput>
-2014-10-13 12:10:21.592 [28987] wal I> creating `./00000000000000000006.xlog.inprogress'
-2014-10-13 12:10:21.617 [28992] main/101/relay/127.0.0.1:51892 I> recover from `./00000000000000000006.xlog'
----
-- - [1, 'Tuple inserted on Terminal #1']
- - [2, 'Tuple inserted on Terminal #2']
- - [3, 'Another']
-...
-</programlisting></entry>
- <entry><programlisting><prompt>... ...
- tarantool> s:insert{2,'Tuple inserted on Terminal #2'}
----
-- [2, 'Tuple inserted on Terminal #2']
-...
-tarantool> 2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> can't read row
-2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 !> SystemError
-unexpected EOF when reading from socket,
-called on fd 10, aka 127.0.0.1:50884, peer of 127.0.0.1:3301: Broken pipe
-2014-10-13 11:45:20.532 [25579] main/103/replica/localhost:3301 I> will retry every 1 second
-tarantool> box.space.tester:select({0},{iterator='GE'})
----
-- - [1, 'Tuple inserted on Terminal #1']
- - [2, 'Tuple inserted on Terminal #2']
-...
-tarantool> box.space.tester:insert{3,'Another'}
----
-- [3, 'Another']
-...
-tarantool>
-2014-10-13 12:01:55.614 [25579] main/103/replica/localhost:3301 C> connected to 127.0.0.1:3301
-2014-10-13 12:01:55.614 [25579] main/103/replica/localhost:3301 I> authenticated
-2014-10-13 12:10:21.488 [25581] main/101/spawner I> created a replication relay: pid = 29632
-2014-10-13 12:10:21.592 [29632] main/101/relay/127.0.0.1:45908 I> recover from `./00000000000000000000.xlog'
-</prompt></programlisting></entry></row>
- </tbody>
- </tgroup>
- </informaltable>
-
-This shows that the two servers are once
-again in synch, and that each server sees
-what the other server wrote.
-</para>
-<para>
-To clean up, say "os.exit()" on both
-Terminal #1 and Terminal #2, and then
-on either terminal say:<programlisting>
-<userinput>cd ~</userinput>
-<userinput>rm -R ~/tarantool_test_node_1</userinput>
-<userinput>rm -R ~/tarantool_test_node_2</userinput></programlisting>
-</para>
-
-
-</section>
-
-</chapter>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/server-administration.xml b/doc/user/server-administration.xml
deleted file mode 100644
index fc95264abb70bbdf5872c48cbe4e4326cd21cf55..0000000000000000000000000000000000000000
--- a/doc/user/server-administration.xml
+++ /dev/null
@@ -1,467 +0,0 @@
-<!DOCTYPE book [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="server-administration">
-<title>Server administration</title>
-<para>
- Typical server administration tasks include starting and stopping
- the server, reloading configuration, taking snapshots, log rotation.
-</para>
-<section xml:id="signal-handling">
-<title>Server signal handling</title>
-<para>
- The server is configured to shut down gracefully on SIGTERM and
- SIGINT (keyboard interrupt) or SIGHUP. SIGUSR1 can be used to
- save a snapshot.
- All other signals are blocked or ignored.
- The signals are processed in the main event loop. Thus, if the
- control flow never reaches the event loop (thanks to a runaway stored
- procedure), the server stops responding to any signal, and
- can only be killed with SIGKILL (this signal can not be ignored).
-</para>
-</section>
-
-<section xml:id="utility-tarantool">
-
-<title>Utility <code>tarantool</code> — using the server as a client</title>
-
-<para>
-If <code>tarantool</code> is started without an initialization file, then
-there will be a prompt ("<code>tarantool></code>") and it will be possible
-to enter requests. When used this way, <code>tarantool</code> is a client
-program as well as a server program.
-</para>
-<para>
-This section shows all legal syntax for the tarantool program, with short notes and examples.
-Other client programs may have similar options and request syntaxes.
-Some of the information in this section is duplicated in the Configuration Reference chapter.
-</para>
-
-<para>
-<bridgehead renderas="sect4">Conventions used in this section</bridgehead>
-
-Tokens are character sequences which are treated as syntactic units within requests.
-
-Square brackets <code>[</code> and <code>]</code> enclose optional syntax.
-Three dots in a row <code>...</code> mean the preceding tokens may be repeated.
-A vertical bar <code>|</code> means the preceding and following tokens are mutually exclusive alternatives.
-</para>
-
-<para>
-<bridgehead renderas="sect4">Options when starting client from the command line</bridgehead>
-
-General form: <code>tarantool</code> or <code>tarantool <replaceable>file-name</replaceable></code>
-or <code>tarantool <replaceable>option</replaceable>... </code>.
-</para>
-<para>
-File-name can be any script containing code for initializing.
-Effect: The code in the file is executed during startup.
-Example: <code>init.lua</code>.
-Notes: If a script is used, there will be no prompt. The script should contain
-configuration information including "box.cfg{...listen=...}" or "box.listen(...)" so
-that a separate program can connect to the server via one of the ports.
-</para>
-<para>
-Option is one of the following (in alphabetical order by the long form of the option):
-</para>
-
-<variablelist>
- <varlistentry>
- <term xml:id="utility-tarantool-help" xreflabel="utility-tarantool-help">--help</term>
- <listitem><para>
- Syntax: short form: <code>-?</code>
- long form: <code>--h[elp]</code>.
- Effect: Client displays a help message including a list of options.
- Example: <code>--help</code>
- Notes: The program stops after displaying the help.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="utility-tarantool-version" xreflabel="utility-tarantool-version">--version</term>
- <listitem><para>
- Syntax: short form: <code>-V</code>
- long form: <code>--v[ersion]</code>.
- Effect: Client displays version information.
- Example: <code>--version</code>
- Notes: The program stops after displaying the version.
- </para></listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-<bridgehead renderas="sect4">Tokens, requests, and special key combinations</bridgehead>
-</para>
-
-<para>
-Procedure identifiers are: Any sequence of letters, digits, or underscores which is
- legal according to the rules for Lua identifiers.
- Procedure identifiers are also called function names.
- Notes: function names are case insensitive so <code>insert</code> and <code>Insert</code> are not the same thing.
-</para>
-<para>
-String literals are: Any sequence of zero or more characters enclosed in single quotes.
- Double quotes are legal but single quotes are preferred.
- Enclosing in double square brackets is good for multi-line strings as described in
- <link xlink:href="http://www.lua.org/pil/2.4.html">Lua documentation</link>.
- Examples: 'Hello, world', 'A', [[A\B!]].
-</para>
-<para>
-Numeric literals are: Character sequences containing only digits, optionally preceded by + or -.
- Examples: 55, -.
- Notes: Tarantool NUM data type is unsigned, so -1 is understood as a large unsigned number.
-</para>
-<para>
-Single-byte tokens are: * or , or ( or ).
- Examples: * , ( ).
-</para>
-<para>
-Tokens must be separated from each other by one or more spaces, except that
-spaces are not necessary around single-byte tokens or string literals.
-</para>
-
-<para xml:id="utility-tarantool-delim">
-<bridgehead renderas="sect4">Requests</bridgehead>
-Generally requests are entered following the prompt in interactive mode while
-tarantool is running. (A prompt will be the word tarantool and a greater-than
-sign, for example <code>tarantool></code>). The end-of-request marker is
-by default a newline (line feed).
-</para>
-<para>
-For multi-line requests, it is possible to change the end-of-request marker.
-Syntax: <code>console = require('console'); console.delimiter(<replaceable>string-literal</replaceable>)</code>.
-The string-literal must be a value in single quotes.
-Effect: string becomes end-of-request delimiter, so newline alone is not treated as end of request.
-To go back to normal mode: <code>console.delimiter('')<replaceable>string-literal</replaceable></code>.
-Example:<programlisting>console = require('console'); console.delimiter('!')
-function f ()
- statement_1 = 'a'
- statement_2 = 'b'
- end!
-console.delimiter('')!</programlisting>
-</para>
-
-<para>
-For a condensed Backus-Naur Form [BNF] description of the suggested form of client requests, see
- <link xlink:href="http://tarantool.org/doc/box-protocol.html"><filename>doc/box-protocol.html</filename></link>
- and
- <link xlink:href="https://github.com/tarantool/tarantool/blob/master/doc/sql.txt"><filename>doc/sql.txt</filename></link>.
-</para>
-
-
-<para>
-In <emphasis>interactive</emphasis> mode, one types requests and gets results.
-Typically the requests
-are typed in by the user following prompts.
-Here is an example of an interactive-mode tarantool client session:
-
-<programlisting>
-<prompt>$ </prompt><userinput>tarantool</userinput>
- [ tarantool will display an introductory message including version number here ]
-tarantool> <userinput>box.cfg{listen=3301}</userinput>
- [ tarantool will display configuration information here ]
-tarantool> <userinput>s = box.schema.space.create('tester')</userinput>
- [ tarantool may display an in-progress message here ]
----
-...
-tarantool> <userinput>s:create_index('primary', {type = 'hash', parts = {1, 'NUM'}})</userinput>
----
-...
-tarantool> <userinput>box.space.tester:insert{1,'My first tuple'}</userinput>
----
-- [1, 'My first tuple']
-...
-tarantool> <userinput>box.space.tester:select(1)</userinput>
----
-- - [1, 'My first tuple']
-...
-tarantool> <userinput>box.space.tester:drop()</userinput>
----
-...
-tarantool> <userinput>os.exit()</userinput>
-2014-04-30 10:28:00.886 [20436] main/101/spawner I> Exiting: master shutdown
-<prompt>$ </prompt>
-</programlisting>
-Explanatory notes about what tarantool displayed in the above example:
-</para>
-<para>
-* Many requests return typed objects.
- In the case of "box.cfg{listen=3301}",
- this result is displayed on the screen.
- If the request had assigned the result to a variable, for example
- "c = box.cfg{listen=3301}", then
- the result would not have been displayed on the screen.
-</para>
-<para>
-* A display of an object always begins with "---" and ends with "...".
-</para>
-<para>
-* The insert request returns an object of type = tuple, so the object display line
- begins with a single dash ('- '). However, the select request returns
- an object of type = <emphasis>table of tuples</emphasis>, so the object display line
- begins with two dashes ('- - ').
-</para>
-
-</section>
-
-<section xml:id="tarantoolctl">
-<title>Utility <code>tarantoolctl</code></title>
-<para>
-With tarantoolctl one can say: "start an instance of the
-Tarantool server which runs a single user-written Lua
-program, allocating disk resources specifically for
-that program, via a standardized deployment method."
-If Tarantool was downloaded from source, then the script
-is in ~/extra/dist/tarantoolctl. If Tarantool was installed
-with Debian or Red Hat installation packages, the script
-is renamed <code>tarantoolctl</code> and is in
-/usr/bin/tarantoolctl. The script handles such things as:
-starting, stopping, rotating logs, logging in to the
-application's console, and checking status.
-</para>
-
-<bridgehead renderas="sect4">configuring for tarantoolctl</bridgehead>
-<para>
-The tarantoolctl script will read a configuration file
-named /etc/sysconfig/tarantool, or /etc/default/tarantool.
-Most of the settings are similar to the settings
-used by <code>box.cfg{...}</code>; however, tarantoolctl
-adjusts some of them by adding an application name.
-A copy of /etc/sysconfig/tarantool, with defaults for
-all settings, would look like this:<programlisting>
-default_cfg = {
- pid_file = "/var/run/tarantool",
- wal_dir = "/var/ lib / tarantool",
- snap_dir = "/var/lib/tarantool",
- sophia_dir = "/var/lib/tarantool",
- logger = "/var/log/tarantool",
- username = "tarantool",
-}
-instance_dir = "/etc/tarantool/instances.enabled"</programlisting>
-</para>
-<para>
-The settings in the above script are:
-</para>
-<para>
-pid_file = The directory for the pid file and control-socket file.
-The script will add "/<replaceable>instance-name</replaceable>" to the directory name.
-</para>
-<para>
-wal_dir = The directory for the write-ahead *.xlog files.
-The script will add "/<replaceable>instance-name</replaceable>" to the directory-name.
-</para>
-<para>
-snap_dir = The directory for the snapshot *.snap files.
-The script will add "/<replaceable>instance-name</replaceable>" to the directory-name.
-</para>
-<para>
-sophia_dir = The directory for the sophia-storage-engine files.
-The script will add "/sophia/<replaceable>instance-name</replaceable>" to the directory-name.
-</para>
-<para>
-logger = The place where the application log will go.
-The script will add /<replaceable>instance-name</replaceable>.log" to the name.
-</para>
-<para>
-username = the user that runs the tarantool server.
-This is the operating-system user name rather than the Tarantool-client user name.
-</para>
-<para>
-instance_dir = the directory where all applications for this host are stored.
-The user who writes an application for tarantoolctl must put the application's
-source code in this directory, or a symbolic link. For examples in this section the application
-name <code>my_app</code> will be used, and its source will have to be in
-<code><replaceable>instance_dir</replaceable>/my_app.lua</code>.
-</para>
-
-<bridgehead renderas="sect4">commands for tarantoolctl</bridgehead>
-<para>
-The command format is <code>tarantoolctl <replaceable>operation</replaceable> application-name</code>,
-where <replaceable>operation</replaceable> is one of: <code>start</code>, <code>stop</code>,
-<code>status</code>, <code>logrotate</code>, <code>enter</code>. Thus ...<programlisting>
-tarantoolctl start my_app -- starts application my_app
-tarantoolctl stop my_app -- stops my_app
-tarantoolctl enter my_app -- show my_app's admin console, if it has one
-tarantoolctl logrotate my_app -- rotate my_app's log files (make new, remove old)
-tarantoolctl status my_app -- check my_app's status</programlisting>
-</para>
-
-<bridgehead renderas="sect4">typical code snippets for tarantoolctl</bridgehead>
-<para>
-A user can check whether my_app is running with these lines:<programlisting>
- if tarantoolctl status my_app; then
- ...
- fi</programlisting>
-A user can initiate, for boot time, an init.d set of instructions:<programlisting>
- for (each file mentioned in the instance_dir directory):
- tarantoolctl start `basename $ file .lua`</programlisting>
-A user can set up a further configuration file for log rotation, like this:<programlisting>
-/path/to/tarantool/*.log {
- daily
- size 512k
- missingok
- rotate 10
- compress
- delaycompress
- create 0640 tarantool adm
- postrotate
- /path/to/tarantoolctl logrotate `basename $ 1 .log`
- endscript
-}</programlisting>
-</para>
-
-<bridgehead renderas="sect4">A detailed example for tarantoolctl</bridgehead>
-<para>
-The example's objective is: make a temporary directory
-where tarantoolctl can start a long-running application
-and monitor it.
-</para>
-<para>
-The assumptions are: the root password is known,
-the computer is only being used for tests,
-the Tarantool server is ready to run but is
-not currently running, and
-there currently is no directory named tarantool_test.
-</para>
-<para>
-Create a directory named /tarantool_test:<programlisting>
-sudo mkdir /tarantool_test</programlisting>
-</para>
-<para>
-Copy tarantoolctl to /tarantool_test.
-If you made a source download to ~/tarantool-master, then<programlisting>
-sudo cp ~/tarantool-master/extra/dist/tarantoolctl /tarantool_test/tarantoolctl</programlisting>
-If the file was named tarantoolctl and placed on /usr/bin/tarantoolctl, then<programlisting>
-sudo cp /usr/bin/tarantoolctl /tarantool_test/tarantoolctl</programlisting>
-</para>
-<para>
-Check and possibly change the first line of /tarantool_test/tarantoolctl.
-Initially it says<programlisting>
-#!/usr/bin/env tarantool</programlisting>
-If that is not correct, edit tarantoolctl and change the line.
-For example, if the Tarantool server is actually on
-/home/user/tarantool-master/src/tarantool, change the line to<programlisting>
-#!/usr/bin/env /home/user/tarantool-master/src/tarantool</programlisting>
-</para>
-<para>
-Save a copy of /etc/sysconfig/tarantool, if it exists.
-</para>
-<para>
-Edit /etc/sysconfig/tarantool.
-It might be necessary to say sudo mkdir /etc/sysconfig first.
-Let the new file contents be:<programlisting>
-default_cfg = {
- pid_file = "/tarantool_test/my_app.pid",
- wal_dir = "/tarantool_test",
- snap_dir = "/tarantool_test",
- sophia_dir = "/tarantool_test",
- logger = "/tarantool_test/log",
- username = "tarantool",
-}
-instance_dir = "/tarantool_test"</programlisting>
-</para>
-<para>
-Make the my_app application file, that is, /tarantool_test/my_app.lua.
-Let the file contents be:<programlisting>
-box.cfg{listen = 3301}
-box.schema.user.passwd('Gx5!')
-box.schema.user.grant('guest','read,write,execute','universe')
-fiber = require('fiber')
-box.schema.space.create('tester')
-box.space.tester:create_index('primary',{})
-i = 0
-while 0 == 0 do
- fiber.sleep(5)
- i = i + 1
- print('insert ' .. i)
- box.space.tester:insert{i, 'my_app tuple'}
-end</programlisting>
-</para>
-<para>
-Tell tarantoolctl to start the application ...<programlisting>
-cd /tarantool_test
-sudo ./tarantoolctl start my_app</programlisting>
-... expect to see messages indicating that the instance has started. Then ...<programlisting>
-ls -l /tarantool_test/my_app</programlisting>
-... expect to see the .snap file, .xlog file, and sophia directory. Then ...<programlisting>
-less /tarantool_test/log/my_app.log</programlisting>
-... expect to see the contents of my_app's log, including error messages, if any. Then ...<programlisting>
-cd /tarantool_test
-#assume that 'tarantool' invokes the tarantool server
-sudo tarantool
-box.cfg{}
-console = require('console')
-console.connect('localhost:3301')
-box.space.tester:select({0},{iterator='GE'})</programlisting>
-... expect to see several tuples that my_app has created.
-</para>
-<para>
-Stop. The only clean way to stop my_app is with tarantoolctl, thus:<programlisting>
-sudo ./tarantoolctl stop my_app</programlisting>
-</para>
-<para>
-Clean up. Restore the original contents of /etc/sysconfig/tarantool, and ...<programlisting>
-cd /
-sudo rm -R tarantool_test</programlisting>
-</para>
-
-</section>
-
-<section xml:id="os-install-notes">
-<title>System-specific administration notes</title>
-<blockquote><para>
- This section will contain information about issue or features which exist
- on some platforms but not others -- for example, on certain versions of a
- particular Linux distribution.
-</para></blockquote>
-
- <section xml:id="Debian">
- <title>Administrating with Debian GNU/Linux and Ubuntu</title>
- <para>
- Setting up an instance: ln -s /etc/tarantool/instances.available/instance-name.cfg /etc/tarantool/instances.enabled/
- </para>
- <para>
- Starting all instances: service tarantool start
- </para>
- <para>
- Stopping all instances: service tarantool stop
- </para>
- <para>
- Starting/stopping one instance: service tarantool-instance-name start/stop
- </para>
- </section>
- <section xml:id="rpm-based-distros">
- <title>Fedora, RHEL, CentOS</title>
- <para>
- There are no known permanent issues.
- For transient issues, go to <link xlink:href="https://github.com/tarantool/tarantool/issues">http://github.com/tarantool/tarantool/issues</link> and enter "RHEL" or "CentOS" or "Fedora" or "Red Hat" in the search box.
- </para>
- </section>
-
- <section xml:id="FreeBSD">
- <title>FreeBSD</title>
- <para>
- There are no known permanent issues.
- For transient issues, go to <link xlink:href="https://github.com/tarantool/tarantool/issues">http://github.com/tarantool/tarantool/issues</link> and enter "FreeBSD" in the search box.
- </para>
- </section>
-
- <section xml:id="mac-os-x">
- <title>Mac OS X</title>
- <para>
- There are no known permanent issues.
- For transient issues, go to <link xlink:href="https://github.com/tarantool/tarantool/issues">http://github.com/tarantool/tarantool/issues</link> and enter "OS X" in the search box.
- </para>
- </section>
-
-</section>
-
-</chapter>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/space.xml b/doc/user/space.xml
deleted file mode 100644
index e89e93ea998d95b28c755563531d19e2a4e698f9..0000000000000000000000000000000000000000
--- a/doc/user/space.xml
+++ /dev/null
@@ -1,101 +0,0 @@
-<para xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="space">
-<bridgehead>Space settings explained</bridgehead>
-Space is a composite parameter, that is, it has properties.
-<programlisting language="cpp">
-/*
- * Each tuple consists of fields. Field types may be
- * integers, floats, or strings.
- * Tarantool is interested in field types only inasmuch as
- * it needs to build indexes on fields. Two indexed field
- * types are supported.
-enum { STR, NUM } field_type;
- * An index can cover one or more fields.
- */
-
-struct index_field_t {
- unsigned int fieldno;
- enum field_type type;
-};
-
-/*
- * HASH and TREE and BITSET index types are supported.
- */
-
-enum { HASH, TREE, BITSET } index_type;
-
-struct index_t {
- index_field_t key_field[];
- enum index_type type;
- /* Secondary index may be non-unique */
- bool unique;
-};
-
-struct space_t
-{
- /* A space can be quickly disabled and re-enabled at run time. */
- bool enabled;
- /*
- * If cardinality is given, each tuple in the space must have exactly
- * this many fields.
- */
- unsigned int arity;
- /* estimated_rows is only used for HASH indexes, to preallocate memory. */
- unsigned int estimated_rows;
- struct index_t index[];
-};
-</programlisting>
-The way a space is defined in a configuration file is similar to how
-one would initialize a C structure in a program. For example,
-a minimal storage configuration looks like the following:
-<programlisting language="c">
-space[0].enabled = 1
-space[0].index[0].type = HASH
-space[0].index[0].unique = 1
-space[0].index[0].key_field[1].fieldno = 1
-space[0].index[0].key_field[1].type = NUM64
-</programlisting>
-The parameters listed above are mandatory. Other space
-properties are set in the same way.
-An alternative syntax, mainly useful when defining large spaces, exists:
-<programlisting language="c">
-space[0] = {
- enabled = 1,
- index = [
- {
- type = HASH,
- key_field = [
- {
- fieldno = 1,
- type = NUM64
- }
- ]
- }
- ]
-}
-</programlisting>
-When defining a space,
-please be aware of these restrictions:
-<itemizedlist>
- <listitem><simpara>at least one space must be
- configured,</simpara></listitem>
- <listitem><simpara>each configured space needs at least one
- unique index,
- </simpara></listitem>
- <listitem><simpara>"unique" property doesn't have a default, and
- must be set explicitly,
- </simpara></listitem>
- <listitem><simpara>space configuration can not be changed
- dynamically, currently you need to restart the server even to
- disable or enable a space,
- </simpara></listitem>
- <listitem><simpara>HASH indexes can not be non-unique.
- </simpara></listitem>
-</itemizedlist>
-</para>
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/stored-procedures.xml b/doc/user/stored-procedures.xml
deleted file mode 100644
index 8206cc55e0ce99f7837e2bdb4951e82141c971a7..0000000000000000000000000000000000000000
--- a/doc/user/stored-procedures.xml
+++ /dev/null
@@ -1,3443 +0,0 @@
-<!DOCTYPE section [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<section xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="stored-procedures">
- <title>Writing and running Lua code</title>
-
- <para>
- Procedures can be defined and invoked interactively, for example:
- <programlisting><computeroutput>tarantool> <userinput>function f1() return 'hello' end</userinput>
----
-...
-tarantool> <userinput>f1()</userinput>
----
-- hello
-...
-</computeroutput>
-</programlisting>
- In the above example, the requests are being handled in interactive mode
- for evaluation as a chunk of Lua code.
- </para>
- <para>
- Thus, the request "<code>function f1() return 'hello' end</code>"
- causes definition of the Lua function which will be identified as f1().
- Then the request "<code>f1()</code>" causes execution of
- the function. The function returns a string 'hello', which gets displayed.
- </para>
- <para>
- It's possible to execute any chunk of Lua code, not just invoke functions ...
- <programlisting><computeroutput>tarantool> <userinput>1 + 2</userinput>
----
- - 3
-...
-tarantool> <userinput>'hello' .. ' world' -- '..' means 'concatenate'</userinput>
----
- - hello world
-...
-</computeroutput></programlisting>
- </para>
- <para>
- Lua functions could also be called at the time of initialization with a script in a
- <olink targetptr="configuration-file">lua-initialization file</olink>.
- An example and discussion of such a script will appear later in section
- <link linkend="sp-expirationd">expirationd</link>.
- </para>
- <para>
- The initialization script can select and modify data.
- </para>
- <para>
- Another common task to perform in the initialization script
- is to start background fibers for data expiration, re-sharding,
- or communication with networked peers.
- </para>
- <para>
- Finally, the script can be used to define Lua <olink
- targetptr="triggers">triggers</olink> invoked on various events
- within the system.
- </para>
- <note><simpara>
- TARANTOOL = A SCRIPT PROCESSOR. Instead of processing scripts with bash or Perl, use tarantool server.
- For example, let the first line of a shell script be #!/usr/bin/tarantool.
- This will be a
- (<link xlink:href="https://en.wikipedia.org/wiki/Shebang_%28Unix%29" xlink:title="wikipedia.org/Shebang">"Hashbang" hint</link>)
- that Tarantool will be the script processor. Since Tarantool includes Lua, the file's instructions can be Lua.
- </simpara></note>
- <para>
- There is a single global instance of the Lua interpreter, which is
- shared across all connections. Any request from a client
- is sent
- directly to this interpreter. Any changes of the interpreter
- state, including global variable values, have immediate
- effect on all client connections.
- </para>
- <para>
- However, each connection uses its own Lua
- <emphasis>coroutine</emphasis> — a mechanism akin to a
- Tarantool <emphasis>fiber</emphasis>. A coroutine has its
- own execution stack and its own set of local variables and
- definitions, as described in the
- <link xlink:href="http://www.lua.org/pil/6.1.html">
- <emphasis>closure</emphasis> section</link> of the Lua manual.
- </para>
- <para>
- In addition to conventional method invocation,
- Lua provides object-oriented syntax. Typically this involves
- the format <computeroutput><replaceable>object-specifier</replaceable>:<replaceable>function-name ...</replaceable></computeroutput>,
- where object-specifier is acquired as the result of another function invocation,
- or is the full <replaceable>library-name.package-name.object-name</replaceable>,
- or is the full <replaceable>library-name.package-name['object-name']</replaceable>,
- or is the full <replaceable>library-name.package-name[object-numeric-id]</replaceable>.
- The following example shows all four forms of object-specifier:
-<programlisting>
-tarantool> <userinput>s = box.schema.space.create('name_of_space', {id = 33})</userinput>
----
-...
-tarantool> <userinput>i = s:create_index('name_of_index', {type = 'tree', parts = {1, 'STR'}})</userinput>
----
-...
-tarantool> <userinput>s:insert{'a', 'b', 'c'}</userinput>
----
-- ['a', 'b', 'c']
-...
-tarantool> <userinput>box.space.name_of_space:insert{'c', 'd', 'e'}</userinput>
----
-- ['c', 'd', 'e']
-...
-tarantool> <userinput>box.space['name_of_space']:insert{'x', 'y', 'z'}</userinput>
----
-- ['x', 'y', 'z']
-...
-</programlisting>
- </para>
- <para>
- When a function in Lua terminates with an error, the error
- is sent to the client as <olink targetptr="ER_PROC_LUA" />
- return code, along with the original error message.
- Similarly, an error which has occurred inside Tarantool (observed on the
- client as an error code), when it happens during execution of a
- Lua procedure, produces a genuine Lua error:
-<programlisting><computeroutput>tarantool> <userinput>function f()error('!') end</userinput>
----
-...
-tarantool> <userinput>f()</userinput>
-- error: '[string "function f()error(''!'') end"]:1: !'
-tarantool> <userinput>s:insert{5}</userinput>
----
-- error: 'Tuple field 1 type does not match one required by operation:
- expected STR'
-...
-tarantool> <userinput>function insert_without_colon(tuple) s:insert(tuple) end</userinput>
----
-...
-tarantool> <userinput>pcall(insert_without_colon,{0, 'b', 'c'})</userinput>
----
-- false
-- 'Tuple field 1 type does not match one required by operation: expected STR'
-tarantool> <userinput>box.space[33]:drop()</userinput>
----
-...
-</computeroutput></programlisting>
- </para>
-
-<para>
-<bridgehead renderas="sect4">The "Batteries Included" Lua Software Distribution</bridgehead>
-Tarantool incorporates open-source
-precompiled packages which Tarantool's developers
-have tested for compatibility -- the "built-in" packages.
-Tarantool specializes in packages which aid
-database applications or which Tarantool's own developers
-use to make database-related tools.
-At the same time.
-Tarantool makes it easy to add new Lua packages
-from <link xlink:href=" http://luarocks.org/">LuaRocks</link> -- the "downloadable" packages.
-</para>
-
-<para>
-The included language processor is <link xlink:href="http://luajit.org/">LuaJIT</link>.
-Major "built-in" components are: fibers,
-<link xlink:href="http://msgpack.org">MsgPack</link>,
-digest, JSON, <link xlink:href="http://en.wikipedia.org/wiki/Yaml">YAML</link>,
-<link xlink:href="http://en.wikipedia.org/wiki/Inter-process_communication">IPC</link>,
-fio, and box.
-</para>
-
-<para>
-<emphasis>LuaJIT</emphasis> is a processor for the entire Lua language.
-This differs from the original Lua interpreter from
-<link xlink:href="http://www.puc-rio.br/index.html">PontifÃcia Universidade Católica do Rio de Janeiro</link>
-("RIO-PUC" <link xlink:href="http://www.lua.org/">Lua</link>)
-because the JIT stands for "Just In Time" compiling, that
-is, it can compile some Lua code into machine executable form
-after a few executions of the code.
-The result is that some
-loops will run as quickly as an equivalent C program.
-Also some precompiled C code can be brought in using
-LuaJIT's FFI (<link xlink:href="https://en.wikipedia.org/wiki/Foreign_function_interface">Foreign Function Interface</link>).
-Examples for using FFI exist on the Internet, for example
-<link xlink:href="https://github.com/tarantool/tarantool/blob/master/src/box/lua/tuple.lua">tuple.lua</link> on the tarantool.org site.
-</para>
-
-<para>
-LuaJIT has been compared to competitive implementations
-and found to be reliable and efficient,
-provided one takes advantage of it where <link xlink:href="http://wiki.luajit.org/Numerical-Computing-Performance-Guide">performance</link> counts.
-</para>
-
- <para>
- Apart from increased performance, LuaJIT provides such
- features as <link
- xlink:href="http://bitop.luajit.org/">bitwise
- operations</link> and <link xlink:href="#tonumber64">64-bit integer arithmetic.</link>
- </para>
-
-<para>
-<link linkend="sp-box-fiber"><emphasis>Fibers</emphasis></link> are like Lua coroutines, but as <link xlink:href="http://members.chello.nl/~w.couwenberg/fibers.htm">one fiber developer</link>
-put it: "The main difference between a coroutine and a fiber
-is that a running fiber can be suspended anywhere in a call
-chain, regardless of its C and Lua call stack nesting levels."
-</para>
-
-<para>
-<link linkend="sp-msgpack"><emphasis>MsgPack</emphasis></link> is a relatively new way to serialize data.
-The point of MsgPack is that it can
-handle Lua types and C types, with structures and nesting,
-without the overhead of an SGML-style markup language.
-</para>
-
-<para>
-<link linkend="sp-digest"><emphasis>Digest</emphasis></link> is a cryptography package for CRC32, SHA, and MDA.
-Nothing new here -- except that Tarantool has made them into a
-package, so that one doesn't have to get each one of these
-things individually from the <link xlink:href="http://lua-users.org/wiki/CryptographyStuff">many that are available</link>.
-And, since Tarantool is binding with FFI rather than a traditional Lua C
-API, the routines should run faster on LuaJIT.
-</para>
-
-<para>
-<link linkend="sp-box-cjson"><emphasis>JSON</emphasis></link> is a serialization format which has
-become popular in the web world. The package within
-Tarantool is derived from <link xlink:href="http://www.kyne.com.au/~mark/software/lua-cjson-manual.html">CJSON</link>
-which, according to <link xlink:href="http://lua-users.org/wiki/JsonModules">a survey</link>,
-handles Unicode surrogate pairs and is robust when
-edge cases come up.
-</para>
-
-<para>
-<link linkend="sp-yaml"><emphasis>YAML</emphasis></link> is short for "YAML Ain't a Markup Language". YAML is a
-way to show data in human-readable form, without losing
-underlying information about typing, arrays, and structures.
-</para>
-
-<para>
-<link linkend="sp-fiber-ipc"><emphasis>IPC</emphasis></link> is Inter-Process Communication.
-This is useful for implementations of task queues and long polling.
-</para>
-
-<para>
-<link linkend="sp-fio"><emphasis>Fio</emphasis></link> is standard file IO,
-adapted to work with Tarantool's fibers in a cooperative environment.
-</para>
-
-<para>
-<link linkend="sp-tap"><emphasis>Tap</emphasis></link> is a tool to test programs for errors.
-</para>
-
-<para>
-<link linkend="sp-box-library"><emphasis>Box</emphasis></link> is the NoSQL DBMS that was developed by Tarantool
-and its community. Box's architecture and routines will be the
-subject of the next chapter.
-</para>
-
-<para>
-<bridgehead renderas="sect4">The Downloadable Packages</bridgehead>
-A directory of Lua Addons packages can be found on the <link xlink:href="http://lua-users.org/wiki/LuaAddons">Lua-users</link> wiki.
-For a "managed package" system equivalent to Perl's CPAN and Ruby's RubyGems and Python's
-Eggs, one gets "rocks" (modules or packages) from <emphasis>LuaRocks</emphasis>.
-Either way, the installation requirement can be as simple as saying
-require('package-name')
-and the effect is a simple Lua table containing
-functions and members, superficially like C/Java classes.
-</para>
-
-<para>
-There are <link xlink:href="https://rocks.moonscript.org/modules">several hundred LuaRocks packages</link> that are not built-in
-but are reasonably easy to obtain by anyone with an Internet
-connection. Just as a sampling: ...
-<link xlink:href="https://rocks.moonscript.org/modules/kikito/ansicolors">ansicolors</link> for color manipulation,
-<link xlink:href="https://rocks.moonscript.org/modules/luarocks/htmlparser">htmlparser</link> for changing HTML text into a tree of elements,
-<link xlink:href="https://rocks.moonscript.org/modules/kikito/i18n">i18n</link> an internationalization library,
-<link xlink:href="https://rocks.moonscript.org/modules/luarocks/lposix">lposix</link> a POSIX library,
-<link xlink:href="https://rocks.moonscript.org/modules/luarocks/lua-spore">lua-Spore</link> a generic ReST client,
-<link xlink:href="https://rocks.moonscript.org/modules/luarocks/tekui">TekUI</link> a GUI toolkit.
-For example, to bring in the i18n package: install luarocks, say <code>luarocks install i18n</code>,
-start Tarantool, and say <code>require('i18n')</code>.
-</para>
-
-<section xml:id="rocks"><title>Installing rocks from tarantool.org</title>
-<para>
-The Lua rocks that Tarantool supplies are available
-on <link xlink:href="http://rocks.tarantool.org">rocks.tarantool.org</link> and can be installed using
-the luarocks utilities. Here is an example.
-</para>
-<para>
-Look at rocks.tarantool.org. Notice that one of the
-available rocks is expirationd -- Expiration daemon for Tarantool.
-</para>
-<para>
-Create a file named ~/.luarocks/config.lua containing these three lines:<programlisting>
-rocks_servers = {
- [[http://rocks.tarantool.org/]]
-}</programlisting>
-Install the expirationd rock with either <programlisting>luarocks --local install expirationd</programlisting>
-or, as root user, <programlisting>luarocks install expirationd</programlisting>
-Start the tarantool server and make the request:<programlisting>expirationd=require('expirationd')</programlisting>
-If there is an error, display the Lua variable
-<code>package_path</code> to make sure it is searching along
-a path that includes the new expirationd.lua file.
-</para>
-<para>
-If the result is success, which it will be if
-nothing unusual has been done when installing
-Tarantool or Luarocks, then the new rock is
-available henceforward for use in the Tarantool
-application server.
-</para>
-
-<para>
-The rest of this chapter is a reference that has what's needed for programming and
-administration with the built-in packages.
-</para>
-</section>
-
-<section xml:id="sp-digest">
- <title>Package <code>digest</code></title>
- <para>
- A "digest" is a value which is returned by a
-
- <link xlink:href="https://en.wikipedia.org/wiki/Cryptographic_hash_function">Cryptographic hash function</link>
- applied against a string.
- Tarantool supports five types of cryptographic hash functions
- (<link xlink:href="https://en.wikipedia.org/wiki/Md4">MD4</link>,
- <link xlink:href="https://en.wikipedia.org/wiki/Md5">MD5</link>,
- <link xlink:href="https://en.wikipedia.org/wiki/Sha-0">SHA-0</link>,
-
- <link xlink:href="https://en.wikipedia.org/wiki/Sha-1">SHA-1</link>,
- <link xlink:href="https://en.wikipedia.org/wiki/Sha-2">SHA-2</link>)
-
- as well as a checksum function
- (<link xlink:href="https://en.wikipedia.org/wiki/Cyclic_redundancy_check">CRC32</link>)
- and two functions for <link xlink:href="https://en.wikipedia.org/wiki/Base64">base64</link>.
- The functions in <code>digest</code> are:
- <informaltable>
- <tgroup cols="2" align="left" colsep="1" rowsep="0">
- <thead>
- <row><entry>name</entry><entry>effect</entry></row>
- </thead>
- <tbody>
- <row><entry><code>digest.crc32(<replaceable>string</replaceable>)</code></entry><entry> Returns 32-bit checksum made with CRC32. See <link linkend="note-crc32">note</link>.</entry></row>
- <row><entry><code>digest.crc32_update(<replaceable>number</replaceable>,<replaceable>string</replaceable>)</code></entry><entry> Returns update of a checksum calculated with CRC32.</entry></row>
- <row><entry><code>digest.sha(<replaceable>string</replaceable>)</code></entry><entry> Returns 160-bit digest made with SHA-0. Not recommended.</entry></row>
- <row><entry><code>digest.sha_hex(<replaceable>string</replaceable>)</code></entry><entry> Returns hexadecimal of a digest calculated with sha.</entry></row>
- <row><entry><code>digest.sha1(<replaceable>string</replaceable>)</code></entry><entry> Returns 160-bit digest made with SHA-1.</entry></row>
- <row><entry><code>digest.sha1_hex(<replaceable>string</replaceable>)</code></entry><entry> Returns hexadecimal of a digest calculated with sha1.</entry></row>
- <row><entry><code>digest.sha224(<replaceable>string</replaceable>)</code></entry><entry> Returns 224-bit digest made with SHA-2.</entry></row>
- <row><entry><code>digest.sha224_hex(<replaceable>string</replaceable>)</code></entry><entry> Returns hexadecimal of a digest calculated with sha224.</entry></row>
- <row><entry><code>digest.sha256(<replaceable>string</replaceable>)</code></entry><entry> Returns 256-bit digest made with SHA-2.</entry></row>
- <row><entry><code>digest.sha256_hex(<replaceable>string</replaceable>)</code></entry><entry> Returns hexadecimal of a digest calculated with sha256.</entry></row>
- <row><entry><code>digest.sha384(<replaceable>string</replaceable>)</code></entry><entry> Returns 384-bit digest made with SHA-2.</entry></row>
- <row><entry><code>digest.sha384_hex(<replaceable>string</replaceable>)</code></entry><entry> Returns hexadecimal of a digest calculated with sha384.</entry></row>
- <row><entry><code>digest.sha512(<replaceable>string</replaceable>)</code></entry><entry> Returns 512-bit digest made with SHA-2.</entry></row>
- <row><entry><code>digest.sha512_hex(<replaceable>string</replaceable>)</code></entry><entry> Returns hexadecimal of a digest calculated with sha512.</entry></row>
- <row><entry><code>digest.md4(<replaceable>string</replaceable>)</code></entry><entry> Returns 128-bit digest made with MD4.</entry></row>
- <row><entry><code>digest.md4_hex(<replaceable>string</replaceable>)</code></entry><entry> Returns hexadecimal of a digest calculated with md4.</entry></row>
- <row><entry><code>digest.md5(<replaceable>string</replaceable>)</code></entry><entry> Returns 256-bit digest made with MD5.</entry></row>
- <row><entry><code>digest.md5_hex(<replaceable>string</replaceable>)</code></entry><entry> Returns hexadecimal of a digest calculated with md5.</entry></row>
- <row><entry><code>digest.base64_encode(<replaceable>string</replaceable>)</code></entry><entry> Returns base64 encoding from a regular string.</entry></row>
- <row><entry><code>digest.base64_decode(<replaceable>string</replaceable>)</code></entry><entry> Returns a regular string from a base64 encoding.</entry></row>
- <row><entry><code>digest.urandom(<replaceable>integer</replaceable>)</code></entry><entry> Returns array of random bytes with length = <replaceable>integer</replaceable>.</entry></row>
- <row><entry><code>digest.guava(<replaceable>integer, integer</replaceable>)</code></entry><entry> Returns a number made with consistent hash. See <link linkend="note-guava">note</link>.</entry></row>
- </tbody>
- </tgroup>
- </informaltable>
- <note xml:id="note-crc32"><simpara>
- <code>digest.crc32(<replaceable>string</replaceable>)</code> uses the
- <link xlink:href="https://en.wikipedia.org/wiki/Cyclic_redundancy_check#Standards_and_common_use">
- CRC-32C (Castagnoli)</link> polynomial value: hexadecimal 11EDC6F41 / decimal 4812730177.
- If it is necessary to be compatible with other checksum functions in other programming languages,
- ensure that the other functions use the same polynomial value.
- For example, in Python, install the crcmod package and say:
- <code>import crcmod ... fun = crcmod.mkCrcFun('4812730177') ... fun('string')</code>.
- </simpara></note>
- <note xml:id="note-guava"><simpara>
- <code>digest.guava(<replaceable>integer, integer</replaceable>)</code> uses the
- <link xlink:href="https://en.wikipedia.org/wiki/Consistent_hashing">
- Consistent Hashing</link> algorithm of the Google guava library.
- The first parameter should be a hash code; the second parameter should be the number of buckets;
- the returned value will be an integer between 0 and the number of buckets.
- For example, <code>digest.guava(10863919174838991, 11)</code> will return 8.
- </simpara></note>
-
- </para>
-<bridgehead renderas="sect4">Example</bridgehead>
- <para>
- In the following example, the user creates two functions, password_insert()
- which inserts a SHA-1 digest of the word "^S^e^c^ret Wordpass" into a tuple set,
- and password_check() which requires input of a password.<programlisting>
-<prompt>localhost></prompt> <userinput>digest = require('digest')</userinput>
-<prompt>localhost></prompt> <userinput>console = require('console'); console.delimiter('!') --this means ignore line feeds until next '!'</userinput>
-<prompt>localhost></prompt> <userinput>function password_insert()</userinput>
- <prompt>-></prompt> <userinput> box.space.tester:insert{12345,digest.sha1('^S^e^c^ret Wordpass')}</userinput>
- <prompt>-></prompt> <userinput> return 'OK'</userinput>
- <prompt>-></prompt> <userinput> end!</userinput>
----
-...
-<prompt>localhost></prompt> <userinput>function password_check(password)</userinput>
- <prompt>-></prompt> <userinput> local t</userinput>
- <prompt>-></prompt> <userinput> t=box.space.tester:select{12345}</userinput>
- <prompt>-></prompt> <userinput> if (digest.sha1(password)==t[2]) then</userinput>
- <prompt>-></prompt> <userinput> print('Password is valid')</userinput>
- <prompt>-></prompt> <userinput> else</userinput>
- <prompt>-></prompt> <userinput> print('Password is not valid')</userinput>
- <prompt>-></prompt> <userinput> end</userinput>
- <prompt>-></prompt> <userinput>end!</userinput>
----
-...
-<prompt>localhost></prompt> <userinput>password_insert()!</userinput>
-Call OK, 1 rows affected
-['OK']
-<prompt>localhost></prompt> <userinput>console.delimiter('') -- back to normal: commands end with line feed!</userinput>
-</programlisting></para>
-<para>
- If a later user calls
- the password_check() function and enters the wrong password, the result is an
- error.<programlisting><prompt>localhost></prompt> <userinput>password_check ('Secret Password')</userinput>
----
-Password is not valid
-...</programlisting></para>
-</section>
-
-<section xml:id="sp-box-uuid">
- <title>Package <code>uuid</code></title>
-
-<para>
- A "UUID" is a
- <link xlink:href="https://en.wikipedia.org/wiki/Universally_unique_identifier">Universally unique identifier</link>.
- If an application requires that a value be unique only within a single computer or
- on a single database, then a simple counter is better than a UUID, because getting
- a UUID is time-consuming (it requires a
- <link xlink:href="https://en.wikipedia.org/wiki/Syscall">syscall</link>).
- For clusters of computers, or widely distributed applications, UUIDs are better.
-</para>
-<para>
- The functions that can return a UUID are: <code>uuid()</code>, <code>uuid.bin()</code>, <code>uuid.str()</code>.
- The functions that can convert between different types of UUID are: <code>:bin()</code>, <code>:str()</code>, <code>uuid.fromstr()</code>, <code>uuid.frombin()</code>.
- The function that can determine whether a UUID is an all-zero value is: <code>:isnil()</code>.
-</para>
-
-<variablelist xml:id="x-uuid" xreflabel="x-uuid">
-
- <varlistentry>
- <term>
- <emphasis role="lua">uuid()</emphasis>
- </term>
- <listitem>
- <para>
- Returns: a UUID with type = cdata.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">uuid.bin()</emphasis>
- </term>
- <listitem>
- <para>
- Returns: a UUID with type = 16-byte binary string.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">uuid.str()</emphasis>
- </term>
- <listitem>
- <para>
- Returns: a UUID with type = 36-byte hexadecimal string.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua"><replaceable>uuid_with_type_cdata</replaceable>:bin([<replaceable>byte-order</replaceable>])</emphasis>
- </term>
- <listitem>
- <para>
- Parameters: byte-order can be 'l' (little-endian), 'b' (big-endian), 'h' (endianness depends on host) (default), or 'n' (endianness depends on network).
- </para>
- <para>
- Returns: UUID with type = 16-byte binary string converted from cdata input value.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua"> <replaceable>uuid_with_type_cdata</replaceable>:str()</emphasis>
- </term>
- <listitem>
- <para>
- Returns: UUID with type = 36-byte hexadecimal string converted from cdata input value.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua"> uuid.fromstr(<replaceable>uuid_with_type_string</replaceable>)</emphasis>
- </term>
- <listitem>
- <para>
- Returns: UUID with type = cdata converted from 36-byte hexadecimal string input value.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">uuid.frombin(<replaceable>uuid_with_type_binary_string</replaceable>)</emphasis>
- </term>
- <listitem>
- <para>
- Returns: UUID with type = cdata converted from 16-byte binary string input value.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua"><replaceable>uuid_with_type_cdata</replaceable>:isnil()</emphasis>
- </term>
- <listitem>
- <para>
- Returns: true if the value is all zero, otherwise false.
- The all-zero UUID value can be expressed as <code>uuid.NULL</code>, or as
- uuid.fromstr('00000000-0000-0000-0000-000000000000').
- The comparison with an all-zero value can also be expressed as
- <replaceable>uuid_with_type_cdata</replaceable> == uuid.NULL.
- </para>
- </listitem>
- </varlistentry>
-
-</variablelist>
-<para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-tarantool> <userinput>uuid = require('uuid')</userinput>
----
-...
-tarantool> <userinput>uuid(), uuid.bin(), uuid.str()</userinput>
----
-- 16ffedc8-cbae-4f93-a05e-349f3ab70baa
-- !!binary FvG+Vy1MfUC6kIyeM81DYw==
-- 67c999d2-5dce-4e58-be16-ac1bcb93160f
-...
-tarantool> <userinput>uu = uuid()</userinput>
----
-...
-tarantool> <userinput>#uu:bin(), #uu:str(), type(uu), uu:isnil()</userinput>
----
-- 16
-- 36
-- cdata
-- false
-...
-</programlisting>
-</para>
-
-</section>
-
-<section xml:id="sp-box-cjson">
- <title>Package <code>json</code></title>
-
-<variablelist xml:id="box.cjson" xreflabel="box.cjson">
- <para>
- The <code>json</code> package provides JSON manipulation routines.
- It is based on the <link xlink:href="http://www.kyne.com.au/~mark/software/lua-cjson.php">
- Lua-CJSON package by Mark Pulford</link>.
-
- For a complete manual on Lua-CJSON please read <link xlink:href="http://www.kyne.com.au/~mark/software/lua-cjson-manual.html">the official documentation</link>.
- </para>
- <varlistentry>
- <term><emphasis role="lua">json.encode(<replaceable>scalar-value | Lua-table-value</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Convert a Lua object to a JSON string.
- </para>
- <para>
- Parameters: either a scalar value or a Lua table value.
- </para>
- <para>
- Returns: (type = string) the original value reformatted as a JSON string.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-tarantool> <userinput>json=require('json')</userinput>
----
-...
-tarantool> <userinput>json.encode(123)</userinput>
----
-- '123'
-...
-tarantool> <userinput>json.encode({123})</userinput>
----
-- '[123]'
-...
-tarantool> <userinput>json.encode({123, 234, 345})</userinput>
----
-- '[123,234,345]'
-...
-tarantool> <userinput>json.encode({abc = 234, cde = 345})</userinput>
----
-- '{"cde":345,"abc":234}'
-...
-tarantool> <userinput>json.encode({hello = {'world'}})</userinput>
----
-- '{"hello":["world"]}'
-...
-</programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua">json.decode(<replaceable>string-value</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Convert a JSON string to a Lua object.
- </para>
- <para>
- Parameters: <code>string-value</code> = a string formatted as JSON.
- </para>
- <para>
- Returns: (type = Lua table) the original contents formatted as a Lua table.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>json=require('json')</userinput>
----
-...
-tarantool> <userinput>json.decode('123')</userinput>
----
-- 123
-...
-tarantool> <userinput>json.decode('[123, "hello"]')[2]</userinput>
----
-- hello
-...
-tarantool> <userinput>json.decode('{"hello": "world"}').hello</userinput>
----
-- world
-...
-</programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua" xml:id="json-null" xreflabel="json-null">json.NULL</emphasis></term>
- <listitem>
- <para>
- Return a value comparable to Lua "nil" which may be useful as a placeholder in a tuple or Lua table.
- </para>
- <para>
- Parameters: none.
- </para>
- <para>
- Returns: the comparable value.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-<prompt>tarantool></prompt> <userinput>-- When nil is assigned to a Lua-table field, the field is null</userinput>
-<prompt>tarantool></prompt> <userinput>{nil, 'a', 'b'}</userinput>
-- - null
- - a
- - b
-...
-<prompt>tarantool></prompt> <userinput> -- When json.NULL is assigned to a Lua-table field, the field is json.NULL</userinput>
-<prompt>tarantool></prompt> <userinput>{json.NULL, 'a', 'b'}</userinput>
----
-- - null
- - a
- - b
-...
-<prompt>tarantool></prompt> <userinput>-- When json.NULL is assigned to a JSON field, the field is null</userinput>
-<prompt>tarantool></prompt> <userinput>json.encode({field2 = json.NULL, field1 = 'a', field3 = 'c'})</userinput>
----
-- '{"field2":null,"field1":"a","field3":"c"}'
-...</programlisting>
- </listitem>
- </varlistentry>
-</variablelist>
-
-</section>
-
-<section xml:id="sp-yaml">
- <title>Package <code>yaml</code></title>
- <para>
- The <code>yaml</code> package takes strings in YAML format and decodes them,
- or takes a series of non-YAML values and encodes them.
- </para>
-<variablelist xml:id="yaml">
- <varlistentry>
- <term><emphasis role="lua">yaml.encode(<replaceable>scalar-value | Lua-table-value</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Convert a Lua object to a YAML string.
- </para>
- <para>
- Parameters: either a scalar value or a Lua table value.
- </para>
- <para>
- Returns: (type = string) the original value reformatted as a YAML string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua">yaml.decode(<replaceable>string-value</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Convert a YAML string to a Lua object.
- </para>
- <para>
- Parameters: <code>string-value</code> = a string formatted as YAML.
- </para>
- <para>
- Returns: (type = Lua table) the original contents formatted as a Lua table.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua" xml:id="yaml-null" xreflabel="yaml-null">yaml.NULL</emphasis></term>
- <listitem>
- <para>
- Return a value comparable to Lua "nil" which may be useful as a placeholder in a tuple.
- </para>
- <para>
- Parameters: none.
- </para>
- <para>
- Returns: the comparable value.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-<prompt>tarantool></prompt> <userinput>yaml = require('yaml')</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>y = yaml.encode({'a',1,'b',2})</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>z = yaml.decode(y)</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>z[1],z[2],z[3],z[4]</userinput>
----
-- a
-- 1
-- b
-- 2
-...
-<prompt>tarantool></prompt> <userinput>if yaml.NULL == nil then print('hi') end</userinput>
-hi
----
-...
-</programlisting>
- </para>
-</section>
-
-<section xml:id="sp-msgpack">
- <title>Package <code>msgpack</code></title>
- <para>
- The <code>msgpack</code> package takes strings in MsgPack format and decodes them,
- or takes a series of non-MsgPack values and encodes them.
- </para>
-<variablelist xml:id="msgpack">
- <varlistentry>
- <term><emphasis role="lua">msgpack.encode(<replaceable>scalar-value | Lua-table-value</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Convert a Lua object to a MsgPack string.
- </para>
- <para>
- Parameters: either a scalar value or a Lua table value.
- </para>
- <para>
- Returns: (type = string) the original value reformatted as a MsgPack string.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua">msgpack.decode(<replaceable>string-value</replaceable>[, <replaceable>field-number</replaceable>])</emphasis></term>
- <listitem>
- <para>
- Convert a MsgPack string to a Lua object.
- </para>
- <para>
- Parameters: <code>string-value</code> = a string formatted as MsgPack.
- <code>field-number</code> = a number of a particular field to decode.
- </para>
- <para>
- Returns: (type = Lua table) the original contents formatted as a Lua table.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua" xml:id="msgpack-null" xreflabel="msgpack-null">msgpack.NULL</emphasis></term>
- <listitem>
- <para>
- Return a value comparable to Lua "nil" which may be useful as a placeholder in a tuple.
- </para>
- <para>
- Parameters: none.
- </para>
- <para>
- Returns: the comparable value.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-<prompt>tarantool></prompt> <userinput>msgpack = require('msgpack')</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput> y = msgpack.encode({'a',1,'b',2})</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput> z = msgpack.decode(y)</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput> z[1],z[2],z[3],z[4]</userinput>
----
-- a
-- 1
-- b
-- 2
-...
-<prompt>tarantool></prompt> <userinput> box.space.tester:insert{20,msgpack.NULL,20}</userinput>
----
-- [20, null, 20]
-...
-</programlisting>
- </para>
-</section>
-
-<section xml:id="sp-box-fiber">
- <title>Package <code>fiber</code></title>
- <para>
- The <code>fiber</code> package allows for creating, running and managing <emphasis>fibers</emphasis>.
- </para>
- <para>
- A fiber is a set of instructions which are executed
- with cooperative multitasking. Fibers managed by the
- fiber package are associated with a user-supplied function
- called the <emphasis>fiber function</emphasis>.
-
- A fiber has three possible states: running, suspended or dead.
- When a fiber is created with <code>fiber.create()</code>, it is running.
- When a fiber yields control with <code>fiber.sleep()</code>, it is suspended.
- When a fiber ends (because the fiber function ends), it is dead.
- </para>
- <para>
- All fibers are part of the fiber registry.
- This registry can be searched (<code>fiber.find()</code>)
-- via fiber id (fid), which is numeric.
- </para>
- <para>
- A runaway fiber can be stopped with <code><replaceable>fiber_object</replaceable>:cancel()</code>.
- However, <code><replaceable>fiber_object</replaceable>:cancel()</code> is advisory — it works
- only if the runaway fiber calls <code>fiber.testcancel()</code>
- once in a while. Most <code>box.*</code> functions, such as <code>box.space...delete()</code>
- or <code>box.space...update()</code>, do call <code>fiber.testcancel()</code> but
- <code>box.space...select{}</code> does not.
- In practice, a runaway fiber can only become unresponsive
- if it does many computations and does not check
- whether it's been canceled.
-<!--
-In addition to the advisory cancellation, configuration parameter
-<code>lua_timeout</code> can be used to cancel runaway Lua
-procedures.
--->
- </para>
- <para>
- The other potential problem comes from
- fibers which never get scheduled, because they are not subscribed
- to any events, or because no relevant events occur. Such morphing fibers
- can be killed with <code>fiber.cancel()</code> at any time,
- since <code>fiber.cancel()</code>
- sends an asynchronous wakeup event to the fiber,
- and <code>fiber.testcancel()</code> is checked whenever such an event occurs.
- </para>
- <para>
- Like all Lua objects, dead fibers are
- garbage collected. The garbage collector frees pool allocator
- memory owned by the fiber, resets all fiber data, and returns
- the fiber (now called a fiber carcass) to the fiber pool.
- The carcass can be reused when another fiber is created.
- </para>
-<variablelist xml:id="fiber">
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="fiber.create">fiber.create(<replaceable>function</replaceable> [, <replaceable>function-arguments</replaceable>])</emphasis>
- </term>
- <listitem>
- <para>
- Create and start a fiber. The fiber is
- created and begins to run immediately.
- </para>
- <para>
- Parameters: <code>function</code> = the function to be associated with the fiber,
- <code>function-arguments</code> = what will be passed to the function.
- </para>
- <para>
- Returns: (type = userdata) created fiber object.
- </para>
- <para>
- Example: <code>fiber_object = fiber.create(function_name)</code>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="fiber.id"><replaceable>fiber_object</replaceable>:id() </emphasis>
- </term>
- <listitem>
- <para>
- Parameters: fiber object, for example the fiber object returned by <code>fiber.create</code>.
- </para>
- <para>
- Returns: (type = number) id of the fiber.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="fiber.name"><replaceable>fiber_object</replaceable>:name() </emphasis>
- </term>
- <listitem>
- <para>
- Parameters: fiber object, for example the fiber object returned by <code>fiber.create</code>.
- </para>
- <para>
- Returns: (type = string) name of the fiber.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="ofiber.name"><replaceable>fiber_object</replaceable>:name(<replaceable>new-name</replaceable>) </emphasis>
- </term>
- <listitem>
- <para>
- Change the fiber name. By default the Tarantool server's interactive-mode fiber is named
- 'interactive' and new fibers created due to <code>fiber.create</code> are named 'lua'.
- Giving fibers distinct names makes it easier to distinguish them when using <code>fiber.info</code>.
- </para>
- <para>
- Parameters: fiber object, for example the fiber object returned by <code>fiber.create</code>;
- new-name = (type = string) the new name of the fiber.
- </para>
- <para>
- Returns: nil.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="fiber.self">fiber.self() </emphasis>
- </term>
- <listitem>
- <para>
- Returns: (type = userdata) fiber object for the currently scheduled fiber.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="fiber.find">fiber.find(<replaceable>id</replaceable>) </emphasis>
- </term>
- <listitem>
- <para>
- Locate a fiber userdata object by id.
- </para>
- <para>
- Returns: (type = userdata) fiber object for the specified fiber.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="fiber.sleep">fiber.sleep(<replaceable>time</replaceable>)</emphasis>
- </term>
- <listitem>
- <para>
- Yield control to the scheduler and sleep for the specified number of seconds.
- Only the current fiber can be made to sleep.
- </para>
- <para>
- Parameters: <code>time</code> = number of seconds to sleep.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="fiber.yield" xreflabel="fiber.yield">fiber.yield() </emphasis>
- </term>
- <listitem>
- <para>
- Yield control to the scheduler. Equivalent to <code>fiber.sleep(0)</code>.
- </para>
- <para>
- Parameters: <code>none</code>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="fiber.ostatus"><replaceable>fiber_object</replaceable>:status()</emphasis>
- </term>
- <listitem>
- <para>
- Return the status of the specified fiber.
- </para>
- <para>
- Parameters: <code>fiber_object</code> = the fiber to be checked.
- </para>
- <para>
- Returns: (type = string) the status of <code>fiber</code>.
- One of: <quote>dead</quote>,
- <quote>suspended</quote>,
- or <quote>running</quote>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="fiber.status">fiber.status()</emphasis>
- </term>
- <listitem>
- <para>
- Return the status of the current fiber.
- </para>
- <para>
- Parameters: none.
- </para>
- <para>
- Returns: (type = string) the status of <code>fiber</code>.
- One of: <quote>dead</quote>,
- <quote>suspended</quote>,
- or <quote>running</quote>.
- </para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry>
- <term>
- <emphasis role="lua">fiber.info()</emphasis>
- </term>
- <listitem>
- <para>
- Return information about all fibers.
- </para>
- <para>
- Returns: (type = table) the name, id, and backtrace of all fibers.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="fiber.cancel"><replaceable>fiber_object</replaceable>:cancel()</emphasis>
- </term>
- <listitem>
- <para>
- Cancel a <code>fiber</code>.
- Running and suspended fibers can be canceled.
- After a fiber has been canceled, attempts to operate on it will cause errors,
- for example <code><replaceable>fiber_object</replaceable>:id()</code> will cause
- "error: the fiber is dead".
- </para>
- <para>
- Parameters: fiber object, for example the fiber returned by <code>fiber.create</code>.
- </para>
- <para>
- Possible errors: cancel is not permitted for the specified fiber object.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="fiber.kill">fiber.kill(<replaceable>id</replaceable>) </emphasis>
- </term>
- <listitem>
- <para>
- Locate a fiber by its numeric id and cancel it. In
- other words, <code>fiber.kill()</code> combines <emphasis
- role="lua">fiber.find()</emphasis> and <emphasis
- role="lua"><replaceable>fiber_object</replaceable>:cancel()</emphasis>.
- </para>
- <para>
- Parameters: <code>id</code> = the id of the fiber to be canceled.
- </para>
- <para>
- Possible errors: the specified fiber does not exist or cancel is not permitted.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua" xml:id="fiber.testcancel">fiber.testcancel()</emphasis>
- </term>
- <listitem>
- <para>
- Check if the current fiber has been canceled and
- throw an exception if this is the case.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">fiber.time()</emphasis>
- </term>
- <listitem>
- <para>
- Returns: current system time (in seconds since the epoch) 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.
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>fiber = require('fiber')</userinput>
----
-...
-tarantool> <userinput> fiber.time(), fiber.time()</userinput>
----
- - 1385758759.2591
- - 1385758759.2591
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis role="lua">fiber.time64()</emphasis>
- </term>
- <listitem>
- <para>
- Returns: current system time (in microseconds since the epoch) as a 64-bit
- integer. The time is taken from the event loop clock.
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>tarantool> <userinput>fiber = require('fiber')</userinput>
----
-...
-tarantool> <userinput>fiber.time(), fiber.time64()</userinput>
----
- - 1385758828.9825
- - 1385758828982485
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
-</variablelist>
-
-<para>
-<bridgehead renderas="sect4">Example</bridgehead>
-Make the function which will be associated with the fiber.
-This function contains an infinite loop
-("while 0 == 0" is always true).
-Each iteration of the loop adds 1 to a global variable
-named gvar, then goes to sleep for 2 seconds.
-The sleep causes an implicit fiber.yield().<programlisting>
-<prompt>tarantool></prompt><userinput> fiber = require('fiber')</userinput>
-<prompt>tarantool></prompt><userinput> console = require('console'); console.delimiter('!')</userinput>
-<prompt>tarantool></prompt><userinput> function function_x()</userinput>
-<prompt> -></prompt><userinput> gvar = 0</userinput>
-<prompt> -></prompt><userinput> while 0 == 0 do</userinput>
-<prompt> -></prompt><userinput> gvar = gvar + 1</userinput>
-<prompt> -></prompt><userinput> fiber.sleep(2)</userinput>
-<prompt> -></prompt><userinput> end</userinput>
-<prompt> -></prompt><userinput> end!</userinput>
----
-...
-<prompt>tarantool></prompt><userinput> console.delimiter('')!</userinput></programlisting>
-Make a fiber, associate function_x with the fiber,
-and start function_x. It will immediately "detach"
-so it will be running independently of the caller.
-<programlisting>
-<prompt>tarantool></prompt><userinput> fiber_of_x = fiber.create(function_x)</userinput>
----
-...</programlisting>
-
-Get the id of the fiber (fid), to be used in later displays.<programlisting>
-<prompt>tarantool></prompt><userinput> fid = fiber_of_x:id()</userinput>
----
-...
-</programlisting>
-Pause for a while, while the detached function runs. Then ...
-Display the fiber id, the fiber status, and gvar (gvar will have
-gone up a bit depending how long the pause lasted). The status is
-suspended because the fiber spends almost all its time sleeping or yielding.<programlisting>
-<prompt>tarantool></prompt><userinput> print('#',fid,'. ',fiber_of_x:status(),'. gvar=',gvar)</userinput>
-# 102 . suspended . gvar= 399
----
-...
-</programlisting>
-Pause for a while, while the detached function runs. Then ...
-Cancel the fiber. Then, once again ...
-Display the fiber id, the fiber status, and gvar (gvar will have
-gone up a bit more depending how long the pause lasted). This time
-the status is dead because the cancel worked.<programlisting>
-<prompt>tarantool></prompt><userinput> fiber_of_x:cancel()</userinput>
-... fiber `lua' has been cancelled
-... fiber `lua': exiting
----
-...
-<prompt>tarantool></prompt><userinput> print('#',fid,'. ',fiber_of_x:status(),'. gvar=',gvar)</userinput>
-# 102 . dead . gvar= 421
----
-...</programlisting>
-</para>
-
-</section>
-
-<section xml:id="sp-fiber-ipc">
- <title>Package <code>fiber-IPC</code> — inter-process communication</title>
- <para>
- The <code>fiber-IPC</code> package allows sending and receiving messages between
- different processes. The words "different processes" in this context mean
- different connections, different sessions, or different fibers.
- </para>
- <para>
- Call <code>fiber.channel()</code> to allocate space and get a channel object, which will be
- called <code>channel</code> for examples in this section.
- Call the other fiber-IPC routines, via <code>channel</code>, to send messages, receive messages, or check ipc status.
- Message exchange is synchronous.
- The channel is garbage collected when no one is using it, as with any
- other Lua object.
- Use object-oriented syntax, for example <code>channel:put(message)</code>
- rather than <code>fiber.channel.put(message)</code>.
- </para>
-<variablelist xml:id="fiber.ipc">
- <para>
- </para>
- <varlistentry>
- <term><emphasis role="lua">fiber.channel(<replaceable>capacity-number</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Create a new communication channel.
- </para>
- <para>
- Parameters: <code>capacity-number</code> =
- a positive integer as great as the maximum number of slots
- (spaces for get or put or broadcast messages)
- that might be pending at any given time.
- </para>
- <para>
- Returns: new channel.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua"><replaceable>channel</replaceable>:put(<replaceable>message[, timeout]</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Send a message using a channel. If the channel is full,
- <code>channel:put()</code>
- blocks until there is a free slot in the channel.
- </para>
- <para>
- Parameters: <code>message</code>, <code>timeout</code>.
- </para>
- <para>
- Returns: (type = boolean) If <code>timeout</code> is provided,
- and the channel doesn't become empty for the duration
- of the timeout,
- <code>channel:put()</code>
- returns false. Otherwise it returns true.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua"><replaceable>channel</replaceable>:close()</emphasis></term>
- <listitem>
- <para>
- Close the channel. All waiters in the channel will be
- woken up. All following <code>channel:put()</code>
- or <code>channel:get()</code> operations will return
- an error (nil).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua"><replaceable>channel</replaceable>:get(<replaceable>[timeout]</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Fetch a message from a channel. If the channel is empty,
- <code>channel:get()</code>
- blocks until there is a message.
- </para>
- <para>
- Parameters: <code>timeout</code>.
- </para>
- <para>
- Returns: the value placed on the channel by an earlier <code>channel:put()</code> or <code>channel:broadcast()</code>.
- </para>
- <para>
- Possible errors: If <code>timeout</code> is provided,
- and there are no new messages for the duration
- of the timeout,
- <code>channel:get()</code>
- returns error.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua"><replaceable>channel</replaceable>:broadcast(<replaceable>message</replaceable>)</emphasis></term>
- <listitem>
- <para>
- If the channel is empty, <code>channel:broadcast()</code> is equivalent to
- <code>channel:put()</code>.
- Otherwise, <code>channel:broadcast()</code> sends the message to all readers of the
- channel.
- </para>
- <para>
- Parameters: <code>message</code>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua"><replaceable>channel</replaceable>:is_empty()</emphasis></term>
- <listitem>
- <para>
- Check whether the specified channel is empty (has no messages).
- </para>
- <para>
- Returns: (type = boolean) true if the specified channel is empty.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua"><replaceable>channel</replaceable>:count()</emphasis></term>
- <listitem>
- <para>
- Find out how many messages are on the channel. The answer is 0 if the channel is empty.
- </para>
- <para>
- Returns: (type = number) the number of messages.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua"><replaceable>channel</replaceable>:is_full()</emphasis></term>
- <listitem>
- <para>
- Check whether the specified channel is full.
- </para>
- <para>
- Returns: (type = boolean) true if the specified channel is full (has no room for a new message).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua"><replaceable>channel</replaceable>:has_readers()</emphasis></term>
- <listitem>
- <para>
- Check whether the specified channel is empty and has readers waiting
- for a message (because they have issued <code>channel:get()</code> and then
- blocked).
- </para>
- <para>
- Returns: (type = boolean) true if blocked users are waiting. Otherwise false.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua"><replaceable>channel</replaceable>:has_writers()</emphasis></term>
- <listitem>
- <para>
- Check whether the specified channel is full and has writers waiting
- (because they have issued <code>channel:put()</code> and then blocked
- due to lack of room).
- </para>
- <para>
- Returns: (type = boolean) true if blocked users are waiting. Otherwise false.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="lua"><replaceable>channel</replaceable>:is_closed()</emphasis></term>
- <listitem>
- <simpara>
- Returns: (type = boolean) true if the specified channel is already
- closed.
- Otherwise false.
- </simpara>
- </listitem>
- </varlistentry>
-</variablelist>
-<para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting><userinput>
-
-fiber = require('fiber')
-channel = fiber.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
- ... -- timeout
- end
- end
-end
-
-function producer_fiber()
- while true do
- task = box.space...: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 are waiting for data
- end
- ...
-
- if channel:has_writers() then
- # there are some fibers that are waiting for readers
- end
- channel:put(task)
- end
-end
-
-function producer2_fiber()
- while true do
- task = box.space...select{...}
-
- if channel:put(task, 10) then -- 10 seconds
- ...
- else
- ... -- timeout
- end
- end
-end
-</userinput></programlisting>
-</para>
-</section>
-
-<section xml:id="sp-box-session">
- <title>Package <code>box.session</code></title>
- <para>
- The <code>box.session</code> package allows querying the session state,
- writing to a session-specific temporary Lua table, or setting up triggers
- which will fire when a session starts or ends.
- A <emphasis>session</emphasis> is an object associated with each client connection.
- </para>
-<variablelist>
- <varlistentry>
- <term>
- <emphasis role="lua">box.session.id() </emphasis>
- </term>
- <listitem>
- <para>
- Returns: (type = number) the unique identifier
- (ID) for the current session. The result can be 0 meaning
- there is no session.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.session.exists(<replaceable>id</replaceable>) </emphasis>
- </term>
- <listitem>
- <para>
- Returns: (type = number) 1 if the session exists,
- 0 if the session does not exist.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.session.peer(<replaceable>id</replaceable>) </emphasis>
- </term>
- <listitem>
- <para>
- Parameters: <code>id</code> = the unique identifier of the session.
- </para>
- <para>
- Returns: (type = string) If the specified session exists, the host
- address and port of the session peer, for example "127.0.0.1:55457".
- If the specified session does not exist, "0.0.0.0:0". The command is executed on the server,
- so the "local name" is the server's host and administrative port,
- and the "peer name" is the client's host and port.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.session.storage</emphasis>
- </term>
- <listitem>
- <para>
- A Lua table that can hold arbitrary
- unordered session-specific names and values, which will last until
- the session ends.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-<bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt><userinput> box.session.peer(session.id())</userinput>
----
- - 127.0.0.1:45129
-...
-<prompt>tarantool></prompt><userinput> box.session.storage.random_memorandum = "Don't forget the eggs."</userinput>
----
-...
-<prompt>tarantool></prompt><userinput> box.session.storage.radius_of_mars = 3396</userinput>
----
-...
-
-<prompt>tarantool></prompt><userinput> m = ''</userinput>
----
-...
-<prompt>tarantool></prompt><userinput> for k, v in pairs(box.session.storage) do m = m .. k .. '=' .. v .. ' ' end</userinput>
----
-...
-<prompt>tarantool></prompt><userinput> m</userinput>
----
-- 'radius_of_mars=3396 random_memorandum=Don''t forget the eggs. '
-...</programlisting>
-</para>
-
- <para>
- See <olink targetptr="sp-box-session-triggers">the section "Triggers on connect and disconnect"</olink>
- for instructions about defining triggers for connect and disconnect events
- with <code>box.session.on_connect()</code> and <code>box.session.on_disconnect()</code>.
- See <link linkend="authentication">the section "Authentication and access control"</link>
- for instructions about <code>box.session</code> functions that affect user identification and security.
- </para>
-</section>
-
-<section xml:id="sp-box-socket">
- <title>Package <code>socket</code> — TCP and UDP sockets</title>
-<variablelist xml:id="socket">
- <para>
- The <code>socket</code> package allows exchanging data via BSD sockets
- with a local or remote host in connection-oriented (TCP) or datagram-oriented (UDP) mode.
- Semantics of the calls in the <code>socket</code> API closely follow
- semantics of the corresponding POSIX calls. Function names
- and signatures are mostly compatible with
- <link xlink:href="http://w3.impa.br/~diego/software/luasocket/">luasocket</link>.
- </para>
- <para>
- The functions for setting up and connecting are <code>socket</code>, <code>sysconnect</code>, <code>tcp_connect</code>.
- The functions for sending data are <code>send</code>, <code>sendto</code>, <code>write</code>, <code>syswrite</code>.
- The functions for receiving data are <code>recv</code>, <code>recvfrom</code>, <code>read</code>.
- The functions for waiting before sending/receiving data are <code>wait</code>, <code>readable</code>, <code>writable</code>.
- The functions for setting flags are <code>nonblock</code>, <code>setsockopt</code>.
- The functions for stopping and disconnecting are <code>shutdown</code>, <code>close</code>.
- The functions for error checking are <code>errno</code>, <code>error</code>.
- </para>
- <para>
- <table>
- <title xml:id="socket-functions">Socket functions: Names, Purposes</title>
- <tgroup cols="2" align="left" colsep="1" rowsep="1">
- <thead>
- <row><entry>Name</entry><entry>Purpose</entry></row>
- </thead>
- <tbody>
- <row><entry>socket</entry><entry>setup</entry></row>
- <row><entry><link linkend="socket-sysconnect">sysconnect</link></entry><entry>setup</entry></row>
- <row><entry><link linkend="socket-tcpconnect">tcp_connect</link></entry><entry>setup</entry></row>
- <row><entry><link linkend="socket-send">send</link></entry><entry>sending</entry></row>
- <row><entry><link linkend="socket-sendto">sendto</link></entry><entry>sending</entry></row>
- <row><entry><link linkend="socket-send">write</link></entry><entry>sending</entry></row>
- <row><entry><link linkend="socket-syswrite">syswrite</link></entry><entry>sending</entry></row>
- <row><entry><link linkend="socket-recv">recv</link></entry><entry>receiving</entry></row>
- <row><entry><link linkend="socket-recvfrom">recvfrom</link></entry><entry>receiving</entry></row>
- <row><entry><link linkend="socket-read">read</link></entry><entry>receiving</entry></row>
- <row><entry><link linkend="socket-nonblock">nonblock</link></entry><entry>flag setting </entry></row>
- <row><entry><link linkend="socket-setsockopt">setsockopt</link></entry><entry>flag setting </entry></row>
- <row><entry><link linkend="socket-linger">linger</link></entry><entry>flag setting</entry></row>
- <row><entry><link linkend="socket-listen">listen</link></entry><entry>client/server</entry></row>
- <row><entry><link linkend="socket-accept">accept</link></entry><entry>client/server</entry></row>
- <row><entry><link linkend="socket-shutdown">shutdown</link></entry><entry>teardown</entry></row>
- <row><entry><link linkend="socket-close">close</link></entry><entry>teardown</entry></row>
- <row><entry><link linkend="socket-error">errno</link></entry><entry>serror checking</entry></row>
- <row><entry><link linkend="socket-error">error</link></entry><entry>error checking</entry></row>
- <row><entry><link linkend="socket-getaddrinfo">getaddrinfo</link></entry><entry>information</entry></row>
- <row><entry><link linkend="socket-getsockopt">getsockopt</link></entry><entry>information</entry></row>
- <row><entry><link linkend="socket-peer">peer</link></entry><entry>information</entry></row>
- <row><entry><link linkend="socket-name">name</link></entry><entry>information</entry></row>
- </tbody>
- </tgroup>
- </table>
- </para>
- <para>
- Typically a socket session will begin with the setup functions,
- will set one or more flags, will have a loop with sending and receiving functions,
- will end with the teardown functions -- as an example at the end of this section will show.
- Throughout, there may be error-checking and waiting functions for synchronization.
- Some functions may "block" if a non-default option flag is set,
- therefore the fiber that they are in will yield so that other processes may take
- over, as is the norm for cooperative multitasking.
- </para>
- <para>
- For all examples in this section the socket name will be <code>sock</code>
- and the function invocations will look like <code>sock:<replaceable>function_name</replaceable>(...)</code>.
- </para>
-
- <varlistentry>
- <term xml:id="socket-socket" xreflabel="socket-socket"><emphasis role="lua">socket(<replaceable>domain</replaceable>, <replaceable>type</replaceable>, <replaceable>protocol</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Create a new TCP or UDP socket.
- The argument values are the same as in the <link xlink:href="http://man7.org/linux/man-pages/man2/socket.2.html">Linux man page</link>.
- </para>
- <para>
- Returns: (type = userdata) a new socket, or <code>nil</code>.
- </para>
- <para>
- Example: <code>socket = require('socket'); sock = socket('AF_INET', 'SOCK_STREAM', 'tcp')</code>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-sysconnect" xreflabel="socket-sysconnect"><emphasis role="lua"><replaceable>sock</replaceable>:sysconnect(<replaceable>host, port</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Connect a socket to a remote host.
- The argument values are the same as in the <link xlink:href="http://man7.org/linux/man-pages/man2/connect.2.html">Linux man page</link>.
- The host must be an IP address.
- </para>
- <para>
- Parameters: Either: <code>host</code> -- a string representation of an IPv4 address or an IPv6 address; <code>port</code> -- a number.
- Or: <code>host</code> -- a string containing "unix/"; <code>port</code> -- a string containing a path to a unix socket.
- Or: <code>host</code> -- a number, 0 (zero), meaning "all local interfaces"; <code>port</code> -- a number.
- If a port number is 0 (zero), the socket will be bound to a random local port.
- </para>
- <para>
- Returns: (type = userdata) a connected socket, if no error.
- </para>
- <para>
- Example: <code>sock:sysconnect('127.0.0.1', 80)</code>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-tcpconnect" xreflabel="socket-tcpconnect"><emphasis role="lua">socket.tcp_connect(<replaceable>host, port</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Connect a socket to a remote host.
- </para>
- <para>
- Parameters: <code>host</code>, <code>port</code>. The host may be a URL rather than an IP address.
- </para>
- <para>
- Returns: (type = userdata) a connected socket, if no error.
- </para>
- <para>
- Example: <code>socket.tcp_connect('tarantool.org', 80)</code>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-send" xreflabel="socket-send"><emphasis role="lua"><replaceable>sock</replaceable>:send(<replaceable>data</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Send data over a connected socket.
- </para>
- <para>
- Parameters: <code>data</code> (type = string).
- </para>
- <para>
- Returns: (type = boolean) true if success, false if error.
- </para>
- <para>
- Notes: The function <code>sock:write(...)</code> has the same parameters and same effect.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-syswrite" xreflabel="socket-syswrite"><emphasis role="lua"><replaceable>sock</replaceable>:syswrite(<replaceable>size</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Write as much as possible data to the socket buffer if non-blocking.
- Rarely used. For details see <link xlink:href="https://github.com/tarantool/tarantool/wiki/sockets%201.6">this description</link>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-recv" xreflabel="socket-recv"><emphasis role="lua">sock:recv(<replaceable>size</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Read <code>size</code> bytes from a connected socket.
- An internal read-ahead buffer is used to reduce the cost
- of this call.
- </para>
- <para>
- Parameters: <code>size</code>(type = integer).
- </para>
- <para>
- Returns: (type = string) a string of the requested length on success.
- On error, returns an empty string, followed
- by <code>status, errno, errstr</code>.
- In case the writing side has closed its end, returns the remainder
- read from the socket (possibly an empty string),
- followed by <code>"eof"</code> status.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-read" xreflabel="socket-read">
- <emphasis role="lua"><replaceable>sock</replaceable>:read(<replaceable>limit</replaceable> [, <replaceable>timeout</replaceable>])</emphasis>
- or <emphasis role="lua"><replaceable>sock</replaceable>:read(<replaceable>delimiter</replaceable> [, <replaceable>timeout</replaceable>])</emphasis>
- or <emphasis role="lua"><replaceable>sock</replaceable>:read({limit=<replaceable>limit</replaceable>} [, <replaceable>timeout</replaceable>])</emphasis>
- or <emphasis role="lua"><replaceable>sock</replaceable>:read({delimiter=<replaceable>delimiter</replaceable>} [, <replaceable>timeout</replaceable>])</emphasis>
- or <emphasis role="lua"><replaceable>sock</replaceable>:read({limit=<replaceable>limit</replaceable>, delimiter=<replaceable>delimiter</replaceable>} [, <replaceable>timeout</replaceable>])</emphasis>
- </term>
- <listitem>
- <para>
- Read from a connected socket until some condition is true, and return the bytes that were read.
- </para>
- <para>
- Parameters: <code>limit</code> (type = integer) — maximum number of bytes to read for example 50 means "stop after 50 bytes",
- <code>delimiter</code> (type = string) — separator or <link xlink:href="http://www.lua.org/pil/20.2.html">Lua pattern</link> for example '[0-9]' means "stop after a digit",
- <code>timeout</code> (type = number) — maximum number of seconds to wait for example 50 means "stop after 50 seconds".
- Reading goes on until <code>limit</code> bytes have been read,
- or a delimiter has been read, or a timeout has expired.
- </para>
- <para>
- Returns:
- (type = string) an empty string if there is nothing more to read,
- or a nil value if error,
- or a string up to <code>limit</code> bytes long,
- which may include the bytes that matched the <code>delimiter</code> expression.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-sysread" xreflabel="socket-sysread"><emphasis role="lua"><replaceable>sock</replaceable>:sysread(<replaceable>size</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Return all available data from the socket buffer if non-blocking.
- Rarely used. For details see <link xlink:href="https://github.com/tarantool/tarantool/wiki/sockets%201.6">this description</link>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-bind" xreflabel="socket-bind"><emphasis role="lua"><replaceable>sock</replaceable>:bind(<replaceable>host</replaceable>[, <replaceable>port</replaceable>])</emphasis></term>
- <listitem>
- <para>
- Bind a socket to the given host/port.
- A UDP socket after binding can be used
- to receive data (see <code><link linkend="socket-recvfrom">recvfrom()</link></code>). A TCP socket
- can be used to accept new connections, after it has
- been put in listen mode.
- </para>
- <para>
- Parameters: <code>host</code>, <code>port</code>.
- </para>
- <para>
- Returns: (type = userdata) a socket object on success, <code>nil, status, errno, errstr</code> on error.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-listen" xreflabel="socket-listen"><emphasis role="lua"><replaceable>sock</replaceable>:listen(backlog)</emphasis></term>
- <listitem>
- <para>
- Start listening for incoming connections.
- </para>
- <para>
- On Linux the listen <code>backlog</code>
- backlog may be from <filename>/proc/sys/net/core/somaxconn</filename>,
- on BSD the backlog may be <constant>SOMAXCONN</constant>.
- </para>
- <para>
- Returns: (type = boolean) true for success, false for error.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-accept" xreflabel="socket-accept"><emphasis role="lua"><replaceable>sock</replaceable>:accept()</emphasis></term>
- <listitem>
- <para>
- Accept a new client connection and create a new connected socket.
- It is good practice to set the socket's blocking mode explicitly after accepting.
- </para>
- <para>
- Returns: new socket if success, null if error.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-sendto" xreflabel="socket-sendto"><emphasis role="lua"><replaceable>sock</replaceable>:sendto(<replaceable>host, port, data</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Send a message on a UDP socket to a specified host.
- </para>
- <para>
- Parameters: <code>host</code>, <code>port</code>, <code>data</code> (type = string), .
- </para>
- <para>
- Returns: if successful: (type = integer) the number of bytes sent.
- </para>
- <para>
- Returns: if not successful: status, errno, errstr.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-recvfrom" xreflabel="socket-recvfrom"><emphasis role="lua"><replaceable>sock</replaceable>:recvfrom(<replaceable>limit</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Receive a message on a UDP socket.
- </para>
- <para>
- Parameters: <code>limit</code> (type = integer).
- </para>
- <para>
- Returns: if successful: (type = string) message, (type = table) a table containing "host" and "family" and "port" fields.
- </para>
- <para>
- Returns: if not successful: status, errno, errstr.
- </para>
- <para>
- Example: after <code>message_content, message_sender = recvfrom(1)</code> the value of <code>message_content</code>
- might be a string containing 'X' and the value of <code>message_sender</code> might be a table containing
- message_sender.host = '18.44.0.1', message_sender.family = 'AF_INET', message_sender.port = 43065.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-shutdown" xreflabel="socket-shutdown"><emphasis role="lua"><replaceable>sock</replaceable>:shutdown(<replaceable>how</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Shutdown a reading end, a writing end, or both ends of a socket.
- </para>
- <para>
- Parameters: <code>how</code> = socket.SHUT_RD, socket.SHUT_WR,
- or socket.SHUT_RDWR.
- </para>
- <para>
- Returns: true or false.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-close" xreflabel="socket-close"><emphasis role="lua"><replaceable>sock</replaceable>:close()</emphasis></term>
- <listitem>
- <para>
- Close (destroy) a socket.
- A closed socket should not be used any more.
- A socket is closed automatically
- when its userdata is garbage collected by Lua.
- </para>
- <para>
- Returns: (type = boolean) true on success, false on error.
- For example, if sock is already closed, sock:close() returns false.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-error" xreflabel="socket-error"><emphasis role="lua"><replaceable>sock</replaceable>:error() and <replaceable>sock</replaceable>:errno()</emphasis></term>
- <listitem>
- <para>
- Retrieve information about the last error that occurred on a socket, if any.
- Errors do not cause throwing of exceptions so these functions are usually necessary.
- </para>
- <para>
- Returns:(type = number) result for sock:errno(), (type = string) result for sock:error().
- If there is no error, then sock:errno() will return 0 and sock:error() will return null.
- </para>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-setsockopt" xreflabel="socket-setsockopt"><emphasis role="lua"><replaceable>sock</replaceable>:setsockopt(<replaceable>level, name, value</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Set socket flags. The argument values are the same as in the <link xlink:href="http://man7.org/linux/man-pages/man2/setsockopt.2.html">Linux man page</link>.
- The ones that Tarantool accepts are
- SO_ACCEPTCONN, SO_BINDTODEVICE, SO_BROADCAST, SO_BSDCOMPAT, SO_DEBUG,
- SO_DOMAIN, SO_ERROR, SO_DONTROUTE, SO_KEEPALIVE, SO_MARK, SO_OOBINLINE,
- SO_PASSCRED, SO_PEERCRED, SO_PRIORITY, SO_PROTOCOL, SO_RCVBUF, SO_RCVBUFFORCE,
- SO_RCVLOWAT, SO_SNDLOWAT, SO_RCVTIMEO, SO_SNDTIMEO, SO_REUSEADDR, SO_SNDBUF,
- SO_SNDBUFFORCE, SO_TIMESTAMP, and SO_TYPE.
- Setting SO_LINGER is done with sock:linger(active), see below.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-getsockopt" xreflabel="socket-getsockopt"><emphasis role="lua"><replaceable>sock</replaceable>:getsockopt(<replaceable>level, name</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Get socket flags. For a list of possible flags see description of the previous function,
- sock:setsockopt().
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-linger" xreflabel="socket-linger"><emphasis role="lua"><replaceable>sock</replaceable>:linger([<replaceable>active</replaceable>])</emphasis></term>
- <listitem>
- <para>
- Set or clear the SO_LINGER flag. For a description of the flag, see <link xlink:href="http://man7.org/linux/man-pages/man1/loginctl.1.html">Linux man page</link>.
- </para>
- <para>
- Parameters: <code>active</code>.
- </para>
- <para>
- Returns: new active and timeout values.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-nonblock" xreflabel="socket-nonblock"><emphasis role="lua"><replaceable>sock</replaceable>:nonblock([<replaceable>flag</replaceable>])</emphasis></term>
- <listitem>
- <para>
- <code>sock:nonblock()</code> returns the current flag value.
- <code>sock:nonblock(true)</code> sets the flag to false and returns false.
- <code>sock:nonblock(true)</code> sets the flag to true and returns true.
- This function may be useful before invoking a function which might otherwise block indefinitely.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-readable" xreflabel="socket-readable"><emphasis role="lua"><replaceable>sock</replaceable>:readable([<replaceable>timeout</replaceable>])</emphasis>, <emphasis>sock:writable([<replaceable>timeout</replaceable>])</emphasis>, <emphasis>sock:wait([<replaceable>timeout</replaceable>])</emphasis></term>
- <listitem>
- <para>
- <code>sock:readable()</code> waits until something is readable, or until a timeout value expires.
- <code>sock:writable()</code> waits until something is writable, or until a timeout value expires.
- <code>sock:wait()</code> waits until something is either readable or writable, or until a timeout value expires.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-name" xreflabel="socket-name"><emphasis role="lua"><replaceable>sock</replaceable>:name()</emphasis></term>
- <listitem>
- <para>
- The <code>sock:name()</code> function is used to get information about the near side of the connection.
- If a socket was bound to xyz.com:45, then <code>sock:name</code> will return information about [host:xyz.com, port:45].
- The equivalent POSIX function is <code>getsockname()</code>.
- </para>
- <para>
- Returns: A table containing these fields: "host", "family", "type", "protocol", "port".
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-peer" xreflabel="socket-peer"><emphasis role="lua"><replaceable>sock</replaceable>:peer()</emphasis></term>
- <listitem>
- <para>
- The <code>sock:peer()</code> function is used to get information about the far side of a connection.
- If a TCP connection has been made to a distant host tarantool.org:80, <code>sock:peer</code> will return information about [host:tarantool.org, port:80].
- The equivalent POSIX function is <code>getpeername()</code>.
- </para>
- <para>
- Returns: A table containing these fields: "host", "family", "type", "protocol", "port".
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-getaddrinfo" xreflabel="socket-getaddrinfo"><emphasis role="lua">socket.getaddrinfo(<replaceable>host</replaceable>, <replaceable>type</replaceable> [, <replaceable>{option-list}</replaceable>)</emphasis></term>
- <listitem>
- <para>
- The <code>socket.getaddrinfo()</code> function is useful for finding
- information about a remote site so that the correct arguments for
- <code>sock:sysconnect()</code> can be passed.
- </para>
- <para>
- Returns: An array containing "host:", "family", "type:", "protocol:", and "port:" fields.
- </para>
- <para>
- Example: <code>socket.getaddrinfo('tarantool.org', 'http')</code> will return variable information
- such as "- - host: 188.93.56.70, family: AF_INET, type: SOCK_STREAM, protocol: tcp, port: 80".
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="socket-tcp_server" xreflabel="socket-tcp_server"><emphasis role="lua">socket.tcp_server(<replaceable>host</replaceable>, <replaceable>port</replaceable>, <replaceable>handler-function</replaceable>)</emphasis></term>
- <listitem>
- <para>
- The <code>socket.tcp_server()</code> function makes Tarantool act as a server
- that can accept connections.
- Usually the same objective is accomplished with <code>box.cfg{listen=...)</code>.
- </para>
- <para>
- Example: <code>socket.tcp_server('localhost', 3302, function () end)</code>.
- </para>
- </listitem>
- </varlistentry>
-
-</variablelist>
-
-
- <bridgehead renderas="sect4">Socket example #1: use of a TCP socket over the Internet</bridgehead>
- <para>
- In this example a connection is made over the internet between the Tarantool server
- and <link xlink:href="http://tarantool.org">tarantool.org</link>,
- then an HTTP "head" message is sent, and a response is received: "HTTP/1.1 200 OK".
- This is not a useful way to communicate with this particular site,
- but shows that the system works.
-<programlisting>
-<prompt>tarantool></prompt> <userinput>socket = require('socket')</userinput>
----
-...
-
-<prompt>tarantool></prompt> <userinput>sock = socket.tcp_connect('tarantool.org', 80)</userinput>
----
-...
-
-<prompt>tarantool></prompt> <userinput>type(sock)</userinput>
----
-- table
-...
-
-<prompt>tarantool></prompt> <userinput>sock:error()</userinput>
----
-- null
-...
-
-<prompt>tarantool></prompt> <userinput>sock:send("HEAD / HTTP/1.0\r\nHost: tarantool.org\r\n\r\n")</userinput>
----
-- true
-...
-
-<prompt>tarantool></prompt> <userinput>sock:read(17)</userinput>
----
-- "HTTP/1.1 200 OK\r\n"
-...
-
-<prompt>tarantool></prompt> <userinput>sock:close()</userinput>
----
-- true
-...
-</programlisting>
-</para>
-
-<bridgehead renderas="sect4">Socket example #2: Example showing use of a UDP socket on localhost</bridgehead>
- <para>
-Here is an example with datagrams.
-Set up two connections on 127.0.0.1 (localhost): sock_1 and sock_2.
-Using sock_2, send a message to sock_1.
-Using sock_1, receive a message.
-Display the received message.
-Close both connections.
-This is not a useful way for a computer to communicate with itself,
-but shows that the system works.
-<programlisting>
-<prompt>tarantool></prompt> <userinput>socket = require('socket')</userinput>
----
-...
-
-<prompt>tarantool></prompt> <userinput> sock_1 = socket('AF_INET', 'SOCK_DGRAM', 'udp')</userinput>
----
-...
-
-<prompt>tarantool></prompt> <userinput> sock_1:bind('127.0.0.1')</userinput>
----
-- true
-...
-
-<prompt>tarantool></prompt> <userinput> sock_2 = socket('AF_INET', 'SOCK_DGRAM', 'udp')</userinput>
----
-...
-
-<prompt>tarantool></prompt> <userinput> sock_2:sendto('127.0.0.1', sock_1:name().port,'X')</userinput>
----
-- true
-...
-
-<prompt>tarantool></prompt> <userinput> message = sock_1:recvfrom()</userinput>
----
-...
-
-<prompt>tarantool></prompt> <userinput> message</userinput>
----
-- X
-...
-
-<prompt>tarantool></prompt> <userinput> sock_1:close()</userinput>
----
-- true
-...
-
-<prompt>tarantool></prompt> <userinput> sock_2:close()</userinput>
----
-- true
-...
-</programlisting>
-
-</para>
-
-</section>
-
-<section xml:id="sp-fio">
-<title>package <code>fio -- Cooperative File I/O</code></title>
- <para>
- Tarantool supports file input/output with an API that is similar to POSIX syscalls.
- All operations are performed asynchronously.
- Multiple fibers can access the same file simultaneously.
- </para>
- <variablelist>
-
- <varlistentry>
- <term><emphasis role="lua">fio.pathjoin(<replaceable>partial-string [, partial-string ...]</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Concatenate partial strings, separated by '/', to form a path name.
- </para>
- <para>
- Parameters: (type = string) one or more strings to be concatenated.
- </para>
- <para>
- Returns: path name
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fio.pathjoin('/etc', 'default', 'myfile')</userinput>
----
-- /etc/default/myfile
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">fio.basename(<replaceable>path-name</replaceable>[, <replaceable>suffix</replaceable>])</emphasis></term>
- <listitem>
- <para>
- Given a full path name, remove all but the final part (the file name).
- Also remove the suffix, if it is passed.
- </para>
- <para>
- Parameters: (type = string) path name, (type = string) suffix.
- </para>
- <para>
- Returns: file name.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fio.basename('/path/to/my.lua', '.lua')</userinput>
----
-- my
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">fio.dirname(<replaceable>path-name</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Given a full path name, remove the final part (the file name).
- </para>
- <para>
- Parameters: (type = string) path name.
- </para>
- <para>
- Returns: directory name, that is, path name except for file name.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fio.dirname('/path/to/my.lua')</userinput>
----
-- /path/to/
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">fio.umask(<replaceable>mask-bits</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Set the mask bits used when creating files or directories. For a detailed description type "man 2 umask".
- </para>
- <para>
- Parameters: (type = number) mask bits.
- </para>
- <para>
- Returns: (type = number) previous mask bits.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fio.umask(tonumber('755', 8)) -- pass 755 octal</userinput>
----
-- 493
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">fio.lstat or fio.stat(<replaceable>path-name</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Returns information about a file object.
- For details type "man 2 lstat" or "man 2 stat".
- </para>
- <para>
- Parameters: (string) path-name of file.
- </para>
- <para>
- Returns: (type = table) fields which describe the file's block size, creation time, size, and other attributes.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fio.lstat('/etc')</userinput>
----
-- inode: 1048577
- rdev: 0
- size: 12288
- atime: 1421340698
- mode: 16877
- mtime: 1424615337
- nlink: 160
- uid: 0
- blksize: 4096
- gid: 0
- ctime: 1424615337
- dev: 2049
- blocks: 24
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">fio.mkdir or fio.rmdir(<replaceable>path-name</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Create or delete a directory. For details type "man 2 mkdir" or "man 2 rmdir".
- </para>
- <para>
- Parameters: (type = string) path of directory.
- </para>
- <para>
- Returns: (type = boolean) true if success, false if failure.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fio.mkdir('/etc')</userinput>
----
-- false
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">fio.glob(<replaceable>path-name</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Return a list of files that match an input string.
- The list is constructed with a single flag that controls the behavior of the function: GLOB_NOESCAPE.
- For details type "man 3 glob".
- </para>
- <para>
- Parameters: (type = string) path-name, which may contain wildcard characters.
- </para>
- <para>
- Returns: (type = table) list of files whose names match the input string, or nil if failure.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fio.glob('/etc/x*')</userinput>
----
-- - /etc/xdg
- - /etc/xml
- - /etc/xul-ext
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">fio.tempdir()</emphasis></term>
- <listitem>
- <para>
- Return the name of a directory that can be used to store temporary files.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fio.tempdir()</userinput>
----
-- /tmp/lG31e7
- ...</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">fio.link or fio.symlink or fio.readlink or fio.unlink(<replaceable>path-name</replaceable> [, <replaceable>path-name</replaceable>])</emphasis></term>
- <listitem>
- <para>
- Functions to create and delete links.
- For details type "man readlink", "man 2 link", "man 2 symlink", "man 2 unlink"..
- </para>
- <para>
- Parameters: (type = string) existing file name, (type = string) linked name.
- </para>
- <para>
- Returns: <code>fio.link</code> and <code>fio.symlink</code> and <code>fio.unlink</code> return true if success, false if failure. <code>fio.readlink</code> returns the link value if success, nil if failure.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fio.link('/home/username/tmp.txt', '/home/username/tmp.txt2')</userinput>
----
-- true
-...
-<prompt>tarantool></prompt> <userinput>fio.unlink('/home/pgulutzan/tmp.txt2')</userinput>
----
-- true
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">fio.rename(<replaceable>path-name</replaceable>, <replaceable>new-path-name</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Rename a file or directory.
- For details type "man 2 rename".
- </para>
- <para>
- Parameters: (type = string) original name, (type = string) new name.
- </para>
- <para>
- Returns: (type = boolean) true if success, false if failure.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fio.rename('/home/username/tmp.txt', '/home/username/tmp.txt2')</userinput>
----
-- true
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">fio.chown or fio.chmod(<replaceable>path-name</replaceable>,<replaceable>new rights or new owner</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Manage the rights to file objects, or ownership of file objects. For details type "man 2 chown" or "man 2 chmod".
- </para>
- <para>
- Parameters: (for chown) number (uid, gid) and group group name or user name.
- </para>
- <para>
- Returns: (type = boolean) true if success, false if failure.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fio.chmod('/home/username/tmp.txt', tonumber('0755', 8))</userinput>
----
-- true
-...
- <userinput>fio.chown('/home/username/tmp.txt', 'username', 'username')</userinput>
----
-- true
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">fio.truncate(<replaceable>path-name</replaceable>,<replaceable>new-size</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Reduce file size to a specified value. For details type "man 2 truncate".
- </para>
- <para>
- Parameters: (type = string) path-name, (type = number) new-size.
- </para>
- <para>
- Returns: (type = boolean) true if success, false if failure.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fio.truncate('/home/username/tmp.txt', 99999)</userinput>
----
-- true
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">fio.sync()</emphasis></term>
- <listitem>
- <para>
- Ensure that changes are written to disk. For details type "man 2 sync".
- </para>
- <para>
- Parameters: none
- </para>
- <para>
- Returns: (type = boolean) true if success, false if failure.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fio.sync()</userinput>
----
-- true
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">fio.open(<replaceable>path-name</replaceable>[, <replaceable>flags</replaceable>])</emphasis></term>
- <listitem>
- <para>
- Open a file in preparation for reading or writing or seeking.
- </para>
- <para>
- Parameters: (string) path-name, (number) flags. Flags can be passed as a number or as string constants, for example 'O_RDONLY', 'O_WRONLY', 'O_RDWR'.
- Flags can be combined by enclosing them in braces.
- </para>
- <para>
- Returns: (type = table) if success = a file handle (referred to in later examples as "fh"), if failure = nil.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fh = fio.open('/home/username/tmp.txt', {'O_RDWR', 'O_APPEND'})</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>fh -- display file handle returned by fio.open</userinput>
----
-- fh: 11
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>file-handle</replaceable>:close()</emphasis></term>
- <listitem>
- <para>
- Close a file that was opened with fio.open. For details type "man 2 close".
- </para>
- <para>
- Parameters: (type = table) file handle as returned by <code>fio.open()</code>.
- </para>
- <para>
- Returns: (type = boolean) true if success, false if failure.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fh:close() -- where fh = file-handle</userinput>
----
-- true
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>file-handle</replaceable>:pread or <replaceable>file-handle</replaceable>:pwrite(<replaceable>count or new string</replaceable>, <replaceable>offset</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Perform read/write random-access operation on a file, without affecting the current seek position of the file.
- For details type "man 2 pread" or "man 2 pwrite".
- </para>
- <para>
- Parameters: (type = table) file-handle as returned by <code>fio.open</code>,
- (type = string) value to write or (type = number) number of bytes to read,
- (type = number) offset within file where reading or writing begins.
- </para>
- <para>
- Returns: <code>pwrite</code> returns true if success, false if failure. <code>pread</code> returns the data that was read, or nil if failure.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fh:read(25, 25)</userinput>
----
-- |-
- elete from t8//
- insert in
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>file-handle</replaceable>:read or <replaceable>file-handle</replaceable>:write(<replaceable>count or new string</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Perform non-random-access read or write on a file. For details type "man 2 read" or "man 2 write".
- Important: <code>read</code> and <code>write</code> affect the seek position within the file,
- and this must be taken into account when working on the same file from multiple fibers.
- It is possible to limit or prevent or prevent file access from other fibers with <code>fiber.ipc</code>.
- </para>
- <para>
- Parameters: (type = table) file-handle as returned by <code>fio.open</code>, (type = string) value to write or (type = number) number of bytes to read.
- </para>
- <para>
- Returns: <code>write</code> returns true if success, false if failure. <code>read</code> returns the data that was read, or nil if failure.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fh:write('new data')</userinput>
----
-- true
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>file-handle</replaceable>:truncate(<replaceable>new-size</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Change the size of an open file.
- Differs from <code>fio.truncate</code>, which changes the size of a closed file.
- </para>
- <para>
- Parameters: (type = table) file-handle as returned by <code>fio.open</code>, (type = number) new file size.
- </para>
- <para>
- Returns: (type = boolean) true if success, false if failure.
- </para>
- <para>
- Possible errors:
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fh:truncate(0)</userinput>
----
-- true
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>file-handle</replaceable>:seek(<replaceable>position</replaceable> [, <replaceable>offset-from</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Shift position in the file to the specified position.
- For details type "man 2 seek".
- </para>
- <para>
- Parameters: (type = table) file handle as returned by <code>fio.open</code>,
- (type = number) position to seek to, (type = constant string) 'SEEK_END' = end of file,
- 'SEEK_CUR' = current position, 'SEEK_SET' = start of file.
- </para>
- <para>
- Returns: (type = number) the new position if success, nil if failure.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fh:seek(20, 'SEEK_SET')</userinput>
----
-- 20
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>file-handle</replaceable>:stat()</emphasis></term>
- <listitem>
- <para>
- Return statistics about an open file.
- This differs from <code>fio.stat</code> which return statistics about a closed file.
- For details type "man 2 stat".
- </para>
- <para>
- Parameters: (type = table) file handle as returned by <code>fio.open()</code>.
- </para>
- <para>
- Returns: (type = table) details about the file.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fh:stat()</userinput>
----
-- inode: 729866
- rdev: 0
- size: 100
- atime: 1409429855
- mode: 33261
- mtime: 1409430660
- nlink: 1
- uid: 1000
- blksize: 4096
- gid: 1000
- ctime: 1409430660
- dev: 2049
- blocks: 8
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>file-handle</replaceable>:fsync or <replaceable>file-handle</replaceable>:fdatasync ()</emphasis></term>
- <listitem>
- <para>
- Ensure that file changes are written to disk, for an open file.
- Compare <code>fio.sync</code>, which is for all files.
- For details type "man 2 fsync" or "man 2 fdatasync".
- </para>
- <para>
- Parameters: (type = table) file-handle, as returned by <code>fio.open()</code>.
- </para>
- <para>
- Returns: (type = boolean) true if success, false if failure.
- </para>
- <bridgehead renderas="sect4">Example</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>fh:fsync()</userinput>
----
-- true
-...
-</programlisting>
- </listitem>
- </varlistentry>
-
- </variablelist>
-</section>
-
-
-<section xml:id="sp-console">
- <title>package <code>console</code></title>
-
- <para>
- The console package allows one Tarantool server
- to access another Tarantool server, and allows
- one Tarantool server to start listening on an
- administrative host/port.
- </para>
-
-
-<variablelist>
-
- <varlistentry>
- <term xml:id="console-connect" xreflabel="console-connect"><emphasis role="lua">console.connect(<replaceable>URI</replaceable>[, <replaceable>options</replaceable>])</emphasis></term>
- <listitem>
- <para>
- Connect to the server at <link linkend="URI">URI</link>, change the prompt from
- 'tarantool' to 'host:port', and act henceforth as a client
- until the user ends the session or types control-D.
- </para>
- <para>
- The console.connect function allows one Tarantool server,
- in interactive mode, to access another Tarantool
- server over a TCP connection. Subsequent requests
- will appear to be handled locally, but in reality
- the requests are being sent to the remote server
- and the local server is acting as a client.
- Once connection is successful, the prompt
- will change and subsequent requests are sent
- to, and executed on, the remote server.
- Results are displayed on the local server.
- To return to local mode, enter control-D.
- </para>
- <para>
- There are no restrictions on the types of requests
- that can be entered, except those which are due to
- privilege restrictions -- by default the login to the remote
- server is done with user name = 'guest'. The remote
- server could allow for this by granting at least
- one privilege:
- <code>box.schema.user.grant('guest','execute','universe')</code>.
- </para>
- <para>
- Parameters: <code>URI</code>, <code>options</code>.
- The options may be necessary if the Tarantool server at host:port requires
- authentication. In such a case the connection might look something like:
- <code>console.connect('netbox:123@127.0.0.1'})</code>.
- </para>
- <para>
- Returns: nothing.
- </para>
- <para>
- Possible errors: the connection will fail if the target Tarantool server
- was not initiated with <code>box.cfg{listen=...}</code>.
- </para>
- <para>
- <bridgehead renderas="sect4">Example showing use of console</bridgehead><programlisting>
-<prompt>tarantool></prompt> <userinput>console = require('console')</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>console.connect('198.18.44.44:3301')</userinput>
----
-...
-<prompt>198.18.44.44:3301></prompt> <userinput>-- prompt is telling us that server is remote</userinput></programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">console.listen(<replaceable>host</replaceable>,<replaceable>port</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Listen on host:port. The primary way of listening for incoming
- requests is via the host and port, or <link linkend="URI">URI</link>, specified in
- <code>box.cfg{listen=...}</code>. The alternative way of
- listening is via the host and port, or URI, specified in
- <code>console.listen(...)</code>. This alternative way is
- called "administrative" or simply "admin port".
- </para>
- <para>
- Parameters: <code>host</code>, <code>port</code>.
- The listening is usually over a local host with a Unix socket,
- specified as host = 'unix/', port = 'path/to/something.sock'.
- </para>
- <para xml:id="admin_port" xreflabel="admin_port">
- The "admin" address is the port or <link linkend="URI">URI</link> to listen on for administrative
- connections. It has no default value, so it must be specified
- if connections will occur via telnet. It is not used unless
- assigned a value. The parameters may be expressed with URI = Universal
- Resource Identifier format, for example "unix://unix_domain_socket",
- or as a numeric TCP port. Connections are often made with telnet.
- A typical port value is 3313.
- </para>
- </listitem>
- </varlistentry>
-
-
-
- </variablelist>
-
-
-
-
-
-
-</section>
-
-
-<section xml:id="sp-log">
- <title>package <code>log</code></title>
- <para>
- The Tarantool server puts all diagnostic messages in a log file
- specified by the <link linkend="logger">logger</link>
- configuration parameter. Diagnostic messages may be either
- system-generated by the server's internal code, or user-generated
- with the <code>log.<replaceable>log_level_function_name</replaceable></code> function.
- </para>
-<variablelist>
- <varlistentry>
- <term><emphasis role="lua">log.<replaceable>log_level_function_name</replaceable>(<replaceable>log_message</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Output a user-generated message to the <link linkend="logger">log file</link>, given
- log_level_function_name = <code>error</code> or <code>warn</code> or <code>info</code>
- or <code>debug</code> or <code>rotate</code>.
- </para>
- <para>
- Returns: nothing.
- </para>
- <para>
- Parameters: (type = string) log_message. The actual output will be a
- line containing the current timestamp, a module name, 'E' or 'W' or 'I' or 'D' or 'R' depending on
- log_level_function_name, and log_message. Output will not occur if log_level_function_name is for a type greater than
- <link linkend="log_level">log_level</link>.
- </para>
- <para>
- <bridgehead renderas="sect4">Example showing use of log</bridgehead><programlisting>
-#From the shell:
-#Start the server, do some requests, exit, and display the log, thus:
-~/tarantool/src/tarantool
-box.cfg{log_level=3, logger='tarantool.txt'}
-log = require('log')
-log.error('Error')
-log.info('Info')
-os.exit()
-less tarantool.txt
-</programlisting>
- The output from the <code>less</code> command will look approximately like this:
-<programlisting>
-2014-09-21 17:58:40.820 [5257] main/101/interactive C> version 1.6.3-355-ga4f762d
-2014-09-21 17:58:40.821 [5257] main/101/interactive C> log level 3
-2014-09-21 17:58:40.821 [5261] main/101/spawner C> initialized
-2014-09-21 17:58:40.830 [5257] main/101/interactive [C]:-1 E> Error
-</programlisting>
- The 'Error' line is visible in tarantool.txt preceded by the letter E.
- The 'Info' line is not present because the log_level is 3.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-</section>
-
-<section xml:id="sp-tap">
- <title>package <code>tap</code></title>
- <para>
- The tap package streamlines the testing of other packages.
- It allows writing of tests in the <link xlink:href="https://en.wikipedia.org/wiki/Test_Anything_Protocol">TAP protocol</link>.
- The results from the tests can be parsed by standard TAP-analyzers
- so they can be passed to utilities such as <link xlink:href="https://metacpan.org/pod/distribution/Test-Harness/bin/prove">prove</link>.
- Thus one can run tests and then use the results for statistics, decision-making, and so on.
- </para>
-<variablelist>
-
- <varlistentry>
- <term><emphasis role="lua">tap.test(<replaceable>test-name</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Initialize -- the result of <code>tap.test</code> is an object,
- which will be called <code>taptest</code> in the rest of this discussion,
- which is necessary for <code>taptest:plan()</code> and all the other methods.
- </para>
- <para>
- Returns: (table) taptest.
- </para>
- <para>
- Parameters: (type = string) test-name = an arbitrary name to give for the test outputs.
- </para>
- <para>
- Example: <code><userinput>tap = require('tap') taptest = tap.test('test-name')</userinput></code>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>taptest</replaceable>:plan(<replaceable>count</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Indicate how many tests will be performed.
- </para>
- <para>
- Returns: nothing.
- </para>
- <para>
- Parameters: (type = number) count.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>taptest</replaceable>:check()</emphasis></term>
- <listitem>
- <para>
- Checks the number of tests performed.
- This check should only be done after all planned tests are complete,
- so ordinarily <code>taptest:check()</code> will only appear at the end of a script.
- </para>
- <para>
- Returns: nothing. Will display '# bad plan: ...' if the number of completed
- tests is not equal to the number of tests specified by <code>taptest:plan(...)</code>.
- </para>
- <para>
- Parameters: none.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>taptest</replaceable>:diag(<replaceable>message</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Display a diagnostic message.
- </para>
- <para>
- Returns: nothing. The message will be displayed.
- </para>
- <para>
- Parameters: the message to be displayed.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>taptest</replaceable>:ok(<replaceable>condition</replaceable>, <replaceable>test-name</replaceable>)</emphasis></term>
- <listitem>
- <para>
- This is a basic function which is used by other functions.
- Depending on the value of <code>condition</code>, print 'ok' or 'not ok' along with debugging information.
- </para>
- <para>
- Returns: true or false. Also displays 'true' or 'false'.
- </para>
- <para>
- Parameters: (boolean expression) <code>condition</code> == an expression which is true or false, (string) test-name.
- </para>
- <para>
- Example:<programlisting>tarantool> <userinput>taptest:ok(true,'x')</userinput>
-ok - x
----
-- true
-...
-tarantool> <userinput>tap = require('tap')</userinput>
----
-...
-tarantool> <userinput>taptest = tap.test('test-name')</userinput>
-TAP version 13
----
-...
-tarantool> <userinput>taptest:ok(1 + 1 == 2, 'X')</userinput>
-ok - X
----
-- true
- ...</programlisting></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>taptest</replaceable>:fail(<replaceable>test-name</replaceable>)</emphasis></term>
- <listitem>
- <para>
- <code>taptest:fail('x')</code> is equivalent to <code>taptest:ok(false, 'x')</code>.
- </para>
- <para>
- Returns: true or false.
- </para>
- <para>
- Parameters: (string) test-name.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>taptest</replaceable>:skip(<replaceable>message</replaceable>)</emphasis></term>
- <listitem>
- <para>
- <code>taptest:skip('x')</code> is equivalent to <code>taptest:ok(true, 'x' .. '# skip')</code>.
- </para>
- <para>
- Returns: nothing. Displays the message
- </para>
- <para>
- Parameters: (string) message.
- </para>
- <para>
- Example: <code>taptest:skip('message')</code> will return <code>ok - message # skip</code>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>taptest</replaceable>:is(<replaceable>got</replaceable>, <replaceable>expected</replaceable>, <replaceable>test-name</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Check whether the first argument equals the second argument.
- </para>
- <para>
- Returns: true or false. Displays extensive message if the result is false.
- </para>
- <para>
- Parameters: (number) <code>got</code> = actual result, (number) <code>expected</code> = expected result, (string) test-name.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>taptest</replaceable>:isnt(<replaceable>got</replaceable>, <replaceable>expected</replaceable>, <replaceable>test-name</replaceable>)</emphasis></term>
- <listitem>
- <para>
- This is the negation of <code>taptest:is(...)</code>.
- </para>
- <para>
- Returns: true or false.
- </para>
- <para>
- Parameters: (number) <code>got</code> = actual result, (number) <code>expected</code> = expected result, (string) test-name.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>taptest</replaceable>:is<replaceable>type-name</replaceable>(<replaceable>value</replaceable>, <replaceable>test-name</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Test whether a value has a particular type. The possible functions in this group are:
- <code>isnil</code>, <code>isstring</code>, <code>isnumber</code>, <code>istable</code>, <code>isboolean</code>, <code>isudata</code>, <code>iscdata</code>.
- </para>
- <para>
- Returns: true or false. Displays a long message if the value is not of the specified type.
- </para>
- <para>
- Parameters: (nil or string or number or table or boolean or udata or cdata) value, (string) test-name.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua"><replaceable>taptest</replaceable>:is_deeply(<replaceable>got</replaceable>,<replaceable>expected</replaceable>, <replaceable>test-name</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Recursive version of <code>taptestis(...)</code>, which can be
- be used to compare tables as well as scalar values.
- </para>
- <para>
- Returns: true or false.
- </para>
- <para>
- Parameters: (number or table) <code>got</code> = actual result, (number or table) <code>expected</code> = expected result, (string) test-name.
- </para>
-
- <para>
- <bridgehead renderas="sect4">Example Lua script showing use of tap</bridgehead>
- To run this example: put the script in a file named ./tap.lua, then make tap.lua
- executable by saying <code>chmod a+x ./tap.lua</code>, then execute using Tarantool
- as a script processor by saying <code>./tap.lua</code>.
- <programlisting>
-#!/usr/bin/tarantool
-local tap = require('tap')
-test = tap.test("my test name")
-test:plan(2)
-test:ok(2 * 2 == 4, "2 * 2 is 4")
-test:test("some subtests for test2", function(test)
- test:plan(2)
- test:is(2 + 2, 4, "2 + 2 is 4")
- test:isnt(2 + 3, 4, "2 + 3 is not 4")
-end)
-test:check()
-</programlisting>
- The output from the above script will look approximately like this:
-<programlisting>
-TAP version 13
-1..2
-ok - 2 * 2 is 4
- # Some subtests for test2
- 1..2
- ok - 2 + 2 is 4,
- ok - 2 + 3 is not 4
- # Some subtests for test2: end
-ok - some subtests for test2
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-</section>
-
-<section xml:id="sp-tonumber64">
- <title>Lua functions <code>tonumber64</code> and <code>dostring</code></title>
-
-<variablelist>
-
- <varlistentry>
- <term xml:id="tonumber64" xreflabel="tonumber64"> <emphasis role="lua">tonumber64(<replaceable>value</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Convert a string or a Lua number to a
- 64-bit integer. The result can be used in arithmetic,
- and the arithmetic will be 64-bit integer arithmetic
- rather than floating-point arithmetic. (Operations on
- an unconverted Lua number use floating-point arithmetic.)
- The tonumber64() function is added by Tarantool; the name is global.
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-tarantool> <userinput>type(123456789012345), type(tonumber64(123456789012345))</userinput>
----
-- number
-- number
-...
-tarantool> <userinput>i = tonumber64('1000000000')</userinput>
----
-...
-tarantool> <userinput>type(i), i / 2, i - 2, i * 2, i + 2, i % 2, i ^ 2</userinput>
----
- - number
- - 500000000
- - 999999998
- - 2000000000
- - 1000000002
- - 0
- - 1000000000000000000
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">dostring(<replaceable>lua-chunk-string [, lua-chunk-string-argument ...]</replaceable>)</emphasis>
- </term>
- <listitem>
- <para>
- Parse and execute an arbitrary chunk of Lua code.
- This function is mainly useful to define and run
- Lua code without having to
- introduce changes to the global Lua environment.
- </para>
- <para>
- Parameters: <code>lua-chunk-string</code> = string containing Lua code,
- <code>lua-chunk-string-argument(s)</code> = zero or more scalar values
- which will be appended to, or substitute for, items in the Lua chunk.
- </para>
- <para>
- Returns: whatever is returned by the Lua code chunk.
- </para>
- <para>
- Possible errors: If there is a compilation error,
- it is raised as a Lua error.
- </para>
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-tarantool> <userinput>dostring('abc')</userinput>
----
-error: '[string "abc"]:1: ''='' expected near ''<eof>'''
-...
-tarantool> <userinput>dostring('return 1')</userinput>
----
-- 1
-...
-tarantool> <userinput>dostring('return ...', 'hello', 'world')</userinput>
----
-- hello
-- world
-...
-tarantool> <userinput>console = require('console'); console.delimiter('!') --<link linkend="utility-tarantool-delim">this</link> means ignore line feeds until next '!'</userinput>
-tarantool> <userinput>-- Use <link xlink:href="http://www.lua.org/pil/2.4.html">double square brackets</link> to enclose multi-line literal here!</userinput>
-tarantool> <userinput>dostring([[local f = function(key)</userinput>
- -> <userinput> t = box.space.tester:select{key};</userinput>
- -> <userinput> if t ~= nil then return t[1] else return nil end</userinput>
- -> <userinput> end</userinput>
- -> <userinput> return f(...)]], 1)!</userinput>
----
-- null
-...
-tarantool> <userinput>console.delimiter('')!</userinput>
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
-</variablelist>
-
-</section>
-
-
-<section xml:id="sp-pickle">
- <title>Package <code>pickle</code></title>
-<variablelist xml:id="x-pickle" xreflabel="x-pickle">
- <varlistentry>
- <term><emphasis role="lua">pickle.pack(<replaceable>format, argument [, argument ...]</replaceable>)</emphasis></term>
- <listitem><para>
- To use Tarantool binary protocol primitives from Lua,
- it's necessary to convert Lua variables to binary
- format. The pickle.pack() helper function is prototyped after Perl
- <link xlink:href="http://perldoc.perl.org/functions/pack.html">
- 'pack'</link>.
- </para>
- <para>
- Parameters: <code>format</code> = string containing format specifiers, <code>argument(s)</code> = scalar values to be formatted.
- </para>
- <para>
- <bridgehead renderas="sect4">Format specifiers</bridgehead>
- <simplelist>
- <member><code>b</code> or <code>B</code> — converts Lua
- variable to a 1-byte
- integer, and stores the integer in the resulting
- string,
- </member>
- <member><code>s</code> or <code>S</code> — converts Lua
- variable to a 2-byte
- integer, and stores the integer in the resulting
- string, low byte first,
- </member>
- <member><code>i</code> or <code>I</code> — converts Lua
- variable to a 4-byte
- integer, and stores the integer in the resulting
- string, low byte first,
- </member>
- <member><code>l</code> or <code>L</code> — converts Lua
- variable to an 8-byte
- integer, and stores the integer in the resulting
- string, low byte first,
- </member>
- <member><code>n</code> or <code>N</code> — converts Lua
- variable to a 4-byte
- integer, and stores the integer in the resulting
- string, big endian,
- </member>
- <member><code>q</code> or <code>Q</code> — converts Lua
- variable to an 8-byte
- integer, and stores the integer in the resulting
- string, big endian,
- </member>
- <member><code>f</code> — converts Lua
- variable to a 4-byte
- float, and stores the float in the resulting
- string,
- </member>
- <member><code>d</code> — converts Lua
- variable to a 8-byte
- double, and stores the double in the resulting
- string,
- </member>
- <member><code>d</code> — converts Lua
- variable to a sequence of bytes,
- and stores the sequence in the resulting
- string,
- </member>
- </simplelist>
- </para>
- <para>
- Returns: a binary string containing all arguments, packed
- according to the format specifiers.
- </para>
- <para>
- Possible Errors: Unknown format specifier.
- </para>
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-tarantool> <userinput>pickle = require('pickle')</userinput>
----
-...
-tarantool> <userinput>box.space.tester:insert{0, 'hello world'}</userinput>
----
-- [0, 'hello world']
-...
-tarantool> <userinput>box.space.tester:update({0}, {{'=', 2, 'bye world'}})</userinput>
----
-- [0, 'bye world']
-...
-tarantool> <userinput>box.space.tester:update({0}, {{'=', 2, pickle.pack('iiA', 0, 3, 'hello')}})</userinput>
----
-- [0, "\0\0\0\0\x03\0\0\0hello"]
-...
-tarantool> <userinput>box.space.tester:update({0}, {{'=', 2, 4}})</userinput>
----
-- [0, 4]
-...
-tarantool> <userinput>box.space.tester:update({0}, {{'+', 2, 4}})</userinput>
----
-- [0, 8]
-...
-tarantool> <userinput>box.space.tester:update({0}, {{'^', 2, 4}})</userinput>
----
-- [0, 12]
-...
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="lua">pickle.unpack(<replaceable>format, binary-string</replaceable>)</emphasis></term>
- <listitem>
- <para>
- Counterpart to <code>pickle.pack()</code>.
- </para>
- <para>
- Parameters: <code>format</code>, <code>binary-string</code>.
- </para>
- <para>
- Returns: (type = scalar) A list of strings or numbers.
- </para>
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
-<programlisting>
-<prompt>tarantool</prompt> <userinput>pickle = require('pickle')</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>console = require('console'); console.delimiter('!') -- this means following commands must end with '!'</userinput>
-<prompt>tarantool></prompt> <userinput>tuple = box.space.tester:replace{0}!</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>string.len(tuple[1])!</userinput>
----
-- 1
-...
-<prompt>tarantool></prompt> <userinput>pickle.unpack('b', tuple[1])!</userinput>
----
-- 48
-...
-<prompt>tarantool></prompt> <userinput>pickle.unpack('bsi', pickle.pack('bsi', 255, 65535, 4294967295))!</userinput>
----
-- 255
-- 65535
-- 4294967295
-...
-<prompt>tarantool></prompt> <userinput>pickle.unpack('ls', pickle.pack('ls', tonumber64('18446744073709551615'), 65535))!</userinput>
----
-- 18446744073709551615
-- 65535
-...
-<prompt>tarantool></prompt> <userinput>num, str, num64 = pickle.unpack('sAl', pickle.pack('sAl', 666, 'string',</userinput>
-<prompt> -></prompt> <userinput> tonumber64('666666666666666')))!</userinput>
----
-...
-<prompt>tarantool></prompt> <userinput>console.delimiter('') -- back to normal: commands end with line feed!</userinput>
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</section>
-
-
-<section xml:id="sp-expirationd">
- <title>expirationd -- the daemon that shifts expired tuples to a long-term archive</title>
-
-<para>
-For a commercial-grade example of a Lua rock that works with Tarantool,
-let us look at expirationd, which Tarantool supplies on
-<link xlink:href="https://github.com/tarantool/expirationd/blob/master/expirationd.lua">GitHub</link>
-with an Artistic license. The expirationd.lua program is
-lengthy (about 500 lines), so here we will only highlight
-the matters that will be enhanced by studying the full source later.
-<programlisting>
- task.worker_fiber = fiber.create(worker_loop, task)
- log.info("expiration: task %q restarted", task.name)
- ...
- fiber.sleep(expirationd.constants.check_interval)
- ...
-</programlisting>
-Whenever one hears "daemon" in Tarantool, one should suspect it's
-being done with <olink targetptr="sp-box-fiber">fibers</olink>. The program is making a fiber
-and turning control over to it so it runs occasionally, goes to
-sleep, then comes back for more.
-<programlisting>
- for _, tuple in scan_space.index[0]:pairs(nil, {iterator = box.index.ALL}) do
- ...
- if task.is_tuple_expired(task.args, tuple) then
- task.expired_tuples_count = task.expired_tuples_count + 1
- task.process_expired_tuple(task.space_id, task.args, tuple)
- ...
-</programlisting>
-The "for" instruction can be translated as "iterate through the index of
-the space that is being scanned", and within it, if the tuple is "expired"
-(that is, if the tuple has a timestamp field which is less than the current
-time), process the tuple as an expired tuple.
-<programlisting>
--- put expired tuple in archive
-local function put_tuple_to_archive(space_id, args, tuple)
- -- delete expired tuple
- box.space[space_id]:delete{tuple[1]}
- local email = get_field(tuple, 2)
- if args.archive_space_id ~= nil and email ~= nil then
- box.space[args.archive_space_id]:replace{email, os.time()}
- end
-end
-</programlisting>
-Ultimately the tuple-expiry process leads to put_tuple_to_archive()
-which does a "delete" of a tuple from its original space, and an
-"insert" of the same tuple into another space. Tarantool's "replace"
-function is the same as an "insert" function without an error message
-if a tuple with the same content already exists in the target space.
-<programlisting>
-function expirationd.do_test(space_id, archive_space_id)
-...
-</programlisting>
-At this point, if the above explanation is worthwhile, it's clear that
-expirationd.lua starts a background routine (fiber) which iterates
-through all the tuples in a space, sleeps cooperatively so that other
-fibers can operate at the same time, and -- whenever it finds a tuple
-that has expired -- deletes it from this space and puts it in another
-space. Now the "do_test()" function can be used to create some sample
-spaces, let the daemon run for a while, and print results.
-</para>
-<para>
-For those who like to see things run, here are the exact steps to
-get expirationd through the test.
-</para>
-<para>
-1. Get expirationd.lua.
- There are standard ways -- it is after all part of <link linkend="rocks">a standard rock</link> --
- but for this purpose just copy the contents of
- <link xlink:href="https://github.com/tarantool/expirationd/blob/master/expirationd.lua">https://github.com/tarantool/expirationd/blob/master/expirationd.lua</link>
- to a default directory.
-</para>
-<para>
-2. Start the Tarantool server as described <olink targetptr="getting-started-start-stop">before</olink>.
-</para>
-<para>
-3. Execute these requests:
-<programlisting><userinput>
- box.cfg{}
- a = box.schema.space.create('origin')
- a:create_index('first', {type = 'tree', parts = {1, 'NUM'}})
- b = box.schema.space.create('archive')
- b:create_index('first', {type = 'tree', parts = {1, 'STR'}})
- expd = require('expirationd')
- expd._debug = true
- expd.do_test('origin', 'archive')
- os.exit()
-</userinput></programlisting>
-The database-specific requests (cfg, space.create, create_index)
-should already be familiar. The key for getting the rock rolling is
-<code>expd = require('expirationd')</code>.
-The "require" function is what reads in the program; it will appear
-in many later examples in this manual, when it's necessary to get a
-package that's not part of the Tarantool kernel. After the Lua
-variable expd has been assigned the value of the expirationd package,
-it's possible to invoke the package's <code>do_test()</code> function.
-</para>
-<para>
-After a while, when the task has had time to do its iterations through
-the spaces, do_test() will print out a report showing the tuples that
-were originally in the original space, the tuples that have now been
-moved to the archive space, and some statistics. Of course, expirationd
-can be customized to do different things by passing different parameters,
-which will be evident after looking in more detail at the source code.
-</para>
-
-</section>
-
-</section>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/target.db b/doc/user/target.db
deleted file mode 100644
index 8eefc54c5319b1effd04c5358cdd2b6ecf9ec13c..0000000000000000000000000000000000000000
--- a/doc/user/target.db
+++ /dev/null
@@ -1,7 +0,0 @@
-<div element="book" href="#tarantool-user-guide" number="" targetptr="tarantool-user-guide"><ttl>Tarantool User Guide, version 1.6.1-279-ga84cec2</ttl><xreftext>Tarantool User Guide, version 1.6.1-279-ga84cec2</xreftext><div element="chapter" href="#preface" number="1" targetptr="preface"><ttl>Preface</ttl><xreftext>Chapter 1, <i>Preface</i></xreftext><div element="section" href="#tarantool-overview" number="" targetptr="tarantool-overview"><ttl>Tarantool: an overview</ttl><xreftext>the section called “Tarantool: an overviewâ€</xreftext></div><div element="section" href="#manual-conventions" number="" targetptr="manual-conventions"><ttl>Conventions</ttl><xreftext>the section called “Conventionsâ€</xreftext></div><div element="section" href="#reporting-bugs" number="" targetptr="reporting-bugs"><ttl>Reporting bugs</ttl><xreftext>the section called “Reporting bugsâ€</xreftext></div></div><div element="chapter" href="#getting-started" number="2" targetptr="getting-started"><ttl>Getting started</ttl><xreftext>Chapter 2, <i>Getting started</i></xreftext><div element="section" href="#getting-started-binary" number="" targetptr="getting-started-binary"><ttl>Downloading and installing a binary package</ttl><xreftext>the section called “Downloading and installing a binary packageâ€</xreftext></div><div element="section" href="#getting-started-source" number="" targetptr="getting-started-source"><ttl>Downloading and building a source package</ttl><xreftext>the section called “Downloading and building a source packageâ€</xreftext></div><div element="section" href="#getting-started-start-stop" number="" targetptr="getting-started-start-stop"><ttl>Starting Tarantool and making your first database</ttl><xreftext>the section called “Starting Tarantool and making your first databaseâ€</xreftext></div><div element="section" href="#differences-from-older-versions" number="" targetptr="differences-from-older-versions"><ttl>Differences between Tarantool 1.6 and older versions</ttl><xreftext>the section called “Differences between Tarantool 1.6 and older versionsâ€</xreftext></div></div><div element="chapter" href="#data-and-persistence" number="3" targetptr="data-and-persistence"><ttl>Data model and data persistence</ttl><xreftext>Chapter 3, <i>Data model and data persistence</i></xreftext><div element="section" href="#dynamic-data-model" number="" targetptr="dynamic-data-model"><ttl>Dynamic data model</ttl><xreftext>the section called “Dynamic data modelâ€</xreftext></div><div element="section" href="#data-persistence" number="" targetptr="data-persistence"><ttl>Data persistence</ttl><xreftext>the section called “Data persistenceâ€</xreftext></div></div><div element="chapter" href="#language-reference" number="4" targetptr="language-reference"><ttl>Language reference</ttl><xreftext>Chapter 4, <i>Language reference</i></xreftext><div element="section" href="#data-manipulation" number="" targetptr="data-manipulation"><ttl>Data manipulation</ttl><xreftext>the section called “Data manipulationâ€</xreftext></div><div element="section" href="#administrative-console" number="" targetptr="administrative-console"><ttl>Administrative console</ttl><xreftext>the section called “Administrative consoleâ€</xreftext><obj element="term" href="#box.snapshot" number="" targetptr="box.snapshot"><ttl>???TITLE???</ttl><xreftext>box.snapshot()</xreftext></obj><obj element="term" href="#box.cfg.reload" number="" targetptr="box.cfg.reload"><ttl>???TITLE???</ttl><xreftext>box.cfg.reload()</xreftext></obj><obj element="term" href="#box.cfg.show" number="" targetptr="box.cfg.show"><ttl>???TITLE???</ttl><xreftext>box.cfg()</xreftext></obj><obj element="term" href="#box.info" number="" targetptr="box.info"><ttl>???TITLE???</ttl><xreftext>box.info()</xreftext></obj><obj element="term" href="#show-index" number="" targetptr="show-index"><ttl>???TITLE???</ttl><xreftext>SHOW INDEX</xreftext></obj><obj element="term" href="#box.stat.show" number="" targetptr="box.stat.show"><ttl>???TITLE???</ttl><xreftext>box.stat.show()</xreftext></obj><obj element="term" href="#box.slab.info" number="" targetptr="box.slab.info"><ttl>???TITLE???</ttl><xreftext>box.slab.info()</xreftext></obj><obj element="term" href="#box.coredump" number="" targetptr="box.coredump"><ttl>???TITLE???</ttl><xreftext>box.coredump()</xreftext></obj><obj element="term" href="#box.fiber.info" number="" targetptr="box.fiber.info"><ttl>???TITLE???</ttl><xreftext>box.fiber.info()</xreftext></obj><obj element="term" href="#lua-command" number="" targetptr="lua-command"><ttl>???TITLE???</ttl><xreftext>
- <span class="tntadmin">...</span>
- </xreftext></obj></div><div element="section" href="#stored-procedures" number="" targetptr="stored-procedures"><ttl>Writing stored procedures in Lua</ttl><xreftext>the section called “Writing stored procedures in Luaâ€</xreftext><obj element="filename" href="#init.lua" number="" targetptr="init.lua"><ttl>???TITLE???</ttl><xreftext>init.lua</xreftext></obj><obj element="term" href="#tonumber64" number="" targetptr="tonumber64"><ttl>???TITLE???</ttl><xreftext>tonumber64</xreftext></obj><div element="section" href="#sp-box-library" number="" targetptr="sp-box-library"><ttl>The <code class="code">box</code> library</ttl><xreftext>the section called “The <code class="code">box</code> libraryâ€</xreftext><obj element="table" href="#idp724256" number="4.1"><ttl>Possible types of the values that a function in the box library can return</ttl><xreftext>Table 4.1, “Possible types of the values that a function in the box library can returnâ€</xreftext></obj><obj element="title" href="#function-types" number="" targetptr="function-types"><ttl>Possible types of the values that a function in the box library can return</ttl><xreftext>Table 4.1, “Possible types of the values that a function in the box library can returnâ€</xreftext></obj><obj element="entry" href="#function-type-number" number="" targetptr="function-type-number"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="entry" href="#function-type-string" number="" targetptr="function-type-string"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="entry" href="#function-type-nil" number="" targetptr="function-type-nil"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="entry" href="#function-type-lua-table" number="" targetptr="function-type-lua-table"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="entry" href="#function-type-tuple" number="" targetptr="function-type-tuple"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj></div><div element="section" href="#sp-box" number="" targetptr="sp-box"><ttl>Package <code class="code">box</code></ttl><xreftext>the section called “Package <code class="code">box</code>â€</xreftext><obj element="variablelist" href="#box" number="" targetptr="box"><ttl>???TITLE???</ttl><xreftext>box</xreftext></obj><obj element="emphasis" href="#box.process" number="" targetptr="box.process"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.select" number="" targetptr="box.select"><ttl>???TITLE???</ttl><xreftext>box.select</xreftext></obj><obj element="emphasis" href="#box.insert" number="" targetptr="box.insert"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.select_limit" number="" targetptr="box.select_limit"><ttl>???TITLE???</ttl><xreftext>box.select_limit</xreftext></obj><obj element="emphasis" href="#box.replace" number="" targetptr="box.replace"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.update" number="" targetptr="box.update"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.delete" number="" targetptr="box.delete"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.select_range" number="" targetptr="box.select_range"><ttl>???TITLE???</ttl><xreftext>box.select_range</xreftext></obj><obj element="emphasis" href="#box.select_reverse_range" number="" targetptr="box.select_reverse_range"><ttl>???TITLE???</ttl><xreftext>box.select_reverse_range</xreftext></obj></div><div element="section" href="#sp-box-tuple" number="" targetptr="sp-box-tuple"><ttl>Package <code class="code">box.tuple</code></ttl><xreftext>the section called “Package <code class="code">box.tuple</code>â€</xreftext><obj element="variablelist" href="#box.tuple" number="" targetptr="box.tuple"><ttl>???TITLE???</ttl><xreftext>box.tuple</xreftext></obj></div><div element="section" href="#sp-box-cjson" number="" targetptr="sp-box-cjson"><ttl>Package <code class="code">box.cjson</code></ttl><xreftext>the section called “Package <code class="code">box.cjson</code>â€</xreftext><obj element="variablelist" href="#box.cjson" number="" targetptr="box.cjson"><ttl>???TITLE???</ttl><xreftext>box.cjson</xreftext></obj></div><div element="section" href="#sp-box-space" number="" targetptr="sp-box-space"><ttl>Package <code class="code">box.space</code></ttl><xreftext>the section called “Package <code class="code">box.space</code>â€</xreftext><obj element="variablelist" href="#box.space" number="" targetptr="box.space"><ttl>???TITLE???</ttl><xreftext>box.space</xreftext></obj><obj element="emphasis" href="#box.space.select_range" number="" targetptr="box.space.select_range"><ttl>???TITLE???</ttl><xreftext>box.space[i].select_range()</xreftext></obj><obj element="emphasis" href="#box.space.select_reverse_range" number="" targetptr="box.space.select_reverse_range"><ttl>???TITLE???</ttl><xreftext>box.space.select_reverse_range</xreftext></obj></div><div element="section" href="#sp-box-index" number="" targetptr="sp-box-index"><ttl>Package <code class="code">box.index</code></ttl><xreftext>the section called “Package <code class="code">box.index</code>â€</xreftext><obj element="variablelist" href="#box.index" number="" targetptr="box.index"><ttl>???TITLE???</ttl><xreftext>box.index</xreftext></obj><obj element="emphasis" href="#box.index.iterator" number="" targetptr="box.index.iterator"><ttl>???TITLE???</ttl><xreftext>box.index.iterator(type, ...)</xreftext></obj><obj element="para" href="#iterator-consistency" number="" targetptr="iterator-consistency"><ttl>???TITLE???</ttl><xreftext/></obj><obj element="para" href="#iterator-types" number="" targetptr="iterator-types"><ttl>???TITLE???</ttl><xreftext/></obj><obj element="table" href="#idp1114672" number="4.2"><ttl>Common iterator types</ttl><xreftext>Table 4.2, “Common iterator typesâ€</xreftext></obj><obj element="table" href="#idp983120" number="4.3"><ttl>TREE iterator types</ttl><xreftext>Table 4.3, “TREE iterator typesâ€</xreftext></obj><obj element="table" href="#idp1000912" number="4.4"><ttl>BITSET iterator types</ttl><xreftext>Table 4.4, “BITSET iterator typesâ€</xreftext></obj></div><div element="section" href="#sp-box-fiber" number="" targetptr="sp-box-fiber"><ttl>Package <code class="code">box.fiber</code></ttl><xreftext>the section called “Package <code class="code">box.fiber</code>â€</xreftext><obj element="variablelist" href="#box.fiber" number="" targetptr="box.fiber"><ttl>???TITLE???</ttl><xreftext>???TITLE???</xreftext></obj><obj element="emphasis" href="#box.fiber.id" number="" targetptr="box.fiber.id"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.fiber.self" number="" targetptr="box.fiber.self"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.fiber.find" number="" targetptr="box.fiber.find"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.fiber.create" number="" targetptr="box.fiber.create"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.fiber.resume" number="" targetptr="box.fiber.resume"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.fiber.yield" number="" targetptr="box.fiber.yield"><ttl>???TITLE???</ttl><xreftext>box.fiber.yield</xreftext></obj><obj element="emphasis" href="#box.fiber.detach" number="" targetptr="box.fiber.detach"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.fiber.wrap" number="" targetptr="box.fiber.wrap"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.fiber.sleep" number="" targetptr="box.fiber.sleep"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.fiber.status" number="" targetptr="box.fiber.status"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.fiber.cancel" number="" targetptr="box.fiber.cancel"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.fiber.testcancel" number="" targetptr="box.fiber.testcancel"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj></div><div element="section" href="#sp-box-session" number="" targetptr="sp-box-session"><ttl>Package <code class="code">box.session</code></ttl><xreftext>the section called “Package <code class="code">box.session</code>â€</xreftext></div><div element="section" href="#sp-box-ipc" number="" targetptr="sp-box-ipc"><ttl>Package <code class="code">box.ipc</code> — inter procedure communication</ttl><xreftext>the section called “Package <code class="code">box.ipc</code> — inter procedure communicationâ€</xreftext><obj element="variablelist" href="#box.ipc" number="" targetptr="box.ipc"><ttl>???TITLE???</ttl><xreftext>???TITLE???</xreftext></obj></div><div element="section" href="#sp-box-socket" number="" targetptr="sp-box-socket"><ttl>Package <code class="code">box.socket</code> — TCP and UDP sockets</ttl><xreftext>the section called “Package <code class="code">box.socket</code> — TCP and UDP socketsâ€</xreftext><obj element="variablelist" href="#box.socket" number="" targetptr="box.socket"><ttl>???TITLE???</ttl><xreftext>???TITLE???</xreftext></obj><obj element="table" href="#idp622752" number="4.5"><ttl><code class="code">readline()</code> returns</ttl><xreftext>Table 4.5, “<code class="code">readline()</code> returnsâ€</xreftext></obj></div><div element="section" href="#sp-box-net-box" number="" targetptr="sp-box-net-box"><ttl>Package <code class="code">box.net.box</code> — working with networked Tarantool peers</ttl><xreftext>the section called “Package <code class="code">box.net.box</code> — working with networked Tarantool peersâ€</xreftext><obj element="variablelist" href="#box.net.box" number="" targetptr="box.net.box"><ttl>???TITLE???</ttl><xreftext>???TITLE???</xreftext></obj><obj element="emphasis" href="#box.net.box.new" number="" targetptr="box.net.box.new"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.net.box.ping" number="" targetptr="box.net.box.ping"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.net.box.close" number="" targetptr="box.net.box.close"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.net.box.select" number="" targetptr="box.net.box.select"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.net.box.select_limit" number="" targetptr="box.net.box.select_limit"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.net.box.select_range" number="" targetptr="box.net.box.select_range"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.net.box.insert" number="" targetptr="box.net.box.insert"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.net.box.replace" number="" targetptr="box.net.box.replace"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.net.box.update" number="" targetptr="box.net.box.update"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.net.box.delete" number="" targetptr="box.net.box.delete"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.net.box.call" number="" targetptr="box.net.box.call"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="emphasis" href="#box.net.box.timeout" number="" targetptr="box.net.box.timeout"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj></div><div element="section" href="#sp-box-cfg" number="" targetptr="sp-box-cfg"><ttl>Packages <code class="code">box.cfg</code>,
- <code class="code">box.info</code>, <code class="code">box.slab</code> and
- <code class="code">box.stat</code>: server introspection</ttl><xreftext>the section called “Packages <code class="code">box.cfg</code>,
- <code class="code">box.info</code>, <code class="code">box.slab</code> and
- <code class="code">box.stat</code>: server introspectionâ€</xreftext><obj element="code" href="#box.cfg" number="" targetptr="box.cfg"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj><obj element="code" href="#box.stat" number="" targetptr="box.stat"><ttl>???TITLE???</ttl><xreftext>???</xreftext></obj></div><div element="section" href="#sp-limitations" number="" targetptr="sp-limitations"><ttl>Limitations of stored procedures</ttl><xreftext>the section called “Limitations of stored proceduresâ€</xreftext></div></div><div element="section" href="#triggers" number="" targetptr="triggers"><ttl>Defining triggers in Lua</ttl><xreftext>the section called “Defining triggers in Luaâ€</xreftext><div element="section" href="#sp-box-session-triggers" number="" targetptr="sp-box-session-triggers"><ttl>Triggers on connect and disconnect</ttl><xreftext>session triggers</xreftext></div></div></div><div element="chapter" href="#replication" number="5" targetptr="replication"><ttl>Replication</ttl><xreftext>Chapter 5, <i>Replication</i></xreftext><div element="section" href="#replication-architecture" number="" targetptr="replication-architecture"><ttl>Replication architecture</ttl><xreftext>the section called “Replication architectureâ€</xreftext></div><div element="section" href="#setting-up-the-master" number="" targetptr="setting-up-the-master"><ttl>Setting up the master</ttl><xreftext>the section called “Setting up the masterâ€</xreftext></div><div element="section" href="#settin-up-a-replica" number="" targetptr="settin-up-a-replica"><ttl>Setting up a replica</ttl><xreftext>the section called “Setting up a replicaâ€</xreftext></div><div element="section" href="#recovering-from-a-degraded-state" number="" targetptr="recovering-from-a-degraded-state"><ttl>Recovering from a degraded state</ttl><xreftext>the section called “Recovering from a degraded stateâ€</xreftext></div></div><div element="chapter" href="#server-administration" number="6" targetptr="server-administration"><ttl>Server administration</ttl><xreftext>Chapter 6, <i>Server administration</i></xreftext><div element="section" href="#signal-handling" number="" targetptr="signal-handling"><ttl>Server signal handling</ttl><xreftext>the section called “Server signal handlingâ€</xreftext></div><div element="section" href="#utility-tarantool" number="" targetptr="utility-tarantool"><ttl>Utility <code class="code">tarantool</code> — the main client</ttl><xreftext>the section called “Utility <code class="code">tarantool</code> — the main clientâ€</xreftext><obj element="term" href="#utility-tarantool-admin-port" number="" targetptr="utility-tarantool-admin-port"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-admin-port</xreftext></obj><obj element="term" href="#utility-tarantool-bin" number="" targetptr="utility-tarantool-bin"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-bin</xreftext></obj><obj element="term" href="#utility-tarantool-cat" number="" targetptr="utility-tarantool-cat"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-cat</xreftext></obj><obj element="term" href="#utility-tarantool-delim" number="" targetptr="utility-tarantool-delim"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-delim</xreftext></obj><obj element="term" href="#utility-tarantool-format" number="" targetptr="utility-tarantool-format"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-format</xreftext></obj><obj element="term" href="#utility-tarantool-from" number="" targetptr="utility-tarantool-from"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-from</xreftext></obj><obj element="term" href="#utility-tarantool-header" number="" targetptr="utility-tarantool-header"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-header</xreftext></obj><obj element="term" href="#utility-tarantool-help" number="" targetptr="utility-tarantool-help"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-help</xreftext></obj><obj element="term" href="#utility-tarantool-host" number="" targetptr="utility-tarantool-host"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-host</xreftext></obj><obj element="term" href="#utility-tarantool-play" number="" targetptr="utility-tarantool-play"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-play</xreftext></obj><obj element="term" href="#utility-tarantool-port" number="" targetptr="utility-tarantool-port"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-port</xreftext></obj><obj element="term" href="#utility-tarantool-rpl" number="" targetptr="utility-tarantool-rpl"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-rpl</xreftext></obj><obj element="term" href="#utility-tarantool-space" number="" targetptr="utility-tarantool-space"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-space</xreftext></obj><obj element="term" href="#utility-tarantool-to" number="" targetptr="utility-tarantool-to"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-to</xreftext></obj><obj element="term" href="#utility-tarantool-version" number="" targetptr="utility-tarantool-version"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-version</xreftext></obj><obj element="term" href="#utility-tarantool-call" number="" targetptr="utility-tarantool-call"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-call</xreftext></obj><obj element="term" href="#utility-tarantool-delete" number="" targetptr="utility-tarantool-delete"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-delete</xreftext></obj><obj element="term" href="#utility-tarantool-exit" number="" targetptr="utility-tarantool-exit"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-exit</xreftext></obj><obj element="term" href="#utility-tarantool-help2" number="" targetptr="utility-tarantool-help2"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-help2</xreftext></obj><obj element="term" href="#utility-tarantool-insert" number="" targetptr="utility-tarantool-insert"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-insert</xreftext></obj><obj element="term" href="#utility-tarantool-loadfile" number="" targetptr="utility-tarantool-loadfile"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-loadfile</xreftext></obj><obj element="term" href="#utility-tarantool-lua" number="" targetptr="utility-tarantool-lua"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-lua</xreftext></obj><obj element="term" href="#utility-tarantool-ping" number="" targetptr="utility-tarantool-ping"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-ping</xreftext></obj><obj element="term" href="#utility-tarantool-quit" number="" targetptr="utility-tarantool-quit"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-quit</xreftext></obj><obj element="term" href="#utility-tarantool-reload" number="" targetptr="utility-tarantool-reload"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-reload</xreftext></obj><obj element="term" href="#utility-tarantool-replace" number="" targetptr="utility-tarantool-replace"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-replace</xreftext></obj><obj element="term" href="#utility-tarantool-save" number="" targetptr="utility-tarantool-save"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-save</xreftext></obj><obj element="term" href="#utility-tarantool-select" number="" targetptr="utility-tarantool-select"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-select</xreftext></obj><obj element="term" href="#utility-tarantool-set" number="" targetptr="utility-tarantool-set"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-set</xreftext></obj><obj element="term" href="#utility-tarantool-setopt" number="" targetptr="utility-tarantool-setopt"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-setopt</xreftext></obj><obj element="term" href="#utility-tarantool-show" number="" targetptr="utility-tarantool-show"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-show</xreftext></obj><obj element="term" href="#utility-tarantool-update" number="" targetptr="utility-tarantool-update"><ttl>???TITLE???</ttl><xreftext>utility-tarantool-update</xreftext></obj></div><div element="section" href="#tarantar" number="" targetptr="tarantar"><ttl>Utility <code class="code">tarantar</code></ttl><xreftext>the section called “Utility <code class="code">tarantar</code>â€</xreftext></div><div element="section" href="#tarancheck" number="" targetptr="tarancheck"><ttl>Utility <code class="code">tarancheck</code></ttl><xreftext>the section called “Utility <code class="code">tarancheck</code>â€</xreftext></div><div element="section" href="#tarantool_deploy" number="" targetptr="tarantool_deploy"><ttl>Utility <code class="code">tarantool_deploy</code></ttl><xreftext>the section called “Utility <code class="code">tarantool_deploy</code>â€</xreftext></div><div element="section" href="#os-install-notes" number="" targetptr="os-install-notes"><ttl>System-specific administration notes</ttl><xreftext>the section called “System-specific administration notesâ€</xreftext><div element="section" href="#Debian" number="" targetptr="Debian"><ttl>Debian GNU/Linux and Ubuntu</ttl><xreftext>the section called “Debian GNU/Linux and Ubuntuâ€</xreftext></div><div element="section" href="#rpm-based-distros" number="" targetptr="rpm-based-distros"><ttl>Fedora, RHEL, CentOS</ttl><xreftext>the section called “Fedora, RHEL, CentOSâ€</xreftext></div><div element="section" href="#FreeBSD" number="" targetptr="FreeBSD"><ttl>FreeBSD</ttl><xreftext>the section called “FreeBSDâ€</xreftext></div><div element="section" href="#mac-os-x" number="" targetptr="mac-os-x"><ttl>Mac OS X</ttl><xreftext>the section called “Mac OS Xâ€</xreftext></div></div></div><div element="chapter" href="#configuration-reference" number="7" targetptr="configuration-reference"><ttl>Configuration reference</ttl><xreftext>Chapter 7, <i>Configuration reference</i></xreftext><div element="section" href="#command-line-options" number="" targetptr="command-line-options"><ttl>Command line options</ttl><xreftext>the section called “Command line optionsâ€</xreftext><obj element="listitem" href="#help-option" number="" targetptr="help-option"><ttl>???TITLE???</ttl><xreftext/></obj><obj element="listitem" href="#version-option" number="" targetptr="version-option"><ttl>???TITLE???</ttl><xreftext/></obj><obj element="listitem" href="#config-option" number="" targetptr="config-option"><ttl>???TITLE???</ttl><xreftext/></obj><obj element="option" href="#init-storage-option" number="" targetptr="init-storage-option"><ttl>???TITLE???</ttl><xreftext>--init-storage</xreftext></obj></div><div element="section" href="#configuration-file" number="" targetptr="configuration-file"><ttl>The configuration file</ttl><xreftext>configuration file</xreftext><obj element="table" href="#idp2098320" number="7.1"><ttl>Basic parameters</ttl><xreftext>Table 7.1, “Basic parametersâ€</xreftext></obj><obj element="entry" href="#work_dir" number="" targetptr="work_dir"><ttl>???TITLE???</ttl><xreftext>work_dir</xreftext></obj><obj element="entry" href="#script_dir" number="" targetptr="script_dir"><ttl>???TITLE???</ttl><xreftext>script_dir</xreftext></obj><obj element="entry" href="#wal_dir" number="" targetptr="wal_dir"><ttl>???TITLE???</ttl><xreftext>wal_dir</xreftext></obj><obj element="entry" href="#snap_dir" number="" targetptr="snap_dir"><ttl>???TITLE???</ttl><xreftext>snap_dir</xreftext></obj><obj element="entry" href="#bind_ipaddr" number="" targetptr="bind_ipaddr"><ttl>???TITLE???</ttl><xreftext>bind_ipaddr</xreftext></obj><obj element="entry" href="#primary_port" number="" targetptr="primary_port"><ttl>???TITLE???</ttl><xreftext>primary_port</xreftext></obj><obj element="entry" href="#secondary_port" number="" targetptr="secondary_port"><ttl>???TITLE???</ttl><xreftext>secondary_port</xreftext></obj><obj element="entry" href="#admin_port" number="" targetptr="admin_port"><ttl>???TITLE???</ttl><xreftext>admin_port</xreftext></obj><obj element="entry" href="#custom_proc_title" number="" targetptr="custom_proc_title"><ttl>???TITLE???</ttl><xreftext>custom_proc_title</xreftext></obj><obj element="table" href="#idp2157072" number="7.2"><ttl>Configuring the storage</ttl><xreftext>Table 7.2, “Configuring the storageâ€</xreftext></obj><obj element="anchor" href="#slab_alloc_arena" number="" targetptr="slab_alloc_arena"><ttl>???TITLE???</ttl><xreftext>slab_alloc_arena</xreftext></obj><obj element="para" href="#space" number="" targetptr="space"><ttl>???TITLE???</ttl><xreftext>the section called “The configuration fileâ€</xreftext></obj><obj element="table" href="#idp2193104" number="7.3"><ttl>Binary logging and snapshots</ttl><xreftext>Table 7.3, “Binary logging and snapshotsâ€</xreftext></obj><obj element="entry" href="#rows_per_wal" number="" targetptr="rows_per_wal"><ttl>???TITLE???</ttl><xreftext>rows_per_wal</xreftext></obj><obj element="entry" href="#wal_mode" number="" targetptr="wal_mode"><ttl>???TITLE???</ttl><xreftext>wal_mode</xreftext></obj><obj element="table" href="#idp2228480" number="7.4"><ttl>Replication</ttl><xreftext>Table 7.4, “Replicationâ€</xreftext></obj><obj element="entry" href="#replication_port" number="" targetptr="replication_port"><ttl>???TITLE???</ttl><xreftext>replication_port</xreftext></obj><obj element="entry" href="#replication_source" number="" targetptr="replication_source"><ttl>???TITLE???</ttl><xreftext>replication_source</xreftext></obj><obj element="table" href="#idp2247984" number="7.5"><ttl>Networking</ttl><xreftext>Table 7.5, “Networkingâ€</xreftext></obj><obj element="table" href="#idp2264176" number="7.6"><ttl>Logging</ttl><xreftext>Table 7.6, “Loggingâ€</xreftext></obj><obj element="table" href="#idp2289088" number="7.7"><ttl>Hot Standby</ttl><xreftext>Table 7.7, “Hot Standbyâ€</xreftext></obj><obj element="anchor" href="#local_hot_standby" number="" targetptr="local_hot_standby"><ttl>???TITLE???</ttl><xreftext>local_hot_standby</xreftext></obj></div></div><div element="chapter" href="#connectors" number="8" targetptr="connectors"><ttl>Connectors</ttl><xreftext>Chapter 8, <i>Connectors</i></xreftext><div element="section" href="#connector-packet-example" number="" targetptr="connector-packet-example"><ttl>Packet example</ttl><xreftext>the section called “Packet exampleâ€</xreftext></div><div element="section" href="#connector-c" number="" targetptr="connector-c"><ttl>C</ttl><xreftext>the section called “Câ€</xreftext></div><div element="section" href="#connector-erlang" number="" targetptr="connector-erlang"><ttl>Erlang</ttl><xreftext>the section called “Erlangâ€</xreftext></div><div element="section" href="#connector-java" number="" targetptr="connector-java"><ttl>Java</ttl><xreftext>the section called “Javaâ€</xreftext></div><div element="section" href="#connector-node.js" number="" targetptr="connector-node.js"><ttl>node.js</ttl><xreftext>the section called “node.jsâ€</xreftext></div><div element="section" href="#connector-perl" number="" targetptr="connector-perl"><ttl>Perl</ttl><xreftext>the section called “Perlâ€</xreftext></div><div element="section" href="#connector-php" number="" targetptr="connector-php"><ttl>PHP</ttl><xreftext>the section called “PHPâ€</xreftext></div><div element="section" href="#connector-python" number="" targetptr="connector-python"><ttl>Python</ttl><xreftext>the section called “Pythonâ€</xreftext></div><div element="section" href="#connector-ruby" number="" targetptr="connector-ruby"><ttl>Ruby</ttl><xreftext>the section called “Rubyâ€</xreftext></div></div><div element="appendix" href="#proctitle" number="A" targetptr="proctitle"><ttl>Server process titles</ttl><xreftext>Appendix A, <i>Server process titles</i></xreftext></div><div element="appendix" href="#errcode" number="B" targetptr="errcode"><ttl>List of error codes</ttl><xreftext>Appendix B, <i>List of error codes</i></xreftext><obj element="term" href="#ER_NONMASTER" number="" targetptr="ER_NONMASTER"><ttl>???TITLE???</ttl><xreftext>ER_NONMASTER</xreftext></obj><obj element="term" href="#ER_ILLEGAL_PARAMS" number="" targetptr="ER_ILLEGAL_PARAMS"><ttl>???TITLE???</ttl><xreftext>ER_ILLEGAL_PARAMS</xreftext></obj><obj element="term" href="#ER_MEMORY_ISSUE" number="" targetptr="ER_MEMORY_ISSUE"><ttl>???TITLE???</ttl><xreftext>ER_MEMORY_ISSUE</xreftext></obj><obj element="term" href="#ER_WAL_IO" number="" targetptr="ER_WAL_IO"><ttl>???TITLE???</ttl><xreftext>ER_WAL_IO</xreftext></obj><obj element="term" href="#ER_KEY_PART_COUNT" number="" targetptr="ER_KEY_PART_COUNT"><ttl>???TITLE???</ttl><xreftext>ER_KEY_PART_COUNT</xreftext></obj><obj element="term" href="#ER_NO_SUCH_SPACE" number="" targetptr="ER_NO_SUCH_SPACE"><ttl>???TITLE???</ttl><xreftext>ER_NO_SUCH_SPACE</xreftext></obj><obj element="term" href="#ER_NO_SUCH_INDEX" number="" targetptr="ER_NO_SUCH_INDEX"><ttl>???TITLE???</ttl><xreftext>ER_NO_SUCH_INDEX</xreftext></obj><obj element="term" href="#ER_PROC_LUA" number="" targetptr="ER_PROC_LUA"><ttl>???TITLE???</ttl><xreftext>ER_PROC_LUA</xreftext></obj><obj element="term" href="#ER_FIBER_STACK" number="" targetptr="ER_FIBER_STACK"><ttl>???TITLE???</ttl><xreftext>ER_FIBER_STACK</xreftext></obj><obj element="term" href="#ER_UPDATE_FIELD" number="" targetptr="ER_UPDATE_FIELD"><ttl>???TITLE???</ttl><xreftext>ER_UPDATE_FIELD</xreftext></obj></div><div element="appendix" href="#limitations" number="C" targetptr="limitations"><ttl>Limitations</ttl><xreftext>Appendix C, <i>Limitations</i></xreftext><obj element="term" href="#limitations-index-field-count" number="" targetptr="limitations-index-field-count"><ttl>???TITLE???</ttl><xreftext>limitations-index-field-count</xreftext></obj><obj element="term" href="#limitations-index-count" number="" targetptr="limitations-index-count"><ttl>???TITLE???</ttl><xreftext>limitations-index-count</xreftext></obj><obj element="term" href="#limitations-tuple-field-count" number="" targetptr="limitations-tuple-field-count"><ttl>???TITLE???</ttl><xreftext>limitations-tuple-field-count</xreftext></obj><obj element="term" href="#limitations-space-count" number="" targetptr="limitations-space-count"><ttl>???TITLE???</ttl><xreftext>limitations-space-count</xreftext></obj><obj element="term" href="#limitations-connections-count" number="" targetptr="limitations-connections-count"><ttl>???TITLE???</ttl><xreftext>limitations-connections-count</xreftext></obj><obj element="term" href="#limitations-slab-alloc-arena-size" number="" targetptr="limitations-slab-alloc-arena-size"><ttl>???TITLE???</ttl><xreftext>limitations-slab-alloc-arena-size</xreftext></obj><obj element="term" href="#limitations-update-count" number="" targetptr="limitations-update-count"><ttl>???TITLE???</ttl><xreftext>limitations-updae-count</xreftext></obj></div><div element="appendix" href="#lua-tutorial" number="D" targetptr="lua-tutorial"><ttl>Lua tutorial</ttl><xreftext>Appendix D, <i>Lua tutorial</i></xreftext><div element="section" href="#lua-tutorial-insert" number="" targetptr="lua-tutorial-insert"><ttl>Insert one million tuples with a Lua stored procedure</ttl><xreftext>the section called “Insert one million tuples with a Lua stored procedureâ€</xreftext></div><div element="section" href="#lua-tutorial-sum" number="" targetptr="lua-tutorial-sum"><ttl>Sum a JSON field for all tuples</ttl><xreftext>the section called “Sum a JSON field for all tuplesâ€</xreftext></div></div><div element="appendix" href="#plugins" number="E" targetptr="plugins"><ttl>Plugins</ttl><xreftext>Appendix E, <i>Plugins</i></xreftext><obj element="para" href="#plugin-sql-dbms-plugins" number="" targetptr="plugin-sql-dbms-plugins"><ttl>???TITLE???</ttl><xreftext>Appendix E, <i>Plugins</i></xreftext></obj><obj element="para" href="#plugin-mysql-example" number="" targetptr="plugin-mysql-example"><ttl>???TITLE???</ttl><xreftext>Appendix E, <i>Plugins</i></xreftext></obj><obj element="para" href="#plugin-postgresql-example" number="" targetptr="plugin-postgresql-example"><ttl>???TITLE???</ttl><xreftext>Appendix E, <i>Plugins</i></xreftext></obj></div></div>
diff --git a/doc/user/tnt-fo.xsl b/doc/user/tnt-fo.xsl
deleted file mode 100644
index 1081c345ad4dd9fb94be512dc6b38b321633b2f8..0000000000000000000000000000000000000000
--- a/doc/user/tnt-fo.xsl
+++ /dev/null
@@ -1,15 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet
- xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
- xmlns:xslthl="http://xslthl.sf.net">
-
- <xsl:import href="http://docbook.sourceforge.net/release/xsl-ns/current/fo/docbook.xsl"/>
-
- <xsl:param name="generate.toc" select="'book toc'"/>
- <xsl:param name="fop1.extentions">1</xsl:param>
- <xsl:param name="paper.type">A4</xsl:param>
- <xsl:param name="highlight.source" select="1"/>
- <xsl:param name="highlight.xslthl.config">file:////usr/share/xml/docbook/stylesheet/docbook-xsl-ns/highlighting/xslthl-config.xml</xsl:param>
-
- <xsl:param name="collect.xref.targets">all</xsl:param>
-</xsl:stylesheet>
diff --git a/doc/user/tnt-html-chunk.xsl b/doc/user/tnt-html-chunk.xsl
deleted file mode 100644
index 248f83a463d90453c0dd8984506fdc8aa4a2a304..0000000000000000000000000000000000000000
--- a/doc/user/tnt-html-chunk.xsl
+++ /dev/null
@@ -1,18 +0,0 @@
-<?xml version='1.0'?>
-
-<xsl:stylesheet
- xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
- xmlns:xslthl="http://xslthl.sf.net">
- <xsl:import href="http://docbook.sourceforge.net/release/xsl-ns/current/html/chunk.xsl"/>
- <xsl:import href="http://docbook.sourceforge.net/release/xsl-ns/current/html/highlight.xsl"/>
- <xsl:param name="highlight.source" select="1"/>
- <xsl:param name="highlight.xslthl.config">file:////usr/share/xml/docbook/stylesheet/docbook-xsl-ns/highlighting/xslthl-config.xml</xsl:param>
- <xsl:param name="use.id.as.filename" select="1"></xsl:param>
- <xsl:param name="suppress.header.navigation" select="1"></xsl:param>
- <xsl:param name="generate.toc">
- chapter toc
- book toc
- </xsl:param>
- <xsl:param name="html.stylesheet" select="'/theme/docbook.css'"/>
- <xsl:param name="collect.xref.targets">all</xsl:param>
-</xsl:stylesheet>
diff --git a/doc/user/tnt-html.xsl b/doc/user/tnt-html.xsl
deleted file mode 100644
index c838f82390ab812f2cbeaca6af5e7d7c7ff64468..0000000000000000000000000000000000000000
--- a/doc/user/tnt-html.xsl
+++ /dev/null
@@ -1,12 +0,0 @@
-<?xml version='1.0'?>
-<xsl:stylesheet
- xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
- xmlns:xslthl="http://xslthl.sf.net">
- <xsl:import href="http://docbook.sourceforge.net/release/xsl-ns/current/html/docbook.xsl"/>
- <xsl:import href="html-highlight.xsl"/>
- <xsl:param name="collect.xref.targets">all</xsl:param>
- <xsl:param name="generate.toc" select="'book toc'"/>
- <xsl:param name="html.stylesheet" select="'/theme/docbook.css'"/>
- <xsl:param name="highlight.source" select="1"/>
- <xsl:param name="highlight.xslthl.config">file:////usr/share/xml/docbook/stylesheet/docbook-xsl-ns/highlighting/xslthl-config.xml</xsl:param>
-</xsl:stylesheet>
diff --git a/doc/user/triggers.xml b/doc/user/triggers.xml
deleted file mode 100644
index 64a3c0867a57bb2d60abf6381e58d2abb1c4a70e..0000000000000000000000000000000000000000
--- a/doc/user/triggers.xml
+++ /dev/null
@@ -1,288 +0,0 @@
-<!DOCTYPE chapter [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xml:id="triggers">
-<title>Triggers</title>
-
- <para>
- Triggers, also known as callbacks, are functions which the server executes
- when certain events happen. Currently the two types of
- triggers are <link linkend="sp-box-session-triggers">connection triggers</link>,
- which are executed when a session begins or ends,
- and <link linkend="sp-box-replace-triggers">replace</link> triggers
- which are for database events,
- </para>
-
- <para>
- All triggers have the following characteristics.
-
- <itemizedlist mark='bullet'>
-
- <listitem>
- <para>
- They associate a <emphasis>function</emphasis> with an <emphasis>event</emphasis>.
- The request to "define a trigger" consists of passing the name of the
- trigger's function to one of the "on_<replaceable>event-name</replaceable>..." functions:
- <code>on_connect()</code>, <code>on_disconnect()</code>, or <code>on_replace()</code>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- They are <emphasis>defined by any user</emphasis>.
- There are no privilege requirements for defining triggers.
- </para>
- </listitem>
-
- <listitem>
- <para>
- They are called <emphasis>after</emphasis> the event.
- They are not called if the event ends prematurely due to an error.
- </para>
- </listitem>
-
- <listitem>
- <para>
- They are <emphasis>in server memory</emphasis>.
- They are not stored in the database.
- Triggers disappear when the server is shut down.
- If there is a requirement to make them permanent, then
- the function definitions and trigger settings should be
- part of an initialization script.
- </para>
- </listitem>
-
- <listitem>
- <para>
- They have <emphasis>low overhead</emphasis>.
- If a trigger is not defined, then the overhead is
- minimal: merely a pointer dereference and check.
- If a trigger is defined, then its overhead is equivalent to the
- overhead of calling a stored procedure.
- </para>
- </listitem>
-
- <listitem>
- <para>
- They can be <emphasis>multiple</emphasis> for one event.
- Triggers are executed in the reverse order that they were defined in.
- </para>
- </listitem>
-
- <listitem>
- <para>
- They must work <emphasis>within the event context</emphasis>.
- If the function contains requests which normally could not occur
- immediately after the event but before the return from the event,
- effects are undefined. For example, defining a trigger function
- as <code>os.exit()</code> or <code>box.rollback()</code> would
- be bringing in requests outside the event context.
- </para>
- </listitem>
-
- <listitem>
- <para>
- They are <emphasis>replaceable</emphasis>.
- The request to "redefine a trigger" consists of passing the
- names of a new trigger function and an old trigger function
- to one of the "on_<replaceable>event-name</replaceable>..." functions.
- </para>
- </listitem>
-
- </itemizedlist>
-
- </para>
-
-<section xml:id="sp-box-session-triggers" xreflabel="session triggers">
- <title>Connection triggers</title>
-<variablelist>
- <varlistentry>
- <term>
- <emphasis role="lua">box.session.on_connect(<replaceable>trigger-function-name</replaceable> [, <replaceable>old-trigger-function-name</replaceable>])</emphasis>
- </term>
- <listitem><para>
- Define a trigger for execution when a new session is created due to
- an event such as <link linkend="console-connect"><code>console.connect()</code></link>.
- The trigger function will be the first
- thing executed after a new session is created.
- If the trigger fails by raising an error, the error
- is sent to the client and the connection is closed.
- </para>
- <para>
- Parameters: trigger-function-name = name of a function which will become the trigger function;
- (optional) old-trigger-function-name = name of an existing trigger function which will be
- replaced by trigger-function-name.
- If the parameters are (nil, old-trigger-function-name), then the old trigger is deleted.
- </para>
- <para>
- Returns: nil.
- </para>
- <para>
- Example: <code>function f () x = x + 1 end; box.session.on_connect(f)</code>
- </para>
- <warning>
- <para>
- If a trigger always results in an error, it may become
- impossible to connect to the server to reset it.
- </para>
- </warning>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- <emphasis role="lua">box.session.on_disconnect(<replaceable>trigger-function-name</replaceable> [, <replaceable>old-trigger-function-name</replaceable>])</emphasis>
- </term>
- <listitem>
- <para>Define a trigger for execution after a client has
- disconnected. If
- the trigger function causes 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 box.session.id.
- </para>
- <para>
- Parameters: trigger-function-name = name of a function which will become the trigger function;
- (optional) old-trigger-function-name = name of an existing trigger function which will be
- replaced by trigger-function-name.
- If the parameters are (nil, old-trigger-function-name), then the old trigger is deleted.
- </para>
- <para>
- Returns: nil.
- </para>
- <para>
- Example: <code>function f () x = x + 1 end; box.session.on_disconnect(f)</code>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
- After the following series of requests, the server
- will write a message using the <link linkend="sp-log">log package</link>
- whenever any user connects or disconnects.
-<programlisting>
-console = require('console'); console.delimiter('!') --this means ignore line feeds until next '!'
-function log_connect ()
- local log
- local m
- log = require('log')
- m = 'Connection. user=' .. box.session.user() .. ' id=' .. box.session.id()
- log.info(m)
- end!
-function log_disconnect ()
- local log
- local m
- log = require('log')
- m = 'Disconnection. user=' .. box.session.user() .. ' id=' .. box.session.id()
- log.info(m)
- end!
-console.delimiter('')!
-box.session.on_connect(log_connect)
-box.session.on_disconnect(log_disconnect)
-</programlisting>
-Here is what might appear in the log file in a typical installation:
-<programlisting>
-2014-12-15 13:21:34.444 [11360] main/103/iproto I>
- Connection. user=guest id=3
-2014-12-15 13:22:19.289 [11360] main/103/iproto I>
- Disconnection. user=guest id=3
-</programlisting>
- </para>
-
-</section>
-
- <section xml:id="sp-box-replace-triggers" xreflabel="replace triggers">
- <title>Replace triggers</title>
-<variablelist>
-
- <varlistentry>
- <term xml:id="on_replace">
- <emphasis role="lua">box.space.<replaceable>space-name</replaceable>:on_replace(<replaceable>trigger-function-name</replaceable> [, <replaceable>old-trigger-function-name</replaceable>])</emphasis>
- </term>
- <listitem>
- <para>
- Create a "replace trigger". The <code>function-name</code> will be executed whenever a replace() or insert()
- or update() or delete() happens to a tuple in <code>space-name</code>.
- </para>
- <para>
- Parameters: trigger-function-name = name of a function which will become the trigger function;
- (optional) old-trigger-function-name = name of an existing trigger function which will be
- replaced by trigger-function-name.
- If the parameters are (nil, old-trigger-function-name), then the old trigger is deleted.
- </para>
- <para>
- Returns: nil.
- </para>
- <para>
- Example: <code>function f () x = x + 1 end; box.space.X:on_replace(f)</code>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term xml:id="run_triggers">
- <emphasis role="lua">box.space.<replaceable>space-name</replaceable>:run_triggers(<replaceable>true|false</replaceable>)</emphasis>
- </term>
- <listitem>
- <para>
- At the time that a trigger is defined, it is automatically enabled -- that is, it will be executed.
- Replace triggers can be disabled with <code>box.space.<replaceable>space-name</replaceable>:run_triggers(false)</code>
- and re-enabled with <code>box.space.<replaceable>space-name</replaceable>:run_triggers(true)</code>.
- </para>
- <para>
- Returns: nil.
- </para>
- <para>
- Example: <code>box.space.X:run_triggers(false)</code>
- </para>
- </listitem>
- </varlistentry>
-
-</variablelist>
-
- <para>
- <bridgehead renderas="sect4">Example</bridgehead>
- The following series of requests will create a space, create an index,
- create a function which increments a counter, create a trigger,
- do two inserts, drop the space, and display the counter value -- which is 2,
- because the function is executed once after each insert.
-<programlisting>s = box.schema.space.create('space53')
-s:create_index('primary', {parts = {1, 'NUM'}})
-function replace_trigger() replace_counter = replace_counter + 1 end
-s:on_replace(replace_trigger)
-replace_counter = 0
-t = s:insert{1, 'First replace'}
-t = s:insert{2, 'Second replace'}
-s:drop()
-replace_counter</programlisting>
- </para>
-
- <para>
- <bridgehead renderas="sect4">Another Example</bridgehead>
- The following series of requests will associate an existing
- function named F with an existing space named T,
- associate the function a second time with the same space
- (so it will be called twice), disable all triggers of
- T, and destroy each trigger by replacing with nil.
-<programlisting>box.space.T:on_replace(F)
-box.space.T:on_replace(F)
-box.space.T:run_triggers(false)
-box.space.T:on_replace(nil, F)
-box.space.T:on_replace(nil, F)</programlisting>
- </para>
-
-
-</section>
-
-</chapter>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/tutorial.xml b/doc/user/tutorial.xml
deleted file mode 100644
index 2795211240e758cd7fa21719561af0b7aa7ccc3b..0000000000000000000000000000000000000000
--- a/doc/user/tutorial.xml
+++ /dev/null
@@ -1,683 +0,0 @@
-<!DOCTYPE book [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="getting-started">
-
-<title>Getting started</title>
-
-<para>
-This chapter shows how to download, how to install, and how to start Tarantool for the first time.
-</para>
-
-<para>
-For production, if possible, you should download a binary (executable) package.
-This will ensure that you have the same build of the same version that the developers have.
-That makes analysis easier if later you need to
-report a problem, and avoids subtle problems that might happen if
-you used different tools or different parameters when building from source.
-The section about binaries is <olink
-targetptr="getting-started-binary"><quote>Downloading and
-installing a binary package</quote></olink>.
-</para>
-
-<para>
-For development, you will want to download a source package and make the binary
-by yourself using a C/C++ compiler and common tools.
-Although this is a bit harder, it gives more control.
-And the source packages include additional files, for example the Tarantool test suite.
- The section about source is <olink
-targetptr="getting-started-source"><quote>Downloading and building a source package</quote></olink>.
-</para>
-
-<para>
-If the installation has already been done, then you should try it out.
- So we've provided some instructions that you can use to make a temporary <quote>sandbox</quote>.
-In a few minutes you can start the server and type in some
-database-manipulation statements.
-The section about sandbox is <olink
-targetptr="getting-started-start-stop"><quote>Starting Tarantool and making your first database</quote></olink>.
-</para>
-
-<section xml:id="getting-started-binary">
-<title>Downloading and installing a binary package</title>
-
-<para>
-The repositories for the <quote>stable</quote> release are at <link xlink:href="http://tarantool.org/dist/stable" xlink:title="tarantool.org/dist/stble">tarantool.org/dist/stable</link>.
-The repositories for the <quote>master</quote> release are at <link xlink:href="http://tarantool.org/dist/master" xlink:title="tarantool.org/dist/master">tarantool.org/dist/master</link>.
-Since this is the manual for the <quote>master</quote> release, all instructions use <link xlink:href="http://tarantool.org/dist/master" xlink:title="tarantool.org/dist/master">tarantool.org/dist/master</link>.
-</para>
-
-<para>
-An automatic build system creates, tests and publishes packages for every push into the master branch.
-Therefore if you looked at <link xlink:href="http://tarantool.org/dist/master" xlink:title="tarantool.org/dist/master">tarantool.org/dist/master</link> you would see
-that there are source files and subdirectories for the packages that will be described in this section.
-</para>
-
-<para>
-To download and install the package that's appropriate for your environment,
-start a shell (terminal) and enter one of the following sets of command-line instructions.
-</para>
-<para>
-More advice for binary downloads is at <link xlink:href="http://tarantool.org/download.html">http://tarantool.org/download.html</link>.
-</para>
-
-
-<simplesect>
-<title>Debian GNU/Linux</title>
-<para>
-There is always an up-to-date Debian repository at
-<link xlink:href="http://tarantool.org/dist/master/debian">http://tarantool.org/dist/master/debian</link>
-The repository contains builds for Debian unstable "Sid", stable "Wheezy",
-forthcoming "Jessie". Add the tarantool.org repository to your apt
-sources list. $release is an environment variable which will
-contain the Debian version code e.g. "Wheezy":
-<programlisting>
-<userinput>
-<command>wget</command> http://tarantool.org/dist/public.key
-<command>sudo apt-key add</command> <filename>./public.key</filename>
-release=`lsb_release -c -s`
-# append two lines to a list of source repositories
-<command>echo</command> "deb http://tarantool.org/dist/master/debian/ $release main" | \
-<command>sudo tee</command> <option>-a</option> <filename>/etc/apt/sources.list.d/tarantool.list</filename>
-<command>echo</command> "deb-src http://tarantool.org/dist/master/debian/ $release main" | \
-<command>sudo tee</command> <option>-a</option> <filename>/etc/apt/sources.list.d/tarantool.list</filename>
-# install
-<command>sudo apt-get update</command>
-<command>sudo apt-get install</command> tarantool
-</userinput>
-</programlisting>
-</para>
-</simplesect>
-
-<simplesect>
-<title>Ubuntu</title>
-<para>
-There is always an up-to-date Ubuntu repository at
-<link xlink:href="http://tarantool.org/dist/master/ubuntu">http://tarantool.org/dist/master/ubuntu</link>
-The repository contains builds for Ubuntu 12.04 "precise",
-13.10 "saucy", and 14.04 "trusty".
-Add the tarantool.org repository to your apt sources list
-$release is an environment variable which will contain the Ubuntu version
-code e.g. "precise". If you want the version that comes with
-Ubuntu, start with the lines that follow the '# install' comment:
-<programlisting>
-<userinput>
-<command>cd</command> ~
-<command>wget</command> http://tarantool.org/dist/public.key
-<command>sudo apt-key add</command> <filename>./public.key</filename>
-release=`lsb_release -c -s`
-# append two lines to a list of source repositories
-<command>echo</command> "deb http://tarantool.org/dist/master/ubuntu/ $release main" | \
-<command>sudo tee</command> <option>-a</option> <filename>/etc/apt/sources.list.d/tarantool.list</filename>
-<command>echo</command> "deb-src http://tarantool.org/dist/master/ubuntu/ $release main" | \
-<command>sudo tee</command> <option>-a</option> <filename>/etc/apt/sources.list.d/tarantool.list</filename>
-# install
-<command>sudo apt-get update</command>
-<command>sudo apt-get install</command> tarantool
-</userinput>
-</programlisting>
-</para>
-</simplesect>
-
-<simplesect>
-<title>CentOS</title>
-<para>
-These instructions are applicable for CentOS version 5 or 6,
-and RHEL version 5 or 6.
-Pick the CentOS repository which fits your CentOS/RHEL version
-and your x86 platform:
-<itemizedlist>
-<listitem><simpara>
-<link xlink:href="http://tarantool.org/dist/master/centos/5/os/i386">http://tarantool.org/dist/master/centos/5/os/i386</link> for version 5, x86-32
-</simpara></listitem>
-<listitem><simpara>
-<link xlink:href="http://tarantool.org/dist/master/centos/6/os/i386">http://tarantool.org/dist/master/centos/6/os/i386</link> for version 6, x86-32
-</simpara></listitem>
-<listitem><simpara>
-<link xlink:href="http://tarantool.org/dist/master/centos/5/os/x86_64">http://tarantool.org/dist/master/centos/5/os/x86_64</link> for version 5, x86-64
-</simpara></listitem>
-<listitem><simpara>
-<link xlink:href="http://tarantool.org/dist/master/centos/6/os/x86_64">http://tarantool.org/dist/master/centos/6/os/x86_64</link> for version 6, x86-64
-</simpara></listitem>
-</itemizedlist>
-Add the following section to your yum repository list
-(<filename>/etc/yum.repos.d/tarantool.repo</filename>)
-(in the following instructions, $releasever i.e. CentOS release
-version must be either 5 or 6 and $basearch i.e. base
-architecture must be either i386 or x86_64):
-<programlisting>
-<userinput>
-# [tarantool]
-name=CentOS-<replaceable>$releasever</replaceable> - Tarantool
-baseurl=http://tarantool.org/dist/master/centos/<replaceable>$releasever</replaceable>/os/<replaceable>$basearch</replaceable>/
-enabled=1
-gpgcheck=0
-</userinput></programlisting>
-For example, if you have CentOS version 6 and x86-64, you can
-add the new section thus:
-<programlisting><userinput>
-<command>echo</command> "[tarantool]" | \
-<command>sudo tee</command> <filename>/etc/yum.repos.d/tarantool.repo</filename>
-<command>echo</command> "name=CentOS-6 - Tarantool"| <command>sudo tee</command> <option>-a</option> <filename>/etc/yum.repos.d/tarantool.repo</filename>
-<command>echo</command> "baseurl=http://tarantool.org/dist/master/centos/6/os/x86_64/" | \
-<command>sudo tee</command> <option>-a</option> <filename>/etc/yum.repos.d/tarantool.repo</filename>
-<command>echo</command> "enabled=1" | <command>sudo tee</command> <option>-a</option> <filename>/etc/yum.repos.d/tarantool.repo</filename>
-<command>echo</command> "gpgcheck=0" | <command>sudo tee</command> <option>-a</option> <filename>/etc/yum.repos.d/tarantool.repo</filename>
-</userinput>
-</programlisting>
-</para>
-</simplesect>
-
-<simplesect>
-<title>Fedora</title>
-<para>
-These instructions are applicable for Fedora 19 or Fedora 20.
-Pick the Fedora repository, for example <link xlink:href="http://tarantool.org/dist/master/fedora/20/x86_64">http://tarantool.org/dist/master/fedora/20/x86_64</link> for version 20, x86-64.
-Add the following section to your yum repository list
-(<filename>/etc/yum.repos.d/tarantool.repo</filename>)
-(in the following instructions, $releasever i.e. Fedora release
-version must be 19 or 20 and $basearch i.e. base architecture must be x86_64):
-<programlisting>
-<userinput>
-[tarantool]
-name=Fedora-<replaceable>$releasever</replaceable> - Tarantool
-baseurl=http://tarantool.org/dist/master/fedora/<replaceable>$releasever</replaceable><replaceable>$basearch</replaceable>/
-enabled=1
-gpgcheck=0
-</userinput>
-</programlisting>
-For example, if you have Fedora version 20, you can add the new section thus:
-<programlisting>
-<userinput>
-<command>echo</command> "[tarantool]" | \
-<command>sudo tee</command> <filename>/etc/yum.repos.d/tarantool.repo</filename>
-<command>echo</command> "name=Fedora-20 - Tarantool"| <command>sudo tee</command> <option>-a</option> <filename>/etc/yum.repos.d/tarantool.repo</filename>
-<command>echo</command> "baseurl=http://tarantool.org/dist/master/fedora/20/x86_64/" | \
-<command>sudo tee</command> <option>-a</option> <filename>/etc/yum.repos.d/tarantool.repo</filename>
-<command>echo</command> "enabled=1" | <command>sudo tee</command> <option>-a</option> <filename>/etc/yum.repos.d/tarantool.repo</filename>
-<command>echo</command> "gpgcheck=0" | <command>sudo tee</command> <option>-a</option> <filename>/etc/yum.repos.d/tarantool.repo</filename></userinput></programlisting>
-Then install with <code>sudo yum install tarantool</code>.
-</para>
-</simplesect>
-
-<simplesect>
-<title>Gentoo</title>
-<para>
-Tarantool is available from tarantool portage overlay.
-Use layman to add the overlay to your system:
-<programlisting>
-<userinput>
-<command>layman</command> <option>-S</option>
-<command>layman</command> <option>-a</option> tarantool
-<command>emerge</command> <filename>dev-db/tarantool</filename> <option>-av</option>
-</userinput>
-</programlisting>
-</para>
-</simplesect>
-
-<simplesect>
-<title>FreeBSD</title>
-<para>
-With your browser go to the FreeBSD ports page
-<link xlink:href="http://www.freebsd.org/ports/index.html">http://www.freebsd.org/ports/index.html</link>.
-Enter the search term: tarantool.
-Choose the package you want.
-</para>
-
-</simplesect>
-<simplesect>
-<title>Mac OS X</title>
-<para>
-This is actually a <quote><productname>homebrew</productname></quote> recipe
-so it's not a true binary download, some source code is involved.
-First upgrade Clang (the C compiler) to version 3.2 or later using
-Command Line Tools for Xcode disk image version 4.6+ from
-Apple Developer web-site. Then download the recipe file from
-<link xlink:href="http://tarantool.org/dist/master/tarantool.rb">tarantool.org/dist/master/tarantool.rb</link>.
-Make the file executable, execute it, and the script in the file should
-handle the necessary steps with cmake, make, and make install.
-</para>
-</simplesect>
-
-</section>
-
-<section xml:id="getting-started-source">
-<title>Downloading and building a source package</title>
-<para>
-For downloading Tarantool source and building it, the platforms can differ
-and the preferences can differ.
-But the steps are always the same. Here in the manual we'll explain what the steps are,
-then on the Internet you can look at some example scripts.
-</para>
-
-<para>
-1. Get tools and libraries that will be necessary for building and testing.
-The absolutely necessary ones are:
- <itemizedlist>
- <listitem>
- <para>
-A program for downloading source repositories.
-In this case the necessary program is <quote><productname>git</productname></quote>. Although tarantool.org/dist
-has source tarballs (the files whose names end in <quote>-src.tar.gz</quote>), the latest complete source downloads are on
-github.com, and from github one gets with git.
- </para>
- </listitem>
- <listitem>
- <para>
-A C/C++ compiler.
- Ordinarily the compiler is <productname>GCC</productname> version 4.6 or later,
- on Mac OS X it should be <productname>Clang</productname> version 3.2 or later.
- </para>
- </listitem>
- <listitem>
- <para>
-A program for managing the build process.
- This is always <productname>CMake</productname> for GNU/Linux and FreeBSD.
- The CMake version should be 2.8 or later.
- </para>
- </listitem>
- </itemizedlist>
-</para>
-
-<para>
-Here are names of tools and libraries which may have to be installed in advance,
-using <quote><computeroutput>sudo apt-get</computeroutput></quote> (for Ubuntu), <quote><computeroutput>sudo yum install</computeroutput></quote> (for CentOS),
-or the equivalent on other platforms. Different platforms may use slightly
-different names. Do not worry about the ones marked <quote>optional, for build with -DENABLE_DOC</quote>
-unless you intend to work on the documentation.</para>
-<itemizedlist>
- <listitem><para>binutils-dev or binutils-devel # contains GNU bfd for printing stack traces</para></listitem>
- <listitem><para> gcc or clang # see above</para></listitem>
- <listitem><para> git # see above</para></listitem>
- <listitem><para> cmake # see above</para></listitem>
- <listitem><para> libreadline-dev # for interactive mode</para></listitem>
- <listitem><para> libncurses5-dev or ncurses-devel # see above</para></listitem>
- <listitem><para> xsltproc # optional, for build with -DENABLE_DOC</para></listitem>
- <listitem><para> lynx # optional, for build with -DENABLE_DOC</para></listitem>
- <listitem><para> jing # optional, for build with -DENABLE_DOC</para></listitem>
- <listitem><para> libxml2-utils # optional, for build with -DENABLE_DOC</para></listitem>
- <listitem><para> docbook5-xml # optional, for build with -DENABLE_DOC</para></listitem>
- <listitem><para> docbook-xsl-ns # optional, for build with -DENABLE_DOC</para></listitem>
- <listitem><para> w3c-sgml-lib # optional, for build with -DENABLE_DOC</para></listitem>
- <listitem><para> libsaxon-java # optional, for build with -DENABLE_DOC</para></listitem>
- <listitem><para> libxml-commons-resolver1.1-java # optional, for build with -DENABLE_DOC</para></listitem>
- <listitem><para> libxerces2-java # optional, for build with -DENABLE_DOC</para></listitem>
- <listitem><para> libxslthl-java # optional, for build with -DENABLE_DOC</para></listitem>
- <listitem><para> autoconf # optional, appears only in Mac OS scripts</para></listitem>
- <listitem><para> zlib1g or zlib # optional, appears only in Mac OS scripts</para></listitem>
-</itemizedlist>
-
-<para>
-2. Set up python modules for running the test suite or creating documentation.
- This step is optional. Python modules are not necessary for building Tarantool
- itself, unless one intends to use the -DENABLE_DOC option in step 6 or the
- "Run the test suite" option in step 8.</para>
-<para>Say:<programlisting><command>python --version</command></programlisting>
-... You should see that the python version is greater than 2.6 -- preferably 2.7 -- and less than 3.</para>
-<para>On Ubuntu you can get modules from the repository:
-<programlisting>
-<userinput>
-# For test suite
-<command>sudo apt-get install</command> python-daemon python-yaml python-argparse
-# For documentation
-<command>sudo apt-get install</command> python-jinja2 python-markdown
-</userinput>
-</programlisting></para>
-<para>On CentOS too you can get modules from the repository:<programlisting><command>sudo yum install</command> python26 python26-PyYAML python26-argparse</programlisting></para>
-<para>But in general it is best to set up the modules by getting
- a tarball and doing the setup with <computeroutput>python setup.py</computeroutput>, thus:
-<programlisting># python module for parsing YAML (pyYAML): For test suite:
-# (If wget fails, check the <citetitle xlink:href="http://pyyaml.org/wiki/PyYAML" xlink:title="Python YAML parser">PyYAML</citetitle> web site
-# to see what the current version is.)
-<userinput>
-<command>cd</command> ~
-<command>wget</command> http://pyyaml.org/download/pyyaml/PyYAML-3.10.tar.gz
-<command>tar</command> <option>-xzf</option> PyYAML-3.10.tar.gz
-<command>cd</command> PyYAML-3.10
-<command>sudo python</command> setup.py install
-</userinput>
-# python module for helping programs become daemons (daemon): For test suite:
-# (if wget fails, check the <citetitle xlink:href="http://pypi.python.org/pypi/python-daemon" xlink:title="Python daemon">python-daemon</citetitle> web site
-# to see what the current version is.)
-<userinput>
-<command>cd</command> ~
-<command>wget</command> http://pypi.python.org/packages/source/p/python-daemon/python-daemon-1.5.5.tar.gz
-<command>tar</command> <option>-xzvf</option> python-daemon-1.5.5.tar.gz
-<command>cd</command> python-daemon-1.5.5
-<command>sudo python</command> setup.py install
-</userinput>
-
-# python module for text-to-html conversion (markdown): For documentation:
-# (If wget fails, check the <citetitle xlink:href="http://pypi.python.org/pypi/Markdown/" xlink:title="Python implementation of Markdown">python-markdown</citetitle> web site
-# to see what the current version is.)
-<userinput>
-<command>cd</command> ~
-<command>wget</command> https://pypi.python.org/packages/source/M/Markdown/Markdown-2.3.1.tar.gz
-<command>tar</command> <option>-xzvf</option> Markdown-2.3.1.tar.gz
-<command>cd</command> Markdown-2.3.1
-<command>sudo python</command> setup.py install
-</userinput>
-# python module which includes Jinja2 template engine: For documentation:
-<userinput>
-<command>sudo pip install pelican</command>
-</userinput>
-# python module for HTML scraping: For documentation:
-<userinput>
-<command>cd</command> ~
-<command>wget</command> http://www.crummy.com/software/BeautifulSoup/bs3/download//3.x/BeautifulSoup-3.2.1.tar.gz
-<command>tar</command> -xzvf BeautifulSoup-3.2.1.tar.gz
-<command>cd</command> BeautifulSoup-3.2.1
-<command>sudo python</command> setup.py install
-</userinput>
-
-</programlisting>
-</para>
-
-<para>
-3. Pick a default directory.
-This can be anywhere. We'll assume that your default directory is <quote>~</quote>, and therefore
-the tarantool download will go inside it, as <computeroutput><filename>~/tarantool</filename></computeroutput>.
-</para>
-
-<para>
-4. Use <productname>git</productname> to download from github.com.<programlisting><userinput>
-<command>cd</command> ~
-<command>git clone</command> <option>-b master</option> https://github.com/tarantool/tarantool.git <option>tarantool</option></userinput></programlisting>
-The optional argument <quote>-b master</quote> causes download from the master branch instead of the stable branch,
-and the optional last word on the line, <quote>tarantool</quote>, means download is to <computeroutput>~/tarantool</computeroutput>.
-</para>
-
-<para>
-5. Use <productname>git</productname> again so that third-party contributions will be seen as well.
-This step is only necessary once, the first time you do a download.
-There is an alternative -- say <quote><computeroutput><command>git clone</command> --recursive</computeroutput></quote> in step 3 --
-but we prefer this method because it works with older versions of <productname>git</productname>.<programlisting><userinput><command>cd</command> ~/tarantool
-<command>git submodule init</command>
-<command>git submodule update</command>
-<command>cd</command> ../</userinput></programlisting>
-On rare occasions, the submodules will need to be updated again with the command: <userinput>git submodule update --init</userinput>.
-</para>
-
-<para>
-6. Use CMake to initiate the build.<programlisting><userinput><command>cd</command> ~/tarantool
-<command>make clean</command> # unnecessary, added for good luck
-<command>rm CMakeCache.txt</command> # unnecessary, added for good luck
-<command>cmake .</command> # Start build with build type=Debug, no doc</userinput></programlisting>
-
-The option for specifying build type is <option>-DCMAKE_BUILD_TYPE=</option><replaceable>type</replaceable> where
- type = {None | Debug | Release | RelWithDebInfo | MinSizeRel} and a reasonable
- choice for production is <option>-DCMAKE_BUILD_TYPE=RelWithDebInfo</option> (<quote>Debug</quote>
- is used only by project maintainers and <quote>Release</quote> is used only when the
- highest performance is required).
- The option for asking to build documentation is <computeroutput><option>-DENABLE_DOC=</option><replaceable>{true|false}</replaceable></computeroutput>
- and the assumption is that only a minority will need to rebuild the
- documentation (such as what you're reading now), so details about
- documentation are in the developer manual, and the reasonable choice
- is <computeroutput><option>-DENABLE_DOC=false</option></computeroutput> or just don't use the <computeroutput><option>-DENABLE_DOC</option></computeroutput> clause at all.
-</para>
-
-<para>
- 7. Use make to complete the build.<programlisting><userinput><command>make</command></userinput></programlisting>
- It's possible to say <quote><computeroutput><command>make install</command></computeroutput></quote> too, but that's not generally done.
-</para>
-
-<para>
-8. Run the test suite. This step is optional.
-</para>
-<para>
-Tarantool's developers always run the test suite before they publish new versions. You should run the test suite too, if you
- make any changes in the code.
-Assuming you downloaded to <filename>~/tarantool</filename>,
-the principal steps are:<programlisting><userinput><command>mkdir</command> ~/tarantool/bin # make a subdirectory named <filename>bin</filename>
-<command>ln</command> /usr/bin/python ~/tarantool/bin/python # link python to bin (this may require superuser privilege)
-<command>cd</command> ~/tarantool/test #get on the test subdirectory
-PATH=~/tarantool/bin:$PATH ./test-run.py #run tests using python</userinput></programlisting>
-
-
-The output should contain reassuring reports, for example
-<programlisting><computeroutput>======================================================================
-TEST RESULT
-------------------------------------------------------------
-box/bad_trigger.test.py [ pass ]
-box/call.test.py [ pass ]
-box/iproto.test.py [ pass ]
-box/xlog.test.py [ pass ]
-box/admin.test.lua [ pass ]
-box/auth_access.test.lua [ pass ]
-... etc.</computeroutput></programlisting>
-There are more than 70 tests in the suite.
-
-To prevent later confusion, clean up what's in the <filename>bin</filename>
-subdirectory:<programlisting><userinput><command>rm</command> ~/tarantool/bin/python
-<command>rmdir</command> ~/tarantool/bin</userinput></programlisting>
-</para>
-
-
-<para>
-9. Make an rpm.
- This step is optional. It's only for people who want to redistribute Tarantool.
- Package maintainers who want to build with rpmbuild should consult the
- <productname xlink:href="http://tarantool.org/tarantool_developer_guide.html">Tarantool developer guide</productname>.
-</para>
-
-<para>
-This is the end of the list of steps to take for source downloads.
-</para>
-
-<para>
-For your added convenience, github.com has README files with example scripts:
-
-<productname xlink:href="https://github.com/tarantool/tarantool/blob/master/README.CentOS">README.CentOS</productname> for CentOS 5.8,
-<productname xlink:href="https://github.com/tarantool/tarantool/blob/master/README.FreeBSD">README.FreeBSD</productname> for FreeBSD 8.3,
-<productname xlink:href="https://github.com/tarantool/tarantool/blob/master/README.MacOSX">README.MacOSX</productname> for Mac OS X <quote>Lion</quote>,
-<productname xlink:href="https://github.com/tarantool/tarantool/blob/master/README.md">README.md</productname> for generic GNU/Linux.
-
-These example scripts assume that the intent is to download from the master branch, build
-the server (but not the documentation), and run tests after build.
-</para>
-
-<para>
-To build with SUSE 13.1, the steps are as described above, except that the appropriate YaST2 package names are:
-binutils-devel, cmake, ncurses-devel, lynx, jing, libxml2-devel, docbook_5, saxon, libxslt-devel.
-The python connector can be installed with <code>sudo easy_install pip</code> and <code>sudo pip install tarantool</code>.
-</para>
-
-</section>
-<section xml:id="getting-started-start-stop">
-<title>Starting Tarantool and making your first database</title>
-
-<para>
-Here is how to create a simple test database after installing.
-</para>
-
-<para>
-1. Create a new directory. It's just for tests, you can delete it when the tests are over.<programlisting><userinput>
-<command>mkdir</command> <replaceable>~/tarantool_sandbox</replaceable>
-<command>cd</command> <replaceable>~/tarantool_sandbox</replaceable> </userinput></programlisting>
-</para>
-
-<para>
-2. Start the server.
-The server name is <computeroutput><filename>tarantool</filename></computeroutput>.<programlisting><userinput>
-#if you downloaded a binary with apt-get or yum, say this:
- <command>/usr/bin/tarantool</command>
-#if you downloaded and untarred a binary tarball to ~/tarantool, say this:
- <command>~/tarantool/bin/tarantool</command>
-#if you built from a source download, say this:
- <command>~/tarantool/src/tarantool</command> </userinput></programlisting>
-</para>
-
-<para>
- The server starts in interactive mode and outputs a command prompt.
- To turn on the database, <link linkend="configuration-parameters">configure it</link>:
-<programlisting><prompt>tarantool></prompt> <userinput>box.cfg{listen=3301}</userinput></programlisting>
- (this minimal example is sufficient).
-</para>
-
-<para>
-If all goes well, you will see the server displaying progress as it initializes, something like this:<programlisting><computeroutput>
-tarantool> box.cfg{listen=3301}
-2014-08-07 09:41:41.077 ... version 1.6.3-439-g7e1011b
-2014-08-07 09:41:41.077 ... log level 5
-2014-08-07 09:41:41.078 ... mapping 1073741824 bytes for a shared arena...
-2014-08-07 09:41:41.079 ... initialized
-2014-08-07 09:41:41.081 ... initializing an empty data directory
-2014-08-07 09:41:41.095 ... creating `./00000000000000000000.snap.inprogress'
-2014-08-07 09:41:41.095 ... saving snapshot `./00000000000000000000.snap.inprogress'
-2014-08-07 09:41:41.127 ... done
-2014-08-07 09:41:41.128 ... primary: bound to 0.0.0.0:3301
-2014-08-07 09:41:41.128 ... ready to accept requests</computeroutput></programlisting>
-</para>
-
-<para>
- Now that the server is up, you could start up a different shell and
- connect to its primary port with<programlisting>
- <command>telnet 0 3301</command></programlisting>
-but for example purposes it is simpler to just leave the
-server running in "interactive mode".
-On production machines the interactive mode is just
-for administrators, but because it's convenient for
-learning it will be used for most examples in this manual.
-
-Tarantool is waiting for the user to type instructions.
-</para>
-
-<para>
-To create the first space and the first <link linkend="an-index">index</link>, try this:<programlisting>
-<prompt>tarantool> </prompt><userinput>s = box.schema.space.create('tester')</userinput>
-<prompt>tarantool> </prompt><userinput>i = s:create_index('primary', {type = 'hash', parts = {1, 'NUM'}})</userinput></programlisting>
-</para>
-
-<para>
-To insert three <quote>tuples</quote> (our name for <quote>records</quote>) into the first <quote>space</quote> of the database
-try this:<programlisting><prompt>tarantool> </prompt><userinput>t = s:insert({1})</userinput>
-<prompt>tarantool> </prompt><userinput>t = s:insert({2, 'Music'})</userinput>
-<prompt>tarantool> </prompt><userinput>t = s:insert({3, 'Length', 93})</userinput>
-</programlisting>
-
-To select a tuple from the first space of the database,
-using the first defined key, try this:<programlisting><prompt>tarantool> </prompt><userinput>s:select{3}</userinput></programlisting>
-
-Your terminal screen should now look like this:<programlisting><computeroutput>
-tarantool> s = box.schema.space.create('tester')
-2014-06-10 12:04:18.158 ... creating `./00000000000000000002.xlog.inprogress'
----
-...
-tarantool> s:create_index('primary', {type = 'hash', parts = {1, 'NUM'}})
----
-...
-tarantool> t = s:insert{1}
----
-...
-tarantool> t = s:insert{2, 'Music'}
----
-...
-tarantool> t = s:insert{3, 'Length', 93}
----
-...
-tarantool> s:select{3}
----
-- - [3, 'Length', 93]
-...
-
-tarantool></computeroutput></programlisting>
-</para>
-
-<para>
-Now, to prepare for the example in the next section,
-try this:<programlisting><prompt>tarantool> </prompt><userinput>box.schema.user.grant('guest','read,write,execute','universe')</userinput></programlisting>
-</para>
-
-</section>
-<section xml:id="getting-started-connecting-remotely">
-<title>Starting another Tarantool instance and connecting remotely</title>
-
-<para>
-In the previous section the first request was
-with "box.cfg{listen=3301}". The "listen" value can be
-any form of URI (uniform resource identifier); in this
-case it's just a local port: port 3301. It's possible
-to send requests to the listen URI via (a) telnet,
-(b) a connector (which will be the subject of Chapter 8), or
-(c) another instance of Tarantool. Let's try (c).
-</para>
-<para>
-1. Switch to another terminal. On Linux, for example, this
-means starting another instance of a Bash shell.
-There is no need to use <computeroutput><command>cd</command></computeroutput> to switch to the ~/tarantool_sandbox directory.
-</para>
-<para>
-2. Start the second instance of Tarantool.
-The server name is <computeroutput><filename>tarantool</filename></computeroutput>.<programlisting><userinput>
-#if you downloaded a binary with apt-get or yum, say this:
- <command>/usr/bin/tarantool</command>
-#if you downloaded and untarred a binary tarball to ~/tarantool, say this:
- <command>~/tarantool/bin/tarantool</command>
-#if you built from a source download, say this:
- <command>~/tarantool/src/tarantool</command> </userinput></programlisting>
-</para>
-<para>
-3. Try these requests:<programlisting><userinput>console = require('console')
-console.connect('localhost:3301')
-box.space.tester:select{2}</userinput></programlisting>
-</para>
-<para>
-The requests are saying "use the <link linkend="sp-console">console package</link> to connect to the
-Tarantool server that's listening on localhost:3301, send a request
-to that server, and display the result." The result in this case is one of
-the tuples that was inserted earlier.
-Your terminal screen should now look like this:<programlisting><computeroutput>
-...
-
-tarantool> console = require('console')
----
-...
-
-tarantool> console.connect('localhost:3301')
-2014-08-31 12:46:54.650 [32628] main/101/interactive I> connected to localhost:3301
----
-...
-
-localhost:3301> box.space.tester:select{2}
----
-- - [2, 'Music']
-...
-
-localhost:3301></computeroutput></programlisting>
-</para>
-
-<para>
-You can repeat box.space...:insert{} and box.space...:select{} indefinitely,
-on either Tarantool instance.
-When the testing is over:
-To drop the space: <computeroutput>s:drop()</computeroutput>.
-To stop tarantool: <keycombo><keysym>Ctrl</keysym><keysym>C</keysym></keycombo>.
-To stop tarantool (an alternative): <computeroutput>os.exit()</computeroutput>.
-To stop tarantool (from another terminal): <computeroutput><command>sudo pkill</command> -f tarantool</computeroutput>.
-To destroy the test: <computeroutput><command>rm</command> -r ~/tarantool_sandbox</computeroutput>.
-</para>
-
-<sidebar>
-<para>
-To review ...
-If you followed all the instructions in this chapter, then
-so far you have: installed Tarantool from either a binary
-or a source repository, started up the Tarantool server,
-inserted and selected tuples.
-</para>
-</sidebar>
-
-</section>
-
-
-
-
-</chapter>
-
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/user/user.xml b/doc/user/user.xml
deleted file mode 100644
index 1b8d148ae9bba99c3bcf7dbd2ddee036ae8b7b84..0000000000000000000000000000000000000000
--- a/doc/user/user.xml
+++ /dev/null
@@ -1,31 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE book [
-<!ENTITY % tnt SYSTEM "../tnt.ent">
-%tnt;
-]>
-<book xmlns="http://docbook.org/ns/docbook" version="5.0"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xml:id="tarantool-user-guide">
-<title>Tarantool User Guide, version &tnt_version;</title>
-<xi:include href="preface.xml"/>
-<xi:include href="tutorial.xml"/>
-<xi:include href="lua-and-packages.xml"/>
-<xi:include href="databases.xml"/>
-<xi:include href="triggers.xml"/>
-<xi:include href="replication.xml"/>
-<xi:include href="server-administration.xml"/>
-<xi:include href="configuration-reference.xml"/>
-<xi:include href="connectors.xml"/>
-<xi:include href="errcode.xml"/>
-<xi:include href="proctitle.xml"/>
-<xi:include href="lua-tutorial.xml"/>
-<xi:include href="plugins.xml"/>
-<!--
-<xi:include href="faq.xml"/>
--->
-</book>
-<!--
-vim: tw=66 syntax=docbk
-vim: spell spelllang=en_us
--->
diff --git a/doc/www/CMakeLists.txt b/doc/www/CMakeLists.txt
index 29b7538151dbe4810373431d0a33900eb38c63f7..2f1a54930de67f204442d0b0a723c59d6950be15 100644
--- a/doc/www/CMakeLists.txt
+++ b/doc/www/CMakeLists.txt
@@ -5,5 +5,4 @@ if (PELICAN STREQUAL "PELICAN-NOTFOUND")
endif()
add_custom_target(www ALL
- DEPENDS html-saxon html-saxon-chunk dev-html-saxon
COMMAND ${PELICAN} -v)
diff --git a/doc/www/content/doc/faq.rst b/doc/www/content/doc/faq.rst
deleted file mode 100644
index 37cdebadf061fab97454372d3e65254fecefa876..0000000000000000000000000000000000000000
--- a/doc/www/content/doc/faq.rst
+++ /dev/null
@@ -1,79 +0,0 @@
-:title: FAQ's
-:slug: faq
-:save_as: doc/faq.html
-:template: old_documentation
-
--------------------------------------------------------------------------------
- Frequently Asked Questions
--------------------------------------------------------------------------------
-
-**Why Tarantool?**
-::
-
- Tarantool is a result of a long trial and error process within Mail.Ru. It's
- the Nth generation of a family of custom in-memory data servers, developed for
- various web applications. Besides, when Tarantool development started (2008)
- there were no stable and sufficiently functional open source alternative.
-
-**Why Lua?**
-::
-
- Lua is a ligthweight, fast, extensible multi-paradigm language. Lua also happens
- to be very easy to embed. Lua coroutines relate very closely to Tarantool fibers,
- and Lua architecture works well with Tarantool internals. Lua is the first, but,
- hopefully, not the last stored program language for Tarantool.
-
-**What's the key advantage of Tarantool?**
-::
-
- Tarantool provides a rich database feature set (HASH, TREE, RTREE, BITSET indexes,
- secondary indexes, composite indexes, transactions, triggres, asynchronous replication)
- in a flexible environment of a Lua interpreter.
-
- These two properties make it possible to code fast, atomic and reliable in-memory
- data servers which handle non-trivial application-specific logic. The win over
- traditional SQL servers is in performance: low-overhead, lock-free architecture
- means Tarantool can serve an order of magnitude more requests per second, on
- comparable hardware. The win over NoSQL alternatives is in flexibility: Lua
- allows flexible processing of data stored in a compact, denormalized format.
-
-**What are your development plans?**
-::
-
- We continuously improve server performance. On the feature front, automatic
- sharding and online upgrade are the two major goals of 2015.
-
-**Who is developing Tarantool?**
-::
-
- There is a small engineering team employed by Mail.ru -- check out our commit
- logs on github. The development is fully open, and most of the connectors
- authors and maintainers in different distributions are from the community.
-
-**How serious is Mail.Ru about Tarantool?**
-::
-
- Tarantool is an open source project, distributed under a BSD license, and as
- such does not depend on any one sponsor. However, it is currently and integral
- part of Mail.Ru backbone, so it gets a lot of support from Mail.ru.
-
-**Why is Tarantool primary port number 3303?**
-::
-
- It's a prime number which is easy to remember, because 3313, 3301, 313, 13 and
- 3 are also prime numbers.
-
-**My arena_used/items_used in SHOW SLAB output is >> 1. What does it mean and what should I do?**
-::
-
- If the ratio of arena_used to items_used >> 1, that indicates that there is
- fragmentation accumulated by the slab allocator. Imagine there are a lot of
- small tuples stored in the system initially, and later on each tuple becomes
- bigger and doesn't fit into its old slab size. The old slabs are never
- relinquished by the allocator. Currently this can be solved only by a server restart.
-
-**What happens when Tarantool runs out of memory?**
-::
-
- The server stops accepting updates until more memory is available. Read and
- delete requests are served just fine.
diff --git a/doc/www/content/doc/intro.rst b/doc/www/content/doc/intro.rst
deleted file mode 100644
index c6017ab423a55236fcc1d3b190982656f073da25..0000000000000000000000000000000000000000
--- a/doc/www/content/doc/intro.rst
+++ /dev/null
@@ -1,91 +0,0 @@
-:title: Overview
-:slug: intro
-:save_as: doc/introduction.html
-:url: doc/introduction.html
-:template: old_page
-
-===============================================================================
- What is Tarantool?
-===============================================================================
-
-Tarantool is a NoSQL database management system running in a Lua application
-server. The code is available for free under the terms of `BSD license`_.
-Supported platforms are GNU/Linux, Mac OS and FreeBSD.
-
-===============================================================================
- An overview of the architecture
-===============================================================================
-
-The server **maintains all its data in random-access memory**, and therefore
-has very low read latency. At the same time, a copy of the data is kept on
-non-volatile storage (a disk drive), and inserts and updates are performed
-atomically.
-
-To ensure atomicity, consistency and crash-safety of the persistent copy, a
-write-ahead log (WAL) is maintained, and each change is recorded in the WAL
-before it is considered complete. The logging subsystem supports group commit.
-
-If update and delete rate is high, a constantly growing write-ahead log file
-(or files) can pose a disk space problem, and significantly increase time
-necessary to restart from disk. A simple solution is employed: the server
-**can be requested to save a concise snapshot** of its current data. The
-underlying operating system's **"copy-on-write"** feature is employed to take
-the snapshot in a quick, resource-savvy and non-blocking manner. The
-**"copy-on-write"** technique guarantees that snapshotting has minimal impact
-on server performance.
-
-**Tarantool is lock-free**. Instead of the operating system's concurrency
-primitives, such as threads and mutexes, Tarantool uses a cooperative
-multitasking environment to simultaneously operate on thousands of
-connections. A fixed number of independent execution threads within
-the server do not share state, but exchange data using low overhead
-message queues. While this approach limits server scalability to a
-few CPU cores, it removes competition for the memory bus and sets the
-scalability limit to the top of memory and network throughput. CPU
-utilization of a typical highly-loaded Tarantool server is under 10%.
-
-===============================================================================
- Key features
-===============================================================================
-
-Unlike most of NoSQL databases, Tarantool supports primary, **secondary keys,
-multi-part keys**, HASH, TREE and BITSET index types.
-
-Tarantool supports **Lua stored procedures**, which can access and modify data
-atomically. Procedures can be created, modified and dropped at runtime.
-
-Use of Lua as an extension language does not end with stored procedures: Lua
-programs can be used during startup, to define triggers and background tasks,
-interact with networked peers. Unlike popular application development
-frameworks implemented around "reactor" pattern, networking in server-side Lua
-is sequential, yet very efficient, as is built on top of the cooperating
-multitasking environment used by the server itself.
-
-Extended with Lua, Tarantool typically replaces more not one but a few existing
-components with a single well-performing system, changing and simplifying
-complex multi-tier Web application architectures.
-
-Tarantool supports replication. Replicas may run locally or on a remote host.
-Tarantool replication is asynchronous and does not block writes to the master.
-When or if the master becomes unavailable, the replica can be switched to
-assume the role of the master without server restart.
-
-===============================================================================
- How stable is the software?
-===============================================================================
-
-**The software is production-ready**. Tarantool has been created and is actively
-used at `Mail.Ru`_, one of the leading Russian web content providers. At `Mail.Ru`_,
-the software serves the **"hottest"** data, such as online users and their
-sessions, online application properties, mapping between users and their
-serving shards, and so on.
-
-Outside `Mail.Ru`_ the software is used by a growing number of projects in online
-gaming, digital marketing, social media industries. While product development
-is sponsored by `Mail.Ru`_, the roadmap, bugs database and the development process
-are fully open. The software incorporates patches from dozens of community
-contributors, and most of the programming language drivers are written and
-supported by the community.
-
-.. _BSD license: http://www.gnu.org/licenses/license-list.html#ModifiedBSD
-.. _Mail.Ru: http://api.mail.ru
diff --git a/doc/www/content/js/index_tabs.js b/doc/www/content/js/index_tabs.js
index c06f018db0a2e465aca1920081c174fafc495f98..9604f55d910955dc4752ac64b1a4c311ba3b94dd 100644
--- a/doc/www/content/js/index_tabs.js
+++ b/doc/www/content/js/index_tabs.js
@@ -10,38 +10,11 @@
link.addClass('p-active');
var title = $('.b-benchmark-type-title');
var image = $('#b-benchmark-grapf-image');
-
- switch (link.html()) {
- case 'A' : {
- title.html('Workload A');
- image.renderChart('/ycsb/A_throughput.json');
- break;
- } case 'B' : {
- title.html('Workload B');
- image.renderChart('/ycsb/B_throughput.json');
- break;
- } case 'C' : {
- title.html('Workload C');
- image.renderChart('/ycsb/C_throughput.json');
- break;
- } case 'D' : {
- title.html('Workload D');
- image.renderChart('/ycsb/D_throughput.json');
- break;
- } case 'E' : {
- title.html('Workload E');
- image.renderChart('/ycsb/E_throughput.json');
- break;
- } case 'F' : {
- title.html('Workload F');
- image.renderChart('/ycsb/F_throughput.json');
- break;
- } case 'LOAD' : {
- title.html('Insert Only');
- image.renderChart('/ycsb/LOAD_throughput.json');
- break;
- }
+ title.html('Workload ' + link.html());
+ if (link.html() == 'LOAD') {
+ title.html('Insert Only');
}
+ image.renderChart('/ycsb/' + link.html() + '_throughput.json');
$('.b-benchmark-type .b-switcher-item-url.p-active').removeClass('p-active');
$('.b-benchmark-type .b-switcher-item-url').first().addClass('p-active');
}
@@ -58,36 +31,28 @@
var title = $('.b-benchmark-type-title').html();
var image = $('#b-benchmark-grapf-image');
- if (title == 'Workload A' && link.html() == 'Latency') {
- image.renderChart('/ycsb/A_READ_latency.json');
- } else if (title == 'Workload A' && link.html() == 'Throughput') {
- image.renderChart('/ycsb/A_throughput.json')
- } else if (title == 'Workload B' && link.html() == 'Latency') {
- image.renderChart('/ycsb/B_READ_latency.json');
- } else if (title == 'Workload B' && link.html() == 'Throughput') {
- image.renderChart('/ycsb/B_throughput.json')
- } else if (title == 'Workload C' && link.html() == 'Latency') {
- image.renderChart('/ycsb/C_READ_latency.json');
- } else if (title == 'Workload C' && link.html() == 'Throughput') {
- image.renderChart('/ycsb/C_throughput.json')
- } else if (title == 'Workload D' && link.html() == 'Latency') {
- image.renderChart('/ycsb/D_READ_latency.json');
- } else if (title == 'Workload D' && link.html() == 'Throughput') {
- image.renderChart('/ycsb/D_throughput.json')
- } else if (title == 'Workload E' && link.html() == 'Latency') {
- image.renderChart('/ycsb/E_SCAN_latency.json');
- } else if (title == 'Workload E' && link.html() == 'Throughput') {
- image.renderChart('/ycsb/E_throughput.json')
- } else if (title == 'Workload F' && link.html() == 'Latency') {
- image.renderChart('/ycsb/F_READ_latency.json');
- } else if (title == 'Workload F' && link.html() == 'Throughput') {
- image.renderChart('/ycsb/F_throughput.json')
- } else if (title == 'Insert Only' && link.html() == 'Latency') {
- image.renderChart('/ycsb/LOAD_INSERT_latency.json');
- } else if (title == 'Insert Only' && link.html() == 'Throughput') {
- image.renderChart('/ycsb/LOAD_throughput.json')
+ var table = {
+ 'A': 'READ',
+ 'B': 'READ',
+ 'C': 'READ',
+ 'D': 'READ',
+ 'E': 'SCAN',
+ 'F': 'READ',
+ 'LOAD': 'INSERT'
+ };
+ var letter = '';
+ if (title == 'Insert Only') {
+ letter = 'LOAD';
+ } else {
+ letter = title.replace('Workload ', '');
+ }
+ if (link.html() == 'Latency') {
+ image.renderChart('/ycsb/' + letter +
+ '_' + table[letter] + '_latency.json');
+ } else if (link.html() == 'Throughput') {
+ image.renderChart('/ycsb/' + letter +
+ '_throughput.json');
}
-
}
}
}, '.b-benchmark-type .b-switcher-item')
diff --git a/doc/www/content/newsite/download.yml.in b/doc/www/content/newsite/download.yml.in
index c18c830e31f1e40639905553015ca6b320df59f2..19163858de2f79a6339d778c0495c970a534efec 100644
--- a/doc/www/content/newsite/download.yml.in
+++ b/doc/www/content/newsite/download.yml.in
@@ -69,7 +69,7 @@ blocks :
.. code-block:: bash
- $ brew install https://raw.githubusercontent.com/tarantool/tarantool/master/extra/tarantool.rb --devel
+ $ brew install http://build.tarantool.org/tarantool.rb --devel
Please upgrade ``clang`` to version 3.2 or later using
``Command Line Tools for Xcode`` disk image version 4.6+
diff --git a/doc/www/pelicanconf.py b/doc/www/pelicanconf.py
index 7bb7b92a3ec3e17af5410ee8e0712424cc732b1f..6048301885249f998ebba48bafe5b169ad288da6 100644
--- a/doc/www/pelicanconf.py
+++ b/doc/www/pelicanconf.py
@@ -14,7 +14,7 @@ TIMEZONE = 'Europe/Moscow'
DEFAULT_LANG = u'en'
-PLUGINS = ['plugins.documentation', 'plugins.beautifulsite']
+PLUGINS = ['plugins.beautifulsite']
# Feed generation is usually not desired when developing
FEED_ALL_ATOM = None
@@ -23,7 +23,6 @@ TRANSLATION_FEED_ATOM = None
DEFAULT_PAGINATION = False
-DOCS_PATH = ['doc']
BSITE_PATH = ['newsite']
ARTICLE_EXCLUDES = ['doc', 'newsite']
diff --git a/doc/www/plugins/beautifulsite/beautifulsite.py b/doc/www/plugins/beautifulsite/beautifulsite.py
index 9edf97756c0910af47de4620f0368ed74b9daf0c..c51332cd3e523bc7d525116df736c0f3251bd452 100644
--- a/doc/www/plugins/beautifulsite/beautifulsite.py
+++ b/doc/www/plugins/beautifulsite/beautifulsite.py
@@ -9,7 +9,7 @@ import itertools
import re
import yaml
-import docutils
+import docutils.core
import collections
from BeautifulSoup import BeautifulSoup as BSHTML
diff --git a/doc/www/plugins/documentation/__init__.py b/doc/www/plugins/documentation/__init__.py
deleted file mode 100644
index e77810ed33ed27b0cfc67a381a7fc252aeca4964..0000000000000000000000000000000000000000
--- a/doc/www/plugins/documentation/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-from .documentation import *
diff --git a/doc/www/plugins/documentation/documentation.py b/doc/www/plugins/documentation/documentation.py
deleted file mode 100644
index d2013af2b00da6a8b0f9a961ae69ee41a7005919..0000000000000000000000000000000000000000
--- a/doc/www/plugins/documentation/documentation.py
+++ /dev/null
@@ -1,121 +0,0 @@
-from pelican import signals
-from pelican.generators import Generator
-from pelican.contents import Content, is_valid_content
-
-import os
-import glob
-import logging
-import itertools
-
-from BeautifulSoup import BeautifulSoup as BSHTML
-
-logger = logging.getLogger(__name__)
-
-class Documentation(Content):
- mandatory_properties = ('title', )
- default_template = 'old_documentation'
-
-class DocumentationContainer(object):
- def __init__(self, opage):
- self.opage = opage
- self.mpage = []
-
- def add_mpage(self, mpage):
- self.mpage.append(mpage)
-
-class DocumentationGenerator(Generator):
- def __init__(self, *args, **kwargs):
- super(DocumentationGenerator, self).__init__(*args, **kwargs)
- self.doc_html = []
- self.doc_rst = []
-
- def _doc_read_file(self, relpath, op=False):
- abspath = os.path.join(self.path, relpath)
- page = open(abspath, 'r').read()
- page = type('Documentation', (object, ), {
- 'get_relative_source_path': (lambda x: x.save_as),
- 'content' : page,
- 'title' : BSHTML(page).find('title').getText(),
- 'url' : relpath if op else os.path.dirname(relpath),
- 'save_as' : relpath,
- 'template': 'old_documentation'
- })()
- self.add_source_path(page)
- return page
-
- def generate_context(self):
- def b_path(left, right):
- return os.path.join(left,
- os.path.basename(right))
- def db_path(left, right):
- return os.path.join(left,
- os.path.basename(os.path.dirname(right)),
- os.path.basename(right))
-
- for docpath in self.settings['DOCS_PATH']:
- abspath = os.path.join(self.path, docpath, '*.html')
- for op_abspath in glob.glob(abspath):
- op_relpath = b_path(docpath, op_abspath)
- if not os.path.isfile(op_abspath):
- continue
- page = self._doc_read_file(op_relpath, True)
- self.doc_html.append(DocumentationContainer(page))
- if not os.path.isdir(op_abspath[:-5]):
- continue
- mp_abspath = os.path.join(op_abspath[:-5], '*.html')
- for mp_html_abspath in glob.glob(mp_abspath):
- mp_html_relpath = db_path(docpath, mp_html_abspath)
- if not os.path.isfile(mp_html_abspath):
- continue
- page = self._doc_read_file(mp_html_relpath, False)
- self.doc_html[-1].add_mpage(page)
- for docpath in self.settings['DOCS_PATH']:
- abspath = os.path.join(self.path, docpath, '*.rst')
- for op_abspath in glob.glob(abspath):
- op_relpath = b_path(docpath, op_abspath)
- if not os.path.isfile(op_abspath):
- continue
- page = None
- try:
- page = self.readers.read_file(
- base_path = self.path, path = op_relpath,
- content_class = Documentation, context = self.context)
- except Exception as e:
- logger.error('Could not process %s\n%s', op_relpath, e,
- exc_info=self.settings.get('DEBUG', False))
- continue
- if not is_valid_content(page, op_relpath):
- continue
- if page:
- self.doc_rst.append(DocumentationContainer(page))
-
- def generate_output(self, writer):
- for doc_cont in self.doc_html:
- opage = doc_cont.opage
- writer.write_file(
- opage.save_as,
- self.get_template(opage.template),
- self.context,
- page = opage,
- documentation = True)
- for mpage in doc_cont.mpage:
- writer.write_file(
- mpage.save_as,
- self.get_template(mpage.template),
- self.context,
- page = mpage,
- documentation = True)
- for doc_cont in self.doc_rst:
- opage = doc_cont.opage
- writer.write_file(
- opage.save_as,
- self.get_template(opage.template),
- self.context,
- page = opage,
- documentation = False)
-
-def get_generators(pelican_object):
- return DocumentationGenerator
-
-def register():
- signals.get_generators.connect(get_generators)
diff --git a/doc/www/theme/static/design.css b/doc/www/theme/static/design.css
index 6376bf414de54cbb40a8648b7fc2c84287c7d516..2365517ffad4cf7463166e605d2735b342978fd3 100644
--- a/doc/www/theme/static/design.css
+++ b/doc/www/theme/static/design.css
@@ -1248,7 +1248,7 @@ input.b-button.p-smaller {
padding-bottom: 35px;
}
.b-downloads_top .b-section-title {
- margin:0 0 2px 0;
+ margin:0 0 20px 0;
}
.b-downloads .b-block-wrapper {
padding-top:27px;
@@ -1440,4 +1440,36 @@ div.b-rock-list-item-ico {
display:none;
}
+.b-rocks article.b-article {
+ margin-bottom: 0px;
+}
+.b-rocks article.b-article ul {
+ padding-bottom: 0px;
+}
+.b-rocks article.b-article li {
+ padding: 0 0 8px 0;
+}
+.b-rocks article.b-article li {
+ margin: 0px 20px 1px;
+}
+.b-rocks article.b-article p {
+ padding: 0 0 5px;
+}
+.b-rocks article.b-article pre {
+ padding: 10px 0 20px 20px;
+ margin: 0;
+}
+.b-rocks h2.b-section-title,
+.b-downloads h2.b-section-title{
+ margin: 0 0 20px 0;
+/* font-size: 25px;*/
+}
+
+/*.b-rocks .b-section-text {
+ font-size: 15px;
+}*/
+
+.b-rocks .b-rock-list {
+ padding: 0 0 50px 0;
+}
/* vim: expandtab */
diff --git a/doc/www/theme/static/old_header.css b/doc/www/theme/static/old_header.css
index e4d49c447a191f6f5832e2272e50dd9a359b9b4b..22ad82701c83ce70185c6e4f121f5c4eedf46855 100644
--- a/doc/www/theme/static/old_header.css
+++ b/doc/www/theme/static/old_header.css
@@ -61,6 +61,38 @@
height: 0;
}
+/* -- relbar ---------------------------------------------------------------- */
+
+div.related {
+ width: 100%;
+ font-size: 90%;
+}
+
+div.related h3 {
+ display: none;
+}
+
+div.related ul {
+ margin: 0;
+ padding: 0 0 0 10px;
+ list-style: none;
+}
+
+div.related li {
+ display: inline;
+}
+
+div.related li.right {
+ float: right;
+ margin-right: 5px;
+}
+
+div.related li.center {
+ float: center;
+ margin-right: 5px;
+}
+
+
/* =============================================================================
Links
========================================================================== */
diff --git a/doc/www/theme/templates/base b/doc/www/theme/templates/base
index 67eee8f6dd3f23e3fd33ae13413a683992da9283..b7b38927de5c22743185a4619decd91f098f82a3 100644
--- a/doc/www/theme/templates/base
+++ b/doc/www/theme/templates/base
@@ -19,7 +19,6 @@
{% endblock header_scripts %}
{% include "script" ignore missing %}
</head>
-
<body class="p-main">
<div class="b-wrapper">
<!-- HEADER > -->
diff --git a/doc/www/theme/templates/documentation_rst.html b/doc/www/theme/templates/documentation_rst.html
new file mode 100644
index 0000000000000000000000000000000000000000..f7d4bab57b0ddac7d5922835dd10d0ce7dfcbde0
--- /dev/null
+++ b/doc/www/theme/templates/documentation_rst.html
@@ -0,0 +1,46 @@
+{% extends "base" %}
+
+{% block header_scripts %}
+<script src="js/main.js"></script>
+{% endblock header_scripts %}
+
+{% block content %}
+<section class="b-lightgray_block b-documentation_top b-clearbox p-documentation_in">
+ <div class="b-block-wrapper">
+ <h2 class="b-section-title">Documentation</h2>
+ <!--div class="b-search">
+ <input class="b-search-text" data-placeholder="Search in documentation" />
+ <input class="b-search-but" type="submit" />
+ </div-->
+ </div>
+</section>
+
+<div class="b-cols_content b-clearbox">
+ <!--div class="b-cols_content_left">
+ <ul class="b-tcontents_full-list">
+ <li class="b-tcontents_full-list-item p-active">
+ <h2 class="b-tcontents_full-list-item-title">
+ {# number #}<a href="{# link #}">{# name #}</a>
+ </h2>
+ <p class="b-tcontents_full-list-item-disc">{# text #}</p>
+ <ul class="b-tcontents_full-sublist">
+ <li class="b-tcontents_full-sublist-item">
+ {# number #}<a href="{# link #}">{# name #}</a>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </div-->
+ <div class="b-cols_content_left">
+ </div>
+ <div class="b-cols_content_right">
+ <div class="b-cols_content_right-slot">
+ <article class="b-article">
+ {{ page.content }}
+ </article>
+ </div>
+ </div>
+</div>
+{% endblock %}
+
+{# vim: syntax=htmldjango ts=2 sts=2 sw=2 expandtab #}
diff --git a/doc/www/theme/templates/menu b/doc/www/theme/templates/menu
index dd50b676c8f37ac06a95dc63b56b029f61d4e069..1e48fbd12b7d8aa61b2d9ae4f2b7e7cf14371901 100644
--- a/doc/www/theme/templates/menu
+++ b/doc/www/theme/templates/menu
@@ -1,9 +1,10 @@
+
{# Modify i_links to add records to site #}
{% set i_links = [
("Overview", "http://tarantool.org"),
("Try", "http://try.tarantool.org"),
- ("Documentation", "http://tarantool.org/documentation.html"),
+ ("Documentation", "http://tarantool.org/doc/"),
("Download", "http://tarantool.org/download.html"),
("Rocks", "http://rocks.tarantool.org")
] %}
diff --git a/extra/dist/CMakeLists.txt b/extra/dist/CMakeLists.txt
index 0e4f968d04703f15db0f62b8e427a094e437f3d2..848aaa80612ba514aad94639b19125eefbbbe3a5 100644
--- a/extra/dist/CMakeLists.txt
+++ b/extra/dist/CMakeLists.txt
@@ -42,7 +42,7 @@ endif(ENABLE_RPM)
install (FILES tarantoolctl DESTINATION ${CMAKE_INSTALL_BINDIR}
PERMISSIONS
- OWNER_READ OWNER_WRITE
+ OWNER_READ OWNER_WRITE OWNER_EXECUTE
GROUP_READ GROUP_EXECUTE
WORLD_READ WORLD_EXECUTE
)
diff --git a/extra/dist/tarantoolctl b/extra/dist/tarantoolctl
index d9f5b156006473d5616c953eae7facbfabce8e68..4275bf1c37f55f0ad63c0ffe88c9a6a23e6657b5 100755
--- a/extra/dist/tarantoolctl
+++ b/extra/dist/tarantoolctl
@@ -106,6 +106,24 @@ local fiber = require 'fiber'
ffi.cdef[[ int kill(int pid, int sig); ]]
+local config_file = os.getenv('HOME') .. '/.config/tarantool/tarantool'
+local usermode = true
+
+if not fio.stat(config_file) then
+ usermode = false
+ local config_list = {
+ '/etc/sysconfig/tarantool',
+ '/etc/default/tarantool',
+ '/usr/local/etc/tarantool/tarantool',
+ }
+
+ for _, c in pairs(config_list) do
+ if fio.stat(c) then
+ config_file = c
+ break
+ end
+ end
+end
local available_commands = {
'start',
@@ -113,12 +131,14 @@ local available_commands = {
'logrotate',
'status',
'enter',
- 'restart'
+ 'restart',
+ 'reload'
}
local function usage()
log.error("Usage: %s {%s} instance_name",
arg[0], table.concat(available_commands, '|'))
+ log.error("Config file: %s", config_file)
os.exit(1)
end
@@ -164,11 +184,18 @@ end
shift_argv(arg, 0, 2)
-if fio.stat('/etc/sysconfig/tarantool') then
- dofile('/etc/sysconfig/tarantool')
-elseif fio.stat('/etc/default/tarantool') then
- dofile('/etc/default/tarantool')
+local instance_lua = nil
+
+
+dofile(config_file)
+if instance_dir then
+ instance_lua = fio.pathjoin(instance_dir, instance .. '.lua')
+ if fio.stat(instance_lua) then
+ log.info('Found %s.lua in %s', instance, instance_dir)
+ end
end
+instance_dir = nil
+instance_lua = nil
if default_cfg == nil then
default_cfg = {}
@@ -176,6 +203,7 @@ end
if instance_dir == nil then
instance_dir = '/etc/tarantool/instances.enabled'
+ instance_lua = fio.pathjoin(instance_dir, instance .. '.lua')
end
default_cfg.pid_file = default_cfg.pid_file and default_cfg.pid_file or "/var/run/tarantool"
@@ -183,7 +211,10 @@ default_cfg.wal_dir = default_cfg.wal_dir and default_cfg.wal_dir or "/var/li
default_cfg.snap_dir = default_cfg.snap_dir and default_cfg.snap_dir or "/var/lib/tarantool"
default_cfg.sophia_dir = default_cfg.sophia_dir and default_cfg.sophia_dir or "/var/lib/tarantool"
default_cfg.logger = default_cfg.logger and default_cfg.logger or "/var/log/tarantool"
-default_cfg.username = default_cfg.username and default_cfg.username or "tarantool"
+-- change user name only if not running locally
+if not usermode then
+ default_cfg.username = default_cfg.username and default_cfg.username or "tarantool"
+end
-- create a path to the control socket (admin console)
local console_sock = fio.pathjoin(default_cfg.pid_file, instance .. '.control')
@@ -203,7 +234,7 @@ local function mkdir(dirname)
os.exit(-1)
end
- if not fio.chown(dirname, default_cfg.username, default_cfg.username) then
+ if not usermode and not fio.chown(dirname, default_cfg.username, default_cfg.username) then
log.error("Can't chown(%s, %s, %s): %s",
default_cfg.username, default_cfg.username, dirname, errno.strerror())
end
@@ -300,7 +331,14 @@ end
function start()
log.info("Starting instance...")
box.cfg = wrapper_cfg
- dofile(instance_lua)
+ local success, data = pcall(dofile, instance_lua)
+ -- if load fails - show last 10 lines of the log file
+ if not success then
+ print('Start failed: ' .. data)
+ if fio.stat(default_cfg.logger) then
+ os.execute('tail -n 10 ' .. default_cfg.logger)
+ end
+ end
end
@@ -354,6 +392,7 @@ elseif cmd == 'enter' then
elseif cmd == 'status' then
if fio.stat(force_cfg.pid_file) == nil then
if errno() == errno.ENOENT then
+ print(instance .. ' is stopped (pid file does not exist)')
os.exit(1)
end
log.error("Cant access pidfile %s: %s",
@@ -380,7 +419,16 @@ elseif cmd == 'status' then
end
s:close()
+ print(instance .. ' is running (pid:' .. force_cfg.pid_file .. ')')
os.exit(0)
+elseif cmd == 'reload' then
+ if fio.stat(arg[2]) == nil then
+ if errno() == errno.ENOENT then
+ print(arg[2] .. ': file not found')
+ os.exit(1)
+ end
+ end
+ dofile(arg[2])
else
log.error("Unknown command '%s'", cmd)
os.exit(-1)
diff --git a/extra/tarantool.rb b/extra/tarantool.rb
index cb5e2a858be8239e399eb90ec21ecdfe50c59a80..81f6a35ee5e600a00cc2b8db269b6b78d8c363a6 100644
--- a/extra/tarantool.rb
+++ b/extra/tarantool.rb
@@ -44,6 +44,7 @@ class Tarantool < Formula
args << "-DENABLE_CLIENT=True" if build.stable?
args << "-DCMAKE_INSTALL_SYSCONFDIR=#{prefix}/etc"
args << "-DCMAKE_INSTALL_LOCALSTATEDIR=#{prefix}/var"
+ args << "-DREADLINE_ROOT=/usr/local/Cellar"
args += std_cmake_args
ohai "Preparing"
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index 3371f50228a5193f0a41b7ec3b7acec4f0e55e4b..58d917314372edbf732f957f47e8d11820032874 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -25,7 +25,7 @@ lua_source(lua_sources lua/console.lua)
lua_source(lua_sources lua/bsdsocket.lua)
lua_source(lua_sources lua/errno.lua)
lua_source(lua_sources lua/log.lua)
-lua_source(lua_sources lua/box_net_box.lua)
+lua_source(lua_sources lua/net_box.lua)
lua_source(lua_sources lua/help.lua)
lua_source(lua_sources lua/help_en_US.lua)
lua_source(lua_sources lua/tap.lua)
diff --git a/src/box/box.cc b/src/box/box.cc
index 87684c20e136cf559d889f5c3842f786c4f3320d..ae8ce453c647b5935d7a39ecf9d95d4d5f9dfcda 100644
--- a/src/box/box.cc
+++ b/src/box/box.cc
@@ -459,7 +459,8 @@ box_init(void)
fiber_gc();
title("orphan", NULL);
- recovery_follow_local(recovery, cfg_getd("wal_dir_rescan_delay"));
+ recovery_follow_local(recovery, "hot_standby",
+ cfg_getd("wal_dir_rescan_delay"));
title("hot_standby", NULL);
iproto_init(&binary);
diff --git a/src/box/errcode.h b/src/box/errcode.h
index 87dfc827d87f8267b2a50f9d5eeeb4bf3b9a858d..29b950a262883db4f38062bba966fec2e13c8cfc 100644
--- a/src/box/errcode.h
+++ b/src/box/errcode.h
@@ -146,6 +146,7 @@ struct errcode_record {
/* 92 */_(ER_ROLE_NOT_GRANTED, 2, "User '%s' does not have role '%s'") \
/* 93 */_(ER_MISSING_SNAPSHOT, 2, "Can't find snapshot") \
/* 94 */_(ER_CANT_UPDATE_PRIMARY_KEY, 2, "Attempt to modify a tuple field which is part of index %s") \
+ /* 95 */_(ER_UPDATE_INTEGER_OVERFLOW, 2, "Integer overflow when performing '%c' operation on field %u") \
/*
* !IMPORTANT! Please follow instructions at start of the file
diff --git a/src/box/lua/load_cfg.lua b/src/box/lua/load_cfg.lua
index 85d5fcb1f6fcff912852ba2f7bb00b516cff5273..be134f513847b37597850c49776af67349e09f96 100644
--- a/src/box/lua/load_cfg.lua
+++ b/src/box/lua/load_cfg.lua
@@ -47,7 +47,7 @@ local default_cfg = {
rows_per_wal = 500000,
wal_dir_rescan_delay= 0.1,
panic_on_snap_error = true,
- panic_on_wal_error = false,
+ panic_on_wal_error = true,
replication_source = nil,
custom_proc_title = nil,
pid_file = nil,
@@ -129,6 +129,8 @@ local dynamic_cfg = {
-- snapshot_daemon
snapshot_period = box.internal.snapshot_daemon.set_snapshot_period,
snapshot_count = box.internal.snapshot_daemon.set_snapshot_count,
+ -- do nothing, affects new replicas, which query this value on start
+ wal_dir_rescan_delay = function() end
}
local dynamic_cfg_skip_at_load = {
@@ -149,13 +151,13 @@ local function prepare_cfg(cfg, default_cfg, template_cfg, modify_cfg, prefix)
if cfg.dont_check then
return
end
- readable_prefix = ''
+ local readable_prefix = ''
if prefix ~= nil and prefix ~= '' then
readable_prefix = prefix .. '.'
end
local new_cfg = {}
for k,v in pairs(cfg) do
- readable_name = readable_prefix .. k;
+ local readable_name = readable_prefix .. k;
if template_cfg[k] == nil then
error("Error: cfg parameter '" .. readable_name .. "' is unexpected")
elseif v == "" or v == nil then
diff --git a/src/box/lua/tuple.lua b/src/box/lua/tuple.lua
index 78adccd02e1067294119c4d04840dbb1a9ca7dac..66849b6777206d6360f209139897d873003c9c77 100644
--- a/src/box/lua/tuple.lua
+++ b/src/box/lua/tuple.lua
@@ -102,11 +102,6 @@ local function tuple_ipairs(tuple, pos)
return fun.wrap(it, tuple, pos)
end
--- a precreated metatable for totable()
-local tuple_totable_mt = {
- __serialize = 'seq'; -- enables flow mode for yaml
-}
-
local function tuple_totable(tuple, i, j)
-- use a precreated iterator for tuple_next
builtin.tuple_rewind(next_it, tuple)
@@ -134,7 +129,7 @@ local function tuple_totable(tuple, i, j)
i = i + 1
field = builtin.tuple_next(next_it)
end
- return setmetatable(ret, tuple_totable_mt)
+ return setmetatable(ret, msgpackffi.array_mt)
end
local function tuple_unpack(tuple, i, j)
diff --git a/src/box/recovery.cc b/src/box/recovery.cc
index 53685c203a9efe6f72ad4b2e5938529076af1b79..a4b8d662ac29bbf2f192a37dc238ceb93666b695 100644
--- a/src/box/recovery.cc
+++ b/src/box/recovery.cc
@@ -301,8 +301,10 @@ recover_xlog(struct recovery_state *r, struct xlog *l)
* marker - such snapshots are very likely unfinished
* or corrupted, and should not be trusted.
*/
- if (l->dir->type == SNAP && l->is_inprogress == false && i.eof_read == false)
+ if (l->dir->type == SNAP && l->is_inprogress == false &&
+ i.eof_read == false) {
panic("snapshot `%s' has no EOF marker", l->filename);
+ }
/*
* xlog_cursor_next() returns 1 when
@@ -393,7 +395,6 @@ recover_remaining_wals(struct recovery_state *r)
struct xlog *next_wal;
int64_t current_signature, last_signature;
struct vclock *current_vclock;
- size_t rows_before;
enum log_suffix suffix;
xdir_scan(&r->wal_dir);
@@ -447,20 +448,6 @@ recover_remaining_wals(struct recovery_state *r)
next_wal = xlog_open(&r->wal_dir, current_signature, suffix);
} catch (XlogError *e) {
e->log();
- /*
- * When doing final recovery, and dealing with the
- * last file, try opening .<ext>.inprogress.
- */
- if (r->finalize && suffix == INPROGRESS) {
- /*
- * There is an .inprogress file, but
- * we failed to open it. Try to
- * delete it.
- */
- if (inprogress_log_unlink(format_filename(
- &r->wal_dir, current_signature, INPROGRESS)) != 0)
- panic("can't unlink 'inprogres' WAL");
- }
break;
}
assert(r->current_wal == NULL);
@@ -469,18 +456,11 @@ recover_remaining_wals(struct recovery_state *r)
say_info("recover from `%s'", r->current_wal->filename);
recover_current_wal:
- rows_before = r->current_wal->rows;
-
int result = recover_xlog(r, r->current_wal);
-
- if (r->current_wal->rows > 0 &&
- r->current_wal->rows != rows_before) {
- r->current_wal->retry = 0;
- }
/* rows == 0 could indicate an empty WAL */
if (r->current_wal->rows == 0) {
- say_error("read zero records from %s",
+ say_error("read zero records from `%s`",
r->current_wal->filename);
break;
}
@@ -492,20 +472,12 @@ recover_remaining_wals(struct recovery_state *r)
/* last file is not finished */
break;
} else if (r->finalize && r->current_wal->is_inprogress) {
- say_warn("fail to find eof on inprogress");
+ say_warn("failed to find EOF in `%s`",
+ r->current_wal->filename);
/* Let recovery_finalize deal with last file */
break;
- } else if (r->current_wal->retry++ < 3) {
- /*
- * If a newer WAL appeared in the directory before
- * current_wal was fully read, try re-reading
- * one last time. */
- say_warn("`%s' has no EOF marker, yet a newer WAL file exists:"
- " trying to re-read (attempt #%d)",
- r->current_wal->filename, r->current_wal->retry);
- goto recover_current_wal;
} else {
- say_warn("WAL `%s' wasn't correctly closed",
+ say_warn("WAL `%s` wasn't correctly closed",
r->current_wal->filename);
recovery_close_log(r);
}
@@ -527,7 +499,6 @@ void
recovery_finalize(struct recovery_state *r, enum wal_mode wal_mode,
int rows_per_wal)
{
-
recovery_stop_local(r);
r->finalize = true;
@@ -600,12 +571,12 @@ recovery_follow_f(va_list ap)
}
void
-recovery_follow_local(struct recovery_state *r,
+recovery_follow_local(struct recovery_state *r, const char *name,
ev_tstamp wal_dir_rescan_delay)
{
assert(r->writer == NULL);
assert(r->watcher == NULL);
- r->watcher = fiber_new(fiber_name(fiber()), recovery_follow_f);
+ r->watcher = fiber_new(name, recovery_follow_f);
fiber_set_joinable(r->watcher, true);
fiber_start(r->watcher, r, wal_dir_rescan_delay);
}
@@ -901,14 +872,11 @@ wal_opt_rotate(struct xlog **wal, struct recovery_state *r,
l = NULL;
}
if (l == NULL) {
- /* Open WAL with '.inprogress' suffix. */
- l = xlog_create(&r->wal_dir, vclock);
/*
- * Close the file *after* we create the new WAL, since
- * this is when replication relays get an inotify alarm
- * (when we close the file), and try to reopen the next
- * WAL. In other words, make sure that replication relays
- * try to open the next WAL only when it exists.
+ * Close the file *before* we create the new WAL, to
+ * make sure local hot standby/replication can see
+ * EOF in the old WAL before switching to the new
+ * one.
*/
if (wal_to_close) {
/*
@@ -920,6 +888,8 @@ wal_opt_rotate(struct xlog **wal, struct recovery_state *r,
xlog_close(wal_to_close);
wal_to_close = NULL;
}
+ /* Open WAL with '.inprogress' suffix. */
+ l = xlog_create(&r->wal_dir, vclock);
} else if (l->rows == 1) {
/*
* Rename WAL after the first successful write
diff --git a/src/box/recovery.h b/src/box/recovery.h
index 1be77446b966637c8d737ef967016ddb60aa45d3..ad4eabf3070cfef8a82ca0fe7d602462715cc34b 100644
--- a/src/box/recovery.h
+++ b/src/box/recovery.h
@@ -135,7 +135,9 @@ recovery_has_data(struct recovery_state *r)
}
void recovery_bootstrap(struct recovery_state *r);
void recover_snap(struct recovery_state *r);
-void recovery_follow_local(struct recovery_state *r, ev_tstamp wal_dir_rescan_delay);
+void recovery_follow_local(struct recovery_state *r,
+ const char *name,
+ ev_tstamp wal_dir_rescan_delay);
void recovery_stop_local(struct recovery_state *r);
void recovery_finalize(struct recovery_state *r, enum wal_mode mode,
diff --git a/src/box/replication.cc b/src/box/replication.cc
index 3e6e749cd25e7819ff6b2d10b7bece2bbbcb2c3c..aec788cb7d166af96b32014cca054ea11fa4d885 100644
--- a/src/box/replication.cc
+++ b/src/box/replication.cc
@@ -55,6 +55,7 @@ Relay::Relay(int fd_arg, uint64_t sync_arg)
coio_init(&io);
io.fd = fd_arg;
sync = sync_arg;
+ wal_dir_rescan_delay = cfg_getd("wal_dir_rescan_delay");
}
Relay::~Relay()
@@ -117,7 +118,8 @@ replication_subscribe_f(va_list ap)
struct recovery_state *r = relay->r;
relay_set_cord_name(relay->io.fd);
- recovery_follow_local(r, 0.1);
+ recovery_follow_local(r, fiber_name(fiber()),
+ relay->wal_dir_rescan_delay);
/*
* Init a read event: when replica closes its end
* of the socket, we can read EOF and shutdown the
@@ -125,7 +127,7 @@ replication_subscribe_f(va_list ap)
*/
struct ev_io read_ev;
read_ev.data = fiber();
- ev_io_init(&read_ev, (ev_io_cb) fiber_schedule,
+ ev_io_init(&read_ev, (ev_io_cb) fiber_schedule_cb,
relay->io.fd, EV_READ);
while (true) {
diff --git a/src/box/replication.h b/src/box/replication.h
index 46c7394d03ba2b090d992371f9996a25b6abd53f..d84c70c5443eccc3163cd50b89b97eea62b7875e 100644
--- a/src/box/replication.h
+++ b/src/box/replication.h
@@ -40,6 +40,7 @@ class Relay {
/* Request sync */
uint64_t sync;
struct recovery_state *r;
+ ev_tstamp wal_dir_rescan_delay;
Relay(int fd_arg, uint64_t sync_arg);
~Relay();
};
diff --git a/src/box/request.cc b/src/box/request.cc
index dd8d7eea598db4f4e4313ddd50f574124adbebad..479c1abcf47ffdcee703acb9e16884d39eb01643 100644
--- a/src/box/request.cc
+++ b/src/box/request.cc
@@ -172,7 +172,6 @@ execute_select(struct request *request, struct port *port)
void
request_create(struct request *request, uint32_t type)
{
-
memset(request, 0, sizeof(*request));
request->type = type;
}
diff --git a/src/box/tuple_update.cc b/src/box/tuple_update.cc
index df68bb3bbd196d484b1311f99f58ef0305bf4672..11cc4eb76dd6477a13d22d7c508c30e19b7a75dc 100644
--- a/src/box/tuple_update.cc
+++ b/src/box/tuple_update.cc
@@ -35,6 +35,7 @@
#include "salad/rope.h"
#include "error.h"
#include "msgpuck/msgpuck.h"
+#include "bit/int96.h"
/** UPDATE request implementation.
* UPDATE request is represented by a sequence of operations, each
@@ -42,13 +43,13 @@
* add or remove fields. Only one operation on the same field
* is allowed.
*
- * Supported field change operations are: SET, ADD, bitwise AND,
- * XOR and OR, SPLICE.
+ * Supported field change operations are: SET, ADD, SUBTRACT;
+ * bitwise AND, XOR and OR; SPLICE.
*
- * Supported tuple change operations are: SET (when SET field_no
- * == last_field_no + 1), DELETE, INSERT, PUSH and POP.
+ * Supported tuple change operations are: SET, DELETE, INSERT,
+ * PUSH and POP.
* If the number of fields in a tuple is altered by an operation,
- * field index of all following operation is evaluated against the
+ * field index of all following operations is evaluated against the
* new tuple.
*
* Despite the allowed complexity, a typical use case for UPDATE
@@ -84,7 +85,7 @@
* In particular, if a field is deleted by an operation,
* it disappears from the rope and all subsequent operations
* on this field number instead affect the field following the
- * one.
+ * deleted one.
*/
/** Update internal state */
@@ -104,8 +105,49 @@ struct op_set_arg {
const char *value;
};
-/** Argument of ADD, AND, XOR, OR operations. */
+/**
+ * MsgPack format code of an arithmetic argument or result.
+ * MsgPack codes are not used to simplify type calculation.
+ */
+enum arith_type {
+ AT_DOUBLE = 0, /* MP_DOUBLE */
+ AT_FLOAT = 1, /* MP_FLOAT */
+ AT_INT = 2 /* MP_INT/MP_UINT */
+};
+
+/**
+ * Argument (left and right) and result of ADD, AND, XOR, OR,
+ * SUBTRACT, MULTIPLY.
+ *
+ * To perform an arithmetic operation, update first loads
+ * left and right arguments into corresponding value objects,
+ * then performs arithmetics on types of arguments, thus
+ * calculating the type of the result, and then
+ * performs the requested operation according to the calculated
+ * type rules.
+ *
+ * The rules are as follows:
+ * - when one of the argument types is double, the result is
+ * double
+ * - when one of the argument types is float, the result is
+ * float
+ * - for integer arguments, the result type code depends on
+ * the range in which falls the result of the operation.
+ * If the result is in negative range, it's MP_INT, otherwise
+ * it's MP_UINT. If the result is out of bounds of (-2^63,
+ * 2^64), and exception is raised for overflow.
+ */
struct op_arith_arg {
+ enum arith_type type;
+ union {
+ double dbl;
+ float flt;
+ struct int96_num int96;
+ };
+};
+
+/** Argument of AND, XOR, OR operations. */
+struct op_bit_arg {
uint64_t val;
};
@@ -125,6 +167,7 @@ struct op_splice_arg {
union update_op_arg {
struct op_set_arg set;
struct op_arith_arg arith;
+ struct op_bit_arg bit;
struct op_splice_arg splice;
};
@@ -182,6 +225,7 @@ update_field_init(struct update_field *field,
field->tail_len = tail_len;
}
+/** Read a field index or any other integer field. */
static inline int64_t
mp_read_int(struct tuple_update *update, struct update_op *op,
const char **expr)
@@ -197,6 +241,85 @@ mp_read_int(struct tuple_update *update, struct update_op *op,
return field_no;
}
+static inline uint64_t
+mp_read_uint(struct tuple_update *update, struct update_op *op,
+ const char **expr)
+{
+ int64_t field_no;
+ if (mp_typeof(**expr) == MP_UINT)
+ field_no = mp_decode_uint(expr);
+ else
+ tnt_raise(ClientError, ER_ARG_TYPE, (char ) op->opcode,
+ update->index_base + op->field_no, "UINT");
+ return field_no;
+}
+
+/**
+ * Load an argument of an arithmetic operation either from tuple
+ * or from the UPDATE command.
+ */
+static inline struct op_arith_arg
+mp_read_arith_arg(struct tuple_update *update, struct update_op *op,
+ const char **expr)
+{
+ struct op_arith_arg result;
+ if (mp_typeof(**expr) == MP_UINT) {
+ result.type = AT_INT;
+ int96_set_unsigned(&result.int96, mp_decode_uint(expr));
+ } else if (mp_typeof(**expr) == MP_INT) {
+ result.type = AT_INT;
+ int96_set_signed(&result.int96, mp_decode_int(expr));
+ } else if (mp_typeof(**expr) == MP_DOUBLE) {
+ result.type = AT_DOUBLE;
+ result.dbl = mp_decode_double(expr);
+ } else if (mp_typeof(**expr) == MP_FLOAT) {
+ result.type = AT_FLOAT;
+ result.flt = mp_decode_float(expr);
+ } else {
+ tnt_raise(ClientError, ER_ARG_TYPE, (char ) op->opcode,
+ update->index_base + op->field_no, "NUMBER");
+ }
+ return result;
+}
+
+static inline double
+cast_arith_arg_to_double(struct op_arith_arg arg)
+{
+ if (arg.type == AT_DOUBLE) {
+ return arg.dbl;
+ } else if (arg.type == AT_FLOAT) {
+ return arg.flt;
+ } else {
+ assert(arg.type == AT_INT);
+ if (int96_is_uint64(&arg.int96)) {
+ return int96_extract_uint64(&arg.int96);
+ } else {
+ assert(int96_is_neg_int64(&arg.int96));
+ return int96_extract_neg_int64(&arg.int96);
+ }
+ }
+}
+
+/** Return the MsgPack size of an arithmetic operation result. */
+static inline uint32_t
+mp_sizeof_op_arith_arg(struct op_arith_arg arg)
+{
+ if (arg.type == AT_INT) {
+ if (int96_is_uint64(&arg.int96)) {
+ uint64_t val = int96_extract_uint64(&arg.int96);
+ return mp_sizeof_uint(val);
+ } else {
+ int64_t val = int96_extract_neg_int64(&arg.int96);
+ return mp_sizeof_int(val);
+ }
+ } else if (arg.type == AT_DOUBLE) {
+ return mp_sizeof_double(arg.dbl);
+ } else {
+ assert(arg.type == AT_FLOAT);
+ return mp_sizeof_float(arg.flt);
+ }
+}
+
static inline const char *
mp_read_str(struct tuple_update *update, struct update_op *op,
const char **expr, uint32_t *len)
@@ -284,33 +407,123 @@ do_op_delete(struct tuple_update *update, struct update_op *op,
rope_erase(update->rope, op->field_no);
}
+static inline struct op_arith_arg
+make_arith_operation(struct op_arith_arg arg1, struct op_arith_arg arg2,
+ char opcode, uint32_t err_fieldno)
+{
+ struct op_arith_arg result;
+
+ arith_type lowest_type = arg1.type;
+ if (arg1.type > arg2.type)
+ lowest_type = arg2.type;
+
+ if (lowest_type == AT_INT) {
+ result.type = AT_INT;
+ switch(opcode) {
+ case '+':
+ int96_add(&arg1.int96, &arg2.int96);
+ break;
+ case '-':
+ int96_invert(&arg2.int96);
+ int96_add(&arg1.int96, &arg2.int96);
+ break;
+ default:
+ assert(false); /* checked by update_read_ops */
+ break;
+ }
+ if (!int96_is_uint64(&arg1.int96) &&
+ !int96_is_neg_int64(&arg1.int96)) {
+ tnt_raise(ClientError,
+ ER_UPDATE_INTEGER_OVERFLOW,
+ opcode, err_fieldno);
+ }
+ return arg1;
+ } else {
+ /* At least one of operands is double or float */
+ double a = cast_arith_arg_to_double(arg1);
+ double b = cast_arith_arg_to_double(arg2);
+ double c;
+ switch(opcode) {
+ case '+': c = a + b; break;
+ case '-': c = a - b; break;
+ default:
+ tnt_raise(ClientError, ER_ARG_TYPE, (char ) opcode,
+ err_fieldno, "positive integer");
+ break;
+ }
+ if (lowest_type == AT_DOUBLE) {
+ /* result is DOUBLE */
+ result.type = AT_DOUBLE;
+ result.dbl = c;
+ } else {
+ /* result is FLOAT */
+ assert(lowest_type == AT_FLOAT);
+ result.type = AT_FLOAT;
+ result.flt = (float)c;
+ }
+ }
+ return result;
+}
+
static void
-do_op_arith(struct tuple_update *update, struct update_op *op,
- const char **expr)
+prepare_op_arith(struct tuple_update *update, struct update_op *op,
+ const char **expr, struct op_arith_arg *left)
{
op_check_field_no(update, op->field_no, rope_size(update->rope) - 1);
struct update_field *field = (struct update_field *)
rope_extract(update->rope, op->field_no);
-
- /* TODO: signed int & float support */
- struct op_arith_arg *arg = &op->arg.arith;
-
- arg->val = mp_read_int(update, op, expr);
if (field->op) {
tnt_raise(ClientError, ER_UPDATE_FIELD, update->index_base +
op->field_no, "double update of the same field");
}
field->op = op;
const char *old = field->old;
- uint64_t val = mp_read_int(update, op, &old);
+ *left = mp_read_arith_arg(update, op, &old);
+ op->arg.arith = mp_read_arith_arg(update, op, expr);
+}
+
+static void
+do_op_arith(struct tuple_update *update, struct update_op *op,
+ const char **expr)
+{
+ struct op_arith_arg left;
+ prepare_op_arith(update, op, expr, &left);
+ op->arg.arith = make_arith_operation(left, op->arg.arith, op->opcode,
+ update->index_base + op->field_no);
+ op->new_field_len = mp_sizeof_op_arith_arg(op->arg.arith);
+}
+
+static void
+do_op_bit(struct tuple_update *update, struct update_op *op,
+ const char **expr)
+{
+ op_check_field_no(update, op->field_no, rope_size(update->rope) - 1);
+ struct update_field *field = (struct update_field *)
+ rope_extract(update->rope, op->field_no);
+
+ struct op_bit_arg *arg = &op->arg.bit;
+ arg->val = mp_read_uint(update, op, expr);
+ if (field->op) {
+ tnt_raise(ClientError, ER_UPDATE_FIELD,
+ update->index_base + op->field_no,
+ "double update of the same field");
+ }
+ field->op = op;
+ const char *old = field->old;
+ uint64_t val = mp_read_uint(update, op, &old);
switch (op->opcode) {
- case '+': arg->val += val; break;
- case '&': arg->val &= val; break;
- case '^': arg->val ^= val; break;
- case '|': arg->val |= val; break;
- case '-': arg->val = val - arg->val; break;
- default: assert(false); /* checked by update_read_ops */
+ case '&':
+ arg->val &= val;
+ break;
+ case '^':
+ arg->val ^= val;
+ break;
+ case '|':
+ arg->val |= val;
+ break;
+ default:
+ assert(false); /* checked by update_read_ops */
}
op->new_field_len = mp_sizeof_uint(arg->val);
}
@@ -385,7 +598,26 @@ store_op_set(struct op_set_arg *arg, const char *in __attribute__((unused)),
}
static void
-store_op_arith(struct op_arith_arg *arg, const char *in __attribute__((unused)), char *out)
+store_op_arith(struct op_arith_arg *arg,
+ const char *in __attribute__((unused)), char *out)
+{
+ if (arg->type == AT_INT) {
+ if (int96_is_uint64(&arg->int96)) {
+ mp_encode_uint(out, int96_extract_uint64(&arg->int96));
+ } else {
+ assert(int96_is_neg_int64(&arg->int96));
+ mp_encode_int(out, int96_extract_neg_int64(&arg->int96));
+ }
+ } else if (arg->type == AT_DOUBLE) {
+ mp_encode_double(out, arg->dbl);
+ } else {
+ assert(arg->type == AT_FLOAT);
+ mp_encode_float(out, arg->flt);
+ }
+}
+
+static void
+store_op_bit(struct op_bit_arg *arg, const char *in __attribute__((unused)), char *out)
{
mp_encode_uint(out, arg->val);
}
@@ -420,6 +652,8 @@ static const struct update_op_meta op_insert =
{ do_op_insert, (store_op_func) store_op_insert, 3 };
static const struct update_op_meta op_arith =
{ do_op_arith, (store_op_func) store_op_arith, 3 };
+static const struct update_op_meta op_bit =
+ { do_op_bit, (store_op_func) store_op_bit, 3 };
static const struct update_op_meta op_splice =
{ do_op_splice, (store_op_func) store_op_splice, 5 };
static const struct update_op_meta op_delete =
@@ -590,10 +824,12 @@ update_read_ops(struct tuple_update *update, const char *expr,
break;
case '+':
case '-':
+ op->meta = &op_arith;
+ break;
case '&':
case '|':
case '^':
- op->meta = &op_arith;
+ op->meta = &op_bit;
break;
case ':':
op->meta = &op_splice;
diff --git a/src/box/txn.h b/src/box/txn.h
index f2158262e07e61cdebbd88da534d993b62067033..9ae74462dff022b026ceae21a9e80b58a18ad072 100644
--- a/src/box/txn.h
+++ b/src/box/txn.h
@@ -71,7 +71,10 @@ struct txn {
Engine *engine;
/** Engine-specific transaction data */
void *engine_tx;
- /** Triggers on fiber yield and stop to abort transaction for in-memory engine */
+ /**
+ * Triggers on fiber yield and stop to abort transaction
+ * for in-memory engine.
+ */
struct trigger fiber_on_yield, fiber_on_stop;
};
diff --git a/src/box/xlog.cc b/src/box/xlog.cc
index b46e350791b3f697fa883f1e606ef99cca0ba967..b1b513eceea701a67f3cc4acfe874a805415e549 100644
--- a/src/box/xlog.cc
+++ b/src/box/xlog.cc
@@ -566,32 +566,35 @@ xlog_cursor_next(struct xlog_cursor *i, struct xrow_header *row)
return 0;
eof:
/*
- * The only two cases of fully read file:
- * 1. eof_marker is present and it is the last record in file
- * 2. eof_marker is missing but there is no unread data in file
+ * According to POSIX, if a partial element is read, value
+ * of the file position indicator for the stream is
+ * unspecified.
+ *
+ * Thus don't trust the current file position, seek to the
+ * last good position first.
+ *
+ * The only case of a fully read file is when eof_marker
+ * is present and it is the last record in the file. If
+ * eof_marker is missing, the caller must make the
+ * decision whether to switch to the next file or not.
*/
- if (ftello(l->f) == i->good_offset + sizeof(eof_marker)) {
- fseeko(l->f, i->good_offset, SEEK_SET);
- if (fread(&magic, sizeof(magic), 1, l->f) != 1) {
-
- say_error("can't read eof marker");
- } else if (magic == eof_marker) {
+ fseeko(l->f, i->good_offset, SEEK_SET);
+ if (fread(&magic, sizeof(magic), 1, l->f) == 1) {
+ if (magic == eof_marker) {
i->good_offset = ftello(l->f);
i->eof_read = true;
- } else if (magic != row_marker) {
- say_error("eof marker is corrupt: %lu",
- (unsigned long) magic);
- } else {
+ } else if (magic == row_marker) {
/*
* Row marker at the end of a file: a sign
* of a corrupt log file in case of
* recovery, but OK in case we're in local
* hot standby or replication relay mode
* (i.e. data is being written to the
- * file. Don't pollute the log, the
- * condition is taken care of up the
- * stack.
+ * file.
*/
+ } else {
+ say_error("EOF marker is corrupt: %lu",
+ (unsigned long) magic);
}
}
/* No more rows. */
diff --git a/src/box/xlog.h b/src/box/xlog.h
index 88629c0962e210904d618dfd57b467d1e05e294d..46d3d6c7755fc60c9c6359a4062882e39be1aba7 100644
--- a/src/box/xlog.h
+++ b/src/box/xlog.h
@@ -175,8 +175,6 @@ struct xlog {
* appended to the file.
*/
size_t rows;
- /** Used in local hot standby. */
- int retry;
/** Log file name. */
char filename[PATH_MAX + 1];
/** Whether this file has .inprogress suffix. */
diff --git a/src/coio.cc b/src/coio.cc
index cc3831914d5d2b44c3ff4bd72dec20009043cd3d..c8713e6a306f35e14adf361a0734b4211f4aa2f6 100644
--- a/src/coio.cc
+++ b/src/coio.cc
@@ -53,25 +53,10 @@ coio_init(struct ev_io *coio)
{
/* Prepare for ev events. */
coio->data = fiber();
- ev_init(coio, (ev_io_cb) fiber_schedule);
+ ev_init(coio, (ev_io_cb) fiber_schedule_cb);
coio->fd = -1;
}
-static inline void
-coio_fiber_yield(struct ev_io *coio)
-{
- /**
- * We may create an event in one fiber, but wait for it
- * in another. Hence we set the coroutine right before the
- * yield.
- */
- coio->data = fiber();
- fiber_yield();
-#ifdef DEBUG
- coio->data = NULL;
-#endif
-}
-
static inline bool
coio_fiber_yield_timeout(struct ev_io *coio, ev_tstamp delay)
{
@@ -686,7 +671,7 @@ coio_service_start(struct evio_service *service, const char *uri)
void
coio_stat_init(ev_stat *stat, const char *path)
{
- ev_stat_init(stat, (ev_stat_cb) fiber_schedule, path, 0.0);
+ ev_stat_init(stat, (ev_stat_cb) fiber_schedule_cb, path, 0.0);
}
void
@@ -712,7 +697,7 @@ coio_waitpid(pid_t pid)
{
assert(cord_is_main());
ev_child cw;
- ev_init(&cw, (ev_child_cb) fiber_schedule);
+ ev_init(&cw, (ev_child_cb) fiber_schedule_cb);
ev_child_set(&cw, pid, 0);
cw.data = fiber();
ev_child_start(loop(), &cw);
diff --git a/src/fiber.cc b/src/fiber.cc
index 463a1b52cadb3af14147d81442ffc7cb16c9cf40..111aaca7da0c9b4f106119fa603df2b6810263cd 100644
--- a/src/fiber.cc
+++ b/src/fiber.cc
@@ -102,8 +102,16 @@ fiber_wakeup(struct fiber *f)
/** Remove the fiber from whatever wait list it is on. */
rlist_del(&f->state);
struct cord *cord = cord();
- if (rlist_empty(&cord->ready))
+ if (rlist_empty(&cord->ready)) {
+ /*
+ * ev_feed_event() is possibly faster,
+ * but EV_CUSTOM event gets scheduled in the
+ * same event loop iteration, which can
+ * produce unfair scheduling, (see the case of
+ * fiber_sleep(0))
+ */
ev_feed_event(cord->loop, &cord->wakeup_event, EV_CUSTOM);
+ }
rlist_move_tail_entry(&cord->ready, f, state);
}
@@ -203,21 +211,15 @@ void
fiber_join(struct fiber *fiber)
{
assert(fiber->flags & FIBER_IS_JOINABLE);
- if (fiber->flags & FIBER_IS_DEAD) {
- /* The fiber is already dead. */
- fiber_recycle(fiber);
- } else {
+
+ if (! (fiber->flags & FIBER_IS_DEAD)) {
rlist_add_tail_entry(&fiber->wake, fiber(), state);
fiber_yield();
- /* @todo: make this branch async-cancel-safe */
- assert(! (fiber->flags & FIBER_IS_DEAD));
- /*
- * Let the fiber recycle.
- * This can't be done here since there may be other
- * waiters in fiber->wake list, which must run first.
- */
- fiber_set_joinable(fiber, false);
}
+ assert(fiber->flags & FIBER_IS_DEAD);
+ /* The fiber is already dead. */
+ fiber_recycle(fiber);
+
Exception::move(&fiber->exception, &fiber()->exception);
if (fiber()->exception &&
typeid(*fiber()->exception) != typeid(FiberCancelException)) {
@@ -291,12 +293,16 @@ fiber_yield_timeout(ev_tstamp delay)
void
fiber_sleep(ev_tstamp delay)
{
+ /*
+ * We don't use fiber_wakeup() here to ensure there is
+ * no infinite wakeup loop in case of fiber_sleep(0).
+ */
fiber_yield_timeout(delay);
fiber_testcancel();
}
void
-fiber_schedule(ev_loop * /* loop */, ev_watcher *watcher, int /* revents */)
+fiber_schedule_cb(ev_loop * /* loop */, ev_watcher *watcher, int /* revents */)
{
assert(fiber() == &cord()->sched);
fiber_call((struct fiber *) watcher->data);
@@ -305,9 +311,13 @@ fiber_schedule(ev_loop * /* loop */, ev_watcher *watcher, int /* revents */)
static inline void
fiber_schedule_list(struct rlist *list)
{
- while (! rlist_empty(list)) {
+ /** Don't schedule both lists at the same time. */
+ struct rlist copy;
+ rlist_create(©);
+ rlist_swap(list, ©);
+ while (! rlist_empty(©)) {
struct fiber *f;
- f = rlist_shift_entry(list, struct fiber, state);
+ f = rlist_shift_entry(©, struct fiber, state);
fiber_call(f);
}
}
@@ -407,25 +417,17 @@ fiber_loop(void *data __attribute__((unused)))
fiber_name(fiber));
panic("fiber `%s': exiting", fiber_name(fiber));
}
- fiber_schedule_list(&fiber->wake);
- /**
- * By convention, these triggers must not throw.
- * Call triggers after scheduling, since an
- * on_stop trigger of the first fiber may
- * break the event loop.
- */
+ fiber->flags |= FIBER_IS_DEAD;
+ while (! rlist_empty(&fiber->wake)) {
+ struct fiber *f;
+ f = rlist_shift_entry(&fiber->wake, struct fiber,
+ state);
+ fiber_wakeup(f);
+ }
if (! rlist_empty(&fiber->on_stop))
trigger_run(&fiber->on_stop, fiber);
- if (fiber->flags & FIBER_IS_JOINABLE) {
- /*
- * The fiber needs to be joined,
- * and the joiner has not shown up yet,
- * wait.
- */
- fiber->flags |= FIBER_IS_DEAD;
- } else {
+ if (! (fiber->flags & FIBER_IS_JOINABLE))
fiber_recycle(fiber);
- }
fiber_yield(); /* give control back to scheduler */
}
}
diff --git a/src/fiber.h b/src/fiber.h
index 7028b4f6ad49561b14d5b3313338230acad3b1ba..1ee9fc8faf690256d382124cb13d2676db609e26 100644
--- a/src/fiber.h
+++ b/src/fiber.h
@@ -351,7 +351,7 @@ void
fiber_sleep(ev_tstamp s);
void
-fiber_schedule(ev_loop * /* loop */, ev_watcher *watcher, int revents);
+fiber_schedule_cb(ev_loop * /* loop */, ev_watcher *watcher, int revents);
/**
* \brief Associate \a value with \a key in fiber local storage
diff --git a/src/fiob.c b/src/fiob.c
index d05c1e98464229a331cc22c07c10bd19811cfd37..b7840bf44023575a6c864823fc05e90581a45ecc 100644
--- a/src/fiob.c
+++ b/src/fiob.c
@@ -56,7 +56,7 @@ fiob_ceil(off_t off)
#ifdef HAVE_FUNOPEN
static int
-fiob_read(void *cookie, char *buf, int len)
+fiob_read(void *cookie, char *buf, int count)
#else
static ssize_t
fiob_read(void *cookie, char *buf, size_t count)
diff --git a/src/lib/bit/int96.h b/src/lib/bit/int96.h
new file mode 100644
index 0000000000000000000000000000000000000000..39b754ae79f168bc78a7b4add123814a362afe0a
--- /dev/null
+++ b/src/lib/bit/int96.h
@@ -0,0 +1,163 @@
+#ifndef TARANTOOL_LIB_BIT_INT96_H_INCLUDED
+#define TARANTOOL_LIB_BIT_INT96_H_INCLUDED
+/*
+ * Redistribution and use in source and binary forms, with or
+ * without modification, are permitted provided that the following
+ * conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above
+ * copyright notice, this list of conditions and the
+ * following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following
+ * disclaimer in the documentation and/or other materials
+ * provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY <COPYRIGHT HOLDER> ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
+ * <COPYRIGHT HOLDER> OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+ * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+ * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
+ * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ */
+
+#include <inttypes.h>
+#include <assert.h>
+
+/**
+ * 96-bit signed integer.
+ * 1)Negative integer is stored as 96-bit two's complement
+ * 2)Stores an integer modulo n, where n = 2**96
+ * Actually (1) == (2), as the wave-particle duality.
+ * Designed for storing integers in range [INT64_MIN, UINT64_MAX],
+ * and detecting overflow (out of range [INT64_MIN, UINT64_MAX])
+ * after operations (addition, subtraction) on them.
+ * The base fact is when two uint64_t or int64_t values
+ * are converted to int96, and then added or subtracted, the
+ * int96 arithmetics cannot overflow. Actually you need at least
+ * billions of adding UINT64_MAX or INT64_MIN to make it overflow.
+ * Addition is implemented directly;
+ * For subtraction use addition of inverted number.
+ */
+
+/**
+ * struct 96-bit signed integer
+ */
+struct int96_num {
+ /* most significant 64 bits */
+ uint64_t high64;
+ /* least significant order 32 bits */
+ /* (high dword - zero bits) */
+ uint64_t low32;
+};
+
+/**
+ * Assign to unsigned 64-bit
+ */
+static inline void
+int96_set_unsigned(struct int96_num *num, uint64_t val)
+{
+ const uint64_t mask = 0xFFFFFFFFu;
+ num->high64 = val >> 32;
+ num->low32 = val & mask;
+}
+
+/**
+ * Assign to signed 64-bit
+ */
+static inline void
+int96_set_signed(struct int96_num *num, int64_t val)
+{
+ const uint64_t mask = 0xFFFFFFFFu;
+ num->high64 = (uint64_t)(val >> 32);
+ num->low32 = ((uint64_t)val) & mask;
+}
+
+/**
+ * Invert number (assign a to -a)
+ */
+static inline void
+int96_invert(struct int96_num *num)
+{
+ const uint64_t mask = 0xFFFFFFFFu;
+ assert(!(num->low32 & ~mask));
+ num->high64 = ~num->high64;
+ num->low32 = (~num->low32) & mask;
+ num->low32++;
+ num->high64 += num->low32 >> 32;
+ num->low32 &= mask;
+}
+
+/**
+ * Add to number 'to' another number 'what'
+ */
+static inline void
+int96_add(struct int96_num *to, const struct int96_num *what)
+{
+ const uint64_t mask = 0xFFFFFFFFu;
+ assert(!(to->low32 & ~mask));
+ assert(!(what->low32 & ~mask));
+ to->low32 += what->low32;
+ to->high64 += to->low32 >> 32;
+ to->high64 += what->high64;
+ to->low32 &= mask;
+}
+
+/**
+ * Get lowers 64 bit of a number (that is C cast to uint64_t)
+ */
+static inline uint64_t
+int96_get_low64bit(const struct int96_num *num)
+{
+ return num->low32 | (num->high64 << 32);
+}
+
+/**
+ * Returns true if a number fits [0, UINT64_MAX] range
+ */
+static inline bool
+int96_is_uint64(const struct int96_num *num)
+{
+ return (num->high64 >> 32) == 0;
+}
+
+/**
+ * Get number as uint64_t,
+ * the number is expected to be valid range (assert)
+ */
+static inline uint64_t
+int96_extract_uint64(const struct int96_num *num)
+{
+ assert(int96_is_uint64(num));
+ return int96_get_low64bit(num);
+}
+
+/**
+ * Returns true if a number fits [INT64_MIN, 0) range
+ */
+static inline bool
+int96_is_neg_int64(const struct int96_num *num)
+{
+ return (num->high64 >> 31) == 0x1FFFFFFFFull;
+}
+
+/**
+ * Get number as negative int64_t,
+ * the number is expected to be valid range (assert)
+ */
+static inline int64_t
+int96_extract_neg_int64(const struct int96_num *num)
+{
+ assert(int96_is_neg_int64(num));
+ return (int64_t)int96_get_low64bit(num);
+}
+
+#endif /* #ifndef TARANTOOL_LIB_BIT_INT96_H_INCLUDED */
diff --git a/src/lib/salad/guava.c b/src/lib/salad/guava.c
index 84fc5cbfa2f91e7a6a1219513ca7af6f5c2e4d59..86081b206e42b91bce40c2b486492989d4a3436f 100644
--- a/src/lib/salad/guava.c
+++ b/src/lib/salad/guava.c
@@ -31,6 +31,12 @@
#include <stdint.h>
+/**
+ * This is implements a consistent hashing algorithm
+ * A Fast, Minimal Memory, Consistent Hash Algorithm
+ * John Lamping, Eric Veach
+ */
+
static const int64_t K = 2862933555777941757;
static const double D = 0x1.0p31;
diff --git a/src/lua/bsdsocket.cc b/src/lua/bsdsocket.cc
index b6186c4feb0f410b387e8e394d9565b87e88a4a4..45abbe5a37b171fc65265585b9ae1ec8c6a859cb 100644
--- a/src/lua/bsdsocket.cc
+++ b/src/lua/bsdsocket.cc
@@ -812,6 +812,8 @@ lbox_bsdsocket_accept(struct lua_State *L)
int sc = accept(fh, (struct sockaddr*)&fa, &len);
if (sc < 0) {
+ if (errno != EAGAIN && errno != EWOULDBLOCK && errno != EINTR)
+ say_syserror("accept(%d)", fh);
lua_pushnil(L);
return 1;
}
diff --git a/src/lua/bsdsocket.lua b/src/lua/bsdsocket.lua
index 82c1354a441cf627a05c4781d405b8836fabd02d..793ae416bcb526e79345d27bdcca637f7ca7497f 100644
--- a/src/lua/bsdsocket.lua
+++ b/src/lua/bsdsocket.lua
@@ -1,6 +1,8 @@
-- bsdsocket.lua (internal file)
local TIMEOUT_INFINITY = 500 * 365 * 86400
+local LIMIT_INFINITY = 4294967295
+local READAHEAD = 16380
local ffi = require('ffi')
local boxerrno = require('errno')
@@ -62,7 +64,14 @@ end
local socket_t = ffi.typeof('struct socket');
local function socket_cdata_gc(socket)
- ffi.C.close(socket.fd)
+ if socket.fd < 0 then
+ log.error("socket: attempt to double close on gc")
+ return
+ end
+ if ffi.C.close(socket.fd) ~= 0 then
+ log.error("socket: failed to close fd=%d on gc: %s", socket.fd,
+ boxerrno.strerror())
+ end
end
local function check_socket(self)
@@ -70,6 +79,9 @@ local function check_socket(self)
if not ffi.istype(socket_t, socket) then
error('Usage: socket:method()');
end
+ if socket.fd < 0 then
+ error("attempt to use closed socket")
+ end
return socket.fd
end
@@ -83,7 +95,7 @@ local function bless_socket(fd)
return nil
end
- local socket = ffi.new(socket_t, fd);
+ local socket = ffi.new(socket_t, { fd = fd });
ffi.gc(socket, socket_cdata_gc)
return setmetatable({ socket = socket }, socket_mt)
end
@@ -167,7 +179,7 @@ end
socket_methods.sysread = function(self, size)
local fd = check_socket(self)
- size = size or 4096
+ size = size or READAHEAD
self._errno = nil
local buf = ffi.new('char[?]', size)
local res = ffi.C.read(fd, buf, size)
@@ -295,11 +307,13 @@ socket_methods.close = function(self)
end
self._errno = nil
- if ffi.C.close(fd) < 0 then
+ local r = ffi.C.close(fd)
+ self.socket.fd = -1
+ ffi.gc(self.socket, nil)
+ if r ~= 0 then
self._errno = boxerrno()
return false
end
- ffi.gc(self.socket, nil)
return true
end
@@ -532,72 +546,86 @@ local errno_is_fatal = {
[boxerrno.ENOTSOCK] = true;
}
-local function readchunk(self, size, timeout)
+local function readchunk(self, limit, timeout)
if self.rbuf == nil then
self.rbuf = ''
+ self.rpos = 1
+ self.rlen = 0
end
- if string.len(self.rbuf) >= size then
+ if self.rlen >= limit then
self._errno = nil
- local data = string.sub(self.rbuf, 1, size)
- self.rbuf = string.sub(self.rbuf, size + 1)
+ local data = string.sub(self.rbuf, self.rpos, self.rpos - 1 + limit)
+ self.rlen = self.rlen - limit
+ self.rpos = self.rpos + limit
return data
end
- while timeout > 0 do
+ while true do
local started = fiber.time()
- if not self:readable(timeout) then
- return nil
+ local to_read
+ if limit ~= LIMIT_INFINITY and limit > READAHEAD then
+ to_read = limit - self.rlen
end
-
- timeout = timeout - ( fiber.time() - started )
-
- local data = self:sysread()
+ local data = self:sysread(to_read)
if data ~= nil then
- self.rbuf = self.rbuf .. data
- if string.len(self.rbuf) >= size then
- data = string.sub(self.rbuf, 1, size)
- self.rbuf = string.sub(self.rbuf, size + 1)
- return data
- end
-
+ self.rbuf = string.sub(self.rbuf, self.rpos) .. data
+ self.rpos = 1
+ self.rlen = string.len(self.rbuf)
if string.len(data) == 0 then -- eof
- data = self.rbuf
- self.rbuf = nil
- return data
+ limit = self.rlen
+ end
+ if self.rlen >= limit then
+ data = string.sub(self.rbuf, self.rpos, self.rpos - 1 + limit)
+ self.rlen = self.rlen - limit
+ self.rpos = self.rpos + limit
+ return data
end
elseif not errno_is_transient[self:errno()] then
self._errno = boxerrno()
return nil
end
+
+ if not self:readable(timeout) then
+ return nil
+ end
+ if timeout <= 0 then
+ break
+ end
+ timeout = timeout - ( fiber.time() - started )
end
self._errno = boxerrno.ETIMEDOUT
return nil
end
local function readline_check(self, eols, limit)
- local rbuf = self.rbuf
- if string.len(rbuf) == 0 then
+ if limit == 0 then
+ return ''
+ end
+ if self.rlen == 0 then
return nil
end
local shortest
for i, eol in ipairs(eols) do
- local data = string.match(rbuf, "^(.-" .. eol .. ")")
+ local data = string.match(self.rbuf, "^(.-" .. eol .. ")", self.rpos)
if data ~= nil then
if string.len(data) > limit then
data = string.sub(data, 1, limit)
end
- if shortest == nil then
- shortest = data
- elseif #shortest > #data then
+ if shortest == nil or string.len(shortest) > string.len(data) then
shortest = data
end
end
end
- if shortest == nil and #rbuf >= limit then
- return string.sub(rbuf, 1, limit)
+ if shortest == nil and self.rlen >= limit then
+ shortest = string.sub(self.rbuf, self.rpos, self.rpos - 1 + limit)
+ end
+ if shortest ~= nil then
+ local len = string.len(shortest)
+ self.rpos = self.rpos + len
+ self.rlen = self.rlen - len
end
return shortest
end
@@ -605,15 +633,13 @@ end
local function readline(self, limit, eol, timeout)
if self.rbuf == nil then
self.rbuf = ''
+ self.rpos = 1
+ self.rlen = 0
end
self._errno = nil
- if limit == 0 then
- return ''
- end
local data = readline_check(self, eol, limit)
if data ~= nil then
- self.rbuf = string.sub(self.rbuf, string.len(data) + 1)
return data
end
@@ -628,44 +654,38 @@ local function readline(self, limit, eol, timeout)
timeout = timeout - ( fiber.time() - started )
- local data = self:sysread()
+ local to_read
+ if limit ~= LIMIT_INFINITY and limit > READAHEAD then
+ to_read = limit - self.rlen
+ end
+ local data = self:sysread(to_read)
if data ~= nil then
- self.rbuf = self.rbuf .. data
-
- -- eof
- if string.len(data) == 0 then
- data = self.rbuf
- self.rbuf = nil
- return data
+ self.rbuf = string.sub(self.rbuf, self.rpos) .. data
+ self.rpos = 1
+ self.rlen = string.len(self.rbuf)
+ if string.len(data) == 0 then -- eof
+ limit = self.rlen
end
-
data = readline_check(self, eol, limit)
if data ~= nil then
- self.rbuf = string.sub(self.rbuf, string.len(data) + 1)
return data
end
- -- limit
- if string.len(self.rbuf) >= limit then
- data = string.sub(self.rbuf, 1, limit)
- self.rbuf = string.sub(self.rbuf, limit + 1)
- return data
- end
-
elseif not errno_is_transient[self:errno()] then
self._errno = boxerrno()
return nil
end
end
+ return nil
end
socket_methods.read = function(self, opts, timeout)
check_socket(self)
- timeout = timeout and tonumber(timeout) or TIMEOUT_INFINITY
+ timeout = timeout or TIMEOUT_INFINITY
if type(opts) == 'number' then
return readchunk(self, opts, timeout)
elseif type(opts) == 'string' then
- return readline(self, 4294967295, { opts }, timeout)
+ return readline(self, LIMIT_INFINITY, { opts }, timeout)
elseif type(opts) == 'table' then
local chunk = opts.chunk or opts.size or 4294967295
local delimiter = opts.delimiter or opts.line
@@ -687,14 +707,13 @@ socket_methods.write = function(self, octets, timeout)
end
local started = fiber.time()
- while timeout > 0 and self:writable(timeout) do
- timeout = timeout - ( fiber.time() - started )
-
+ while true do
local written = self:syswrite(octets)
if written == nil then
if not errno_is_transient[self:errno()] then
return false
end
+ written = 0
end
if written == string.len(octets) then
@@ -703,6 +722,10 @@ socket_methods.write = function(self, octets, timeout)
if written > 0 then
octets = string.sub(octets, written + 1)
end
+ timeout = timeout - (fiber.time() - started)
+ if timeout <= 0 or not self:writable(timeout) then
+ break
+ end
end
end
@@ -989,6 +1012,7 @@ end
local function tcp_server_handler(server, sc, from)
fiber.name(sprintf("%s/%s:%s", server.name, from.host, from.port))
server.handler(sc, from)
+ sc:shutdown()
sc:close()
end
@@ -1000,7 +1024,7 @@ local function tcp_server_loop(server, s, addr)
if sc == nil then
local errno = s:errno()
if not errno_is_transient[errno] then
- log.error('accept() failed: '..s:error())
+ log.error('accept(%s) failed: %s', tostring(s), s:error())
end
if errno_is_fatal[errno] then
break
diff --git a/src/lua/console.lua b/src/lua/console.lua
index 24165563190a7aaeaae7edb0ac0bb5775e5f7d1f..83b981ddbcf000b6bc02b68ae924d59366242388 100644
--- a/src/lua/console.lua
+++ b/src/lua/console.lua
@@ -163,9 +163,7 @@ local function client_print(self, output)
return
elseif not output then
-- disconnect peer
- self.client:shutdown()
- self.client:close()
- self.client = nil
+ self.client = nil -- socket will be closed by tcp_server() function
self.running = nil
return
end
diff --git a/src/lua/fiber.cc b/src/lua/fiber.cc
index e304fcb8915110816fa59e2a2eb715a6230744e0..491630c5e3fb92c70e7be3aca039e50769339f04 100644
--- a/src/lua/fiber.cc
+++ b/src/lua/fiber.cc
@@ -42,7 +42,7 @@ extern "C" {
* }}}
*/
-/* {{{ box.fiber Lua library: access to Tarantool fibers
+/* {{{ fiber Lua library: access to Tarantool fibers
*
* Each fiber can be running, suspended or dead.
* When a fiber is created (fiber.create()) it's
diff --git a/src/lua/fio.cc b/src/lua/fio.cc
index 721c68af8af0c3e8419c31bcdadadddf6a82d4ee..28507687681f398f3c272a02a6619130d19cc12a 100644
--- a/src/lua/fio.cc
+++ b/src/lua/fio.cc
@@ -26,7 +26,6 @@
* THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*/
-#define _POSIX_SOURCE
#include "lua/fio.h"
#include <sys/types.h>
#include <sys/stat.h>
diff --git a/src/lua/init.cc b/src/lua/init.cc
index 8f418ce73b1b66f7d2c01de67493247f2f359feb..aa1b11cc6680ffc3f0f66e65319d7acf5a1579d5 100644
--- a/src/lua/init.cc
+++ b/src/lua/init.cc
@@ -79,7 +79,7 @@ extern char uuid_lua[],
uri_lua[],
bsdsocket_lua[],
console_lua[],
- box_net_box_lua[],
+ net_box_lua[],
help_lua[],
help_en_US_lua[],
tap_lua[],
@@ -96,7 +96,7 @@ static const char *lua_modules[] = {
"uri", uri_lua,
"fio", fio_lua,
"socket", bsdsocket_lua,
- "net.box", box_net_box_lua,
+ "net.box", net_box_lua,
"console", console_lua,
"tap", tap_lua,
"help.en_US", help_en_US_lua,
@@ -330,12 +330,14 @@ tarantool_lua_init(const char *tarantool_bin, int argc, char **argv)
luaopen_json(L);
lua_pop(L, 1);
+#if defined(HAVE_GNU_READLINE)
/*
* Disable libreadline signals handlers. All signals are handled in
* main thread by libev watchers.
*/
rl_catch_signals = 0;
rl_catch_sigwinch = 0;
+#endif
static const struct luaL_reg consolelib[] = {
{"readline", tarantool_console_readline},
{"add_history", tarantool_console_add_history},
diff --git a/src/lua/ipc.cc b/src/lua/ipc.cc
index 40fade0ccc8e0f85d2f10c23ef90df930a7a8845..9b4470c32f666c7fef6af0f5b5bd83d771b18449 100644
--- a/src/lua/ipc.cc
+++ b/src/lua/ipc.cc
@@ -39,7 +39,7 @@ extern "C" {
#include <ipc.h>
#include "lua/utils.h"
-static const char channel_lib[] = "box.fiber.channel";
+static const char channel_lib[] = "fiber.channel";
#define BROADCAST_MASK (((size_t)1) << (CHAR_BIT * sizeof(size_t) - 1))
@@ -60,7 +60,7 @@ lbox_ipc_channel(struct lua_State *L)
}
struct ipc_channel *ch = ipc_channel_new(size);
if (!ch)
- luaL_error(L, "box.channel: Not enough memory");
+ luaL_error(L, "fiber.channel: Not enough memory");
void **ptr = (void **) lua_newuserdata(L, sizeof(void *));
luaL_getmetatable(L, channel_lib);
diff --git a/src/lua/msgpack.cc b/src/lua/msgpack.cc
index 21a9963e3aaab2ae2f68942f7b72aef23ebec1e1..c1b842dde66ce6005d7bf1e960506e92e71a56f1 100644
--- a/src/lua/msgpack.cc
+++ b/src/lua/msgpack.cc
@@ -331,25 +331,25 @@ luamp_decode(struct lua_State *L, struct luaL_serializer *cfg,
{
uint32_t size = mp_decode_array(data);
lua_createtable(L, size, 0);
- if (cfg->decode_save_metatables)
- luaL_setarrayhint(L, -1);
for (uint32_t i = 0; i < size; i++) {
luamp_decode(L, cfg, data);
lua_rawseti(L, -2, i + 1);
}
+ if (cfg->decode_save_metatables)
+ luaL_setarrayhint(L, -1);
return;
}
case MP_MAP:
{
uint32_t size = mp_decode_map(data);
lua_createtable(L, 0, size);
- if (cfg->decode_save_metatables)
- luaL_setmaphint(L, -1);
for (uint32_t i = 0; i < size; i++) {
luamp_decode(L, cfg, data);
luamp_decode(L, cfg, data);
lua_settable(L, -3);
}
+ if (cfg->decode_save_metatables)
+ luaL_setmaphint(L, -1);
return;
}
case MP_EXT:
diff --git a/src/lua/msgpackffi.lua b/src/lua/msgpackffi.lua
index d63d2905126731e6067414ec986a79535bb703aa..d7fcebd69e81626b7c7d4e949f9e335c1934396f 100644
--- a/src/lua/msgpackffi.lua
+++ b/src/lua/msgpackffi.lua
@@ -2,9 +2,8 @@
local ffi = require('ffi')
local builtin = ffi.C
-
+local msgpack = require('msgpack') -- .NULL, .array_mt, .map_mt, .cfg
local MAXNESTING = 16
-local NULL = ffi.cast('void *', 0)
local int8_ptr_t = ffi.typeof('int8_t *')
local uint8_ptr_t = ffi.typeof('uint8_t *')
local uint16_ptr_t = ffi.typeof('uint16_t *')
@@ -289,9 +288,6 @@ on_encode(ffi.typeof('double'), encode_double)
-- Decoder
--------------------------------------------------------------------------------
-local array_mt = { __serialize = 'seq' }
-local map_mt = { __serialize = 'map' }
-
local decode_r
local function decode_u8(data)
@@ -370,7 +366,10 @@ local function decode_array(data, size)
for i=1,size,1 do
table.insert(arr, decode_r(data))
end
- return setmetatable(arr, array_mt)
+ if not msgpack.cfg.decode_save_metatables then
+ return arr
+ end
+ return setmetatable(arr, msgpack.array_mt)
end
local function decode_map(data, size)
@@ -382,7 +381,10 @@ local function decode_map(data, size)
local val = decode_r(data);
map[key] = val
end
- return setmetatable(map, map_mt)
+ if not msgpack.cfg.decode_save_metatables then
+ return map
+ end
+ return setmetatable(map, msgpack.map_mt)
end
local decoder_hint = {
@@ -437,7 +439,7 @@ decode_r = function(data)
elseif c >= 0xe0 then
return ffi.cast('signed char',c)
elseif c == 0xc0 then
- return NULL
+ return msgpack.NULL
elseif c == 0xc2 then
return false
elseif c == 0xc3 then
@@ -515,7 +517,9 @@ end
--------------------------------------------------------------------------------
return {
- NULL = NULL;
+ NULL = msgpack.NULL;
+ array_mt = msgpack.array_mt;
+ map_mt = msgpack.map_mt;
encode = encode;
on_encode = on_encode;
decode_unchecked = decode_unchecked;
diff --git a/src/lua/box_net_box.lua b/src/lua/net_box.lua
similarity index 86%
rename from src/lua/box_net_box.lua
rename to src/lua/net_box.lua
index 2613825f4b2e9e3bb1dda49ddaa8cf2ae426f580..f205851f90dea52286857049844d9c96883969b2 100644
--- a/src/lua/box_net_box.lua
+++ b/src/lua/net_box.lua
@@ -345,6 +345,11 @@ local function index_metatable(self)
}
end
+local errno_is_transient = {
+ [errno.EAGAIN] = true;
+ [errno.EWOULDBLOCK] = true;
+ [errno.EINTR] = true;
+}
local remote = {}
@@ -412,12 +417,15 @@ local remote_methods = {
self.is_run = true
self.state = 'init'
+ self.wbuf = {}
+ self.rbuf = ''
+ self.rpos = 1
+ self.rlen = 0
self.ch = { sync = {}, fid = {} }
self.wait = { state = {} }
self.timeouts = {}
-
fiber.create(function() self:_connect_worker() end)
fiber.create(function() self:_read_worker() end)
fiber.create(function() self:_write_worker() end)
@@ -512,17 +520,11 @@ local remote_methods = {
end,
is_connected = function(self)
- if self.state == 'active' then
- return true
- end
- if self.state == 'activew' then
- return true
- end
- return false
+ return self.state == 'active' or self.state == 'activew'
end,
wait_connected = function(self, timeout)
- return self:_wait_state({ 'active', 'activew', 'closed' }, timeout)
+ return self:_wait_state(self._request_states, timeout)
end,
timeout = function(self, timeout)
@@ -586,13 +588,15 @@ local remote_methods = {
self.s = nil
end
- log.warn("%s", tostring(emsg))
+ log.warn("%s:%s: %s", self.host or "", self.port or "", tostring(emsg))
self.error = emsg
self.space = {}
self:_switch_state('error')
self:_error_waiters(emsg)
self.rbuf = ''
- self.wbuf = ''
+ self.rpos = 1
+ self.rlen = 0
+ self.wbuf = {}
self.handshake = ''
end,
@@ -615,11 +619,14 @@ local remote_methods = {
_check_console_response = function(self)
while true do
- local resp = string.match(self.rbuf, '.-\n[.][.][.]\r?\n')
+ local resp = string.match(self.rbuf, '.-\n[.][.][.]\r?\n',
+ self.rpos)
if resp == nil then
break
end
- self.rbuf = string.sub(self.rbuf, #resp + 1)
+ local len = #resp
+ self.rpos = self.rpos + len
+ self.rlen = self.rlen - len
local result = yaml.decode(resp)
if result ~= nil then
@@ -656,31 +663,29 @@ local remote_methods = {
end
while true do
- if #self.rbuf < 5 then
+ if self.rlen < 5 then
break
end
- local len, off = msgpack.decode(self.rbuf)
+ local len, off = msgpack.decode(self.rbuf, self.rpos)
-- wait for correct package length
- local roff = off + len - 1
- if roff > #self.rbuf then
+ if off + len > #self.rbuf + 1 then
break
end
- local pkt = string.sub(self.rbuf, 1, roff)
- self.rbuf = string.sub(self.rbuf, roff + 1)
-
-
local hdr, body
- hdr, off = msgpack.decode(pkt, off)
- if off <= #pkt then
- body, off = msgpack.decode(pkt, off)
+ hdr, off = msgpack.decode(self.rbuf, off)
+ if off <= #self.rbuf then
+ body, off = msgpack.decode(self.rbuf, off)
-- disable YAML flow output (useful for admin console)
setmetatable(body, mapping_mt)
else
body = {}
end
+ self.rpos = off
+ self.rlen = #self.rbuf + 1 - self.rpos
+
local sync = hdr[SYNC]
if self.ch.sync[sync] ~= nil then
@@ -693,17 +698,13 @@ local remote_methods = {
end,
_switch_state = function(self, state)
- if self.state == state then
+ if self.state == state or state == nil then
return
end
self.state = state
- local list = self.wait.state[ state ]
- self.wait.state[ state ] = nil
-
- if list == nil then
- return
- end
+ local list = self.wait.state[ state ] or {}
+ self.wait.state[ state ] = {}
for _, fid in pairs(list) do
if fid ~= fiber.id() then
@@ -716,57 +717,33 @@ local remote_methods = {
end,
_wait_state = function(self, states, timeout)
- if timeout == nil then
- timeout = TIMEOUT_INFINITY
- end
- while timeout > 0 do
+ timeout = timeout or TIMEOUT_INFINITY
+ while timeout > 0 and self:_is_state(states) ~= true do
local started = fiber.time()
- for _, state in pairs(states) do
- if self.state == state then
- return true
- end
- end
-
local fid = fiber.id()
local ch = fiber.channel()
- for _, state in pairs(states) do
- if self.wait.state[state] == nil then
- self.wait.state[state] = {}
- end
+ for state, _ in pairs(states) do
+ self.wait.state[state] = self.wait.state[state] or {}
self.wait.state[state][fid] = fid
end
self.ch.fid[fid] = ch
- local res
- res = ch:get(timeout)
+ ch:get(timeout)
self.ch.fid[fid] = nil
- local has_state = false
- for _, state in pairs(states) do
- if self.wait.state[state] ~= nil then
- self.wait.state[state][fid] = nil
- end
- if self.state == state then
- has_state = true
- end
- end
-
- if has_state or res == nil then
- return res
+ for state, _ in pairs(states) do
+ self.wait.state[state][fid] = nil
end
-
timeout = timeout - (fiber.time() - started)
end
+ return self.state
end,
_connect_worker = function(self)
fiber.name('net.box.connector')
- while true do
- self:_wait_state{ 'init', 'error', 'closed' }
- if self.state == 'closed' then
- return
- end
+ local connect_states = { init = true, error = true, closed = true }
+ while self:_wait_state(connect_states) ~= 'closed' do
if self.state == 'error' then
if self.opts.reconnect_after == nil then
@@ -791,9 +768,6 @@ local remote_methods = {
elseif string.len(self.handshake) ~= 128 then
self:_fatal("Can't read handshake")
else
- self.wbuf = ''
- self.rbuf = ''
-
if string.match(self.handshake, '^Tarantool .*console') then
self.console = true
self:_switch_state('active')
@@ -808,7 +782,7 @@ local remote_methods = {
xpcall(function() self:_load_schema() end,
function(e)
- log.info("Can't load schema: %s", tostring(e))
+ log.error("Can't load schema: %s", tostring(e))
end)
if self.state ~= 'error' and self.state ~= 'closed' then
@@ -822,7 +796,6 @@ local remote_methods = {
_auth = function(self)
if self.opts.user == nil or self.opts.password == nil then
- self:_switch_state('authen')
return
end
@@ -833,35 +806,34 @@ local remote_methods = {
if auth_res.hdr[TYPE] ~= OK then
self:_fatal(auth_res.body[ERROR])
- return
end
-
- self:_switch_state('authen')
end,
-- states wakeup _read_worker
_r_states = {
- 'active', 'activew', 'schema', 'schemaw', 'closed', 'auth', 'authw'
+ active = true, activew = true, schema = true,
+ schemaw = true, auth = true, authw = true,
+ closed = true,
},
-- states wakeup _write_worker
- _rw_states = { 'activew', 'schemaw', 'closed', 'authw' },
+ _rw_states = {
+ activew = true, schemaw = true, authw = true,
+ closed = true,
+ },
+ _request_states = {
+ active = true, activew = true, closed = true,
+ },
+
+ _is_state = function(self, states)
+ return states[self.state] ~= nil
+ end,
_is_r_state = function(self)
- for _, state in pairs(self._r_states) do
- if state == self.state then
- return true
- end
- end
- return false
+ return is_state(self._r_states)
end,
_is_rw_state = function(self)
- for _, state in pairs(self._rw_states) do
- if state == self.state then
- return true
- end
- end
- return false
+ return is_state(self._rw_states)
end,
_load_schema = function(self)
@@ -944,30 +916,22 @@ local remote_methods = {
_read_worker = function(self)
fiber.name('net.box.read')
- while self.state ~= 'closed' do
- self:_wait_state(self._r_states)
- if self.state == 'closed' then
- break
- end
-
+ while self:_wait_state(self._r_states) ~= 'closed' do
if self.s:readable() then
- if self.state == 'closed' then
- break
- end
+ local data = self.s:sysread()
- if self:_is_r_state() then
- local data = self.s:sysread()
-
- if data ~= nil then
- if data == '' then
- self:_fatal('Remote host closed connection')
- else
- self.rbuf = self.rbuf .. data
- self:_check_response()
- end
+ if data ~= nil then
+ if #data == 0 then
+ self:_fatal('Remote host closed connection')
else
- self:_fatal(errno.strerror(errno()))
+ self.rbuf = string.sub(self.rbuf, self.rpos) ..
+ data
+ self.rpos = 1
+ self.rlen = #self.rbuf
+ self:_check_response()
end
+ elseif errno_is_transient[errno()] ~= true then
+ self:_fatal(errno.strerror(errno()))
end
end
end
@@ -978,42 +942,34 @@ local remote_methods = {
_write_worker = function(self)
fiber.name('net.box.write')
- while self.state ~= 'closed' do
- self:_wait_state(self._rw_states)
-
- if self.state == 'closed' then
- break
- end
-
- if string.len(self.wbuf) == 0 then
-
- local wstate = self._to_rstate[self.state]
- if wstate ~= nil then
- self:_switch_state(wstate)
- end
-
- elseif self.s:writable(.5) then
-
- if self.state == 'closed' then
- break
- end
- if self:_is_rw_state() then
- if #self.wbuf > 0 then
- local written = self.s:syswrite(self.wbuf)
- if written ~= nil then
- self.wbuf = string.sub(self.wbuf,
- tonumber(1 + written))
- else
- self:_fatal(errno.strerror(errno()))
+ while self:_wait_state(self._rw_states) ~= 'closed' do
+ while self.wbuf[1] ~= nil do
+ local s = table.concat(self.wbuf)
+ self.wbuf = {}
+ local written = self.s:syswrite(s)
+ if written ~= nil then
+ if written ~= #s then
+ table.insert(self.wbuf, string.sub(s, written + 1))
+ end
+ else
+ table.insert(self.wbuf, s)
+ if errno_is_transient[errno()] then
+ -- the write is with a timeout to detect FIN
+ -- packet on the receiving end, and close the connection.
+ -- Every second sockets we iterate the while loop
+ -- and check the connection state
+ while self.s:writable(1) == 0 and self.state ~= 'closed' do
end
+ else
+ self:_fatal(errno.strerror(errno()))
+ break
end
end
-
end
+ self:_switch_state(self._to_rstate[self.state])
end
end,
-
_request = function(self, name, raise, ...)
local fid = fiber.id()
@@ -1023,7 +979,7 @@ local remote_methods = {
local started = fiber.time()
- self:_wait_state({ 'active', 'activew', 'closed' }, self.timeouts[fid])
+ self:_wait_state(self._request_states, self.timeouts[fid])
self.timeouts[fid] = self.timeouts[fid] - (fiber.time() - started)
@@ -1062,12 +1018,9 @@ local remote_methods = {
self.timeouts[fid] = TIMEOUT_INFINITY
end
- self.wbuf = self.wbuf .. request
+ table.insert(self.wbuf, request)
- local wstate = self._to_wstate[self.state]
- if wstate ~= nil then
- self:_switch_state(wstate)
- end
+ self:_switch_state(self._to_wstate[self.state])
local ch = fiber.channel()
@@ -1151,6 +1104,7 @@ remote.self = {
close = function() end,
timeout = function(self) return self end,
wait_connected = function(self) return true end,
+ is_connected = function(self) return true end,
call = function(_box, proc_name, ...)
if type(_box) ~= 'table' then
box.error(box.error.PROC_LUA, "usage: remote:call(proc_name, ...)")
diff --git a/src/lua/utils.cc b/src/lua/utils.cc
index 6f68a5fc2528a89fd9c5f42eece62e60e440b9c8..ffd0908c50a479dfe85b7c890706f3cb6927966b 100644
--- a/src/lua/utils.cc
+++ b/src/lua/utils.cc
@@ -260,6 +260,11 @@ luaL_newserializer(struct lua_State *L, const luaL_Reg *reg)
luaL_pushnull(L);
lua_setfield(L, -2, "NULL");
+ lua_rawgeti(L, LUA_REGISTRYINDEX, luaL_array_metatable_ref);
+ lua_setfield(L, -2, "array_mt");
+ lua_rawgeti(L, LUA_REGISTRYINDEX, luaL_map_metatable_ref);
+ lua_setfield(L, -2, "map_mt");
+
return serializer;
}
@@ -678,11 +683,17 @@ tarantool_lua_utils_init(struct lua_State *L)
lua_createtable(L, 0, 1);
lua_pushliteral(L, "map"); /* YAML will use flow mode */
lua_setfield(L, -2, LUAL_SERIALIZE);
+ /* automatically reset hints on table change */
+ luaL_loadstring(L, "setmetatable((...), nil); return rawset(...)");
+ lua_setfield(L, -2, "__newindex");
luaL_map_metatable_ref = luaL_ref(L, LUA_REGISTRYINDEX);
lua_createtable(L, 0, 1);
lua_pushliteral(L, "seq"); /* YAML will use flow mode */
lua_setfield(L, -2, LUAL_SERIALIZE);
+ /* automatically reset hints on table change */
+ luaL_loadstring(L, "setmetatable((...), nil); return rawset(...)");
+ lua_setfield(L, -2, "__newindex");
luaL_array_metatable_ref = luaL_ref(L, LUA_REGISTRYINDEX);
fpconv_init();
diff --git a/src/trivia/config.h.cmake b/src/trivia/config.h.cmake
index dc272ed29dc6825fca44ef23402ff896d9b9229f..1f8bb5e3c44b2f4ef04db587c2e016264ead8107 100644
--- a/src/trivia/config.h.cmake
+++ b/src/trivia/config.h.cmake
@@ -108,6 +108,10 @@
* Defined if this platform supports openmp and it is enabled
*/
#cmakedefine HAVE_OPENMP 1
+/*
+* Defined if compatible with GNU readline installed.
+*/
+#cmakedefine HAVE_GNU_READLINE 1
/*
* Set if compiler has __builtin_XXX methods.
diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
index ad6576d4806507961cd2f2455bd649b6e0446679..547d6a50eebec4a4d05d75390fcd19700db040dd 100644
--- a/test/CMakeLists.txt
+++ b/test/CMakeLists.txt
@@ -3,6 +3,10 @@ enable_tnt_compile_flags()
add_compile_flags("C;CXX"
"-Wno-unused-parameter")
+if(POLICY CMP0037)
+ cmake_policy(SET CMP0037 OLD)
+endif(POLICY CMP0037)
+
add_custom_target(test
COMMAND ${PROJECT_SOURCE_DIR}/test/test-run.py --builddir=${PROJECT_BINARY_DIR} --vardir=${PROJECT_BINARY_DIR}/test/var)
diff --git a/test/app/console.test.lua b/test/app/console.test.lua
index d62f9a59b67c07fdd09faf67aa5d22c529436616..4bbb9ec57075e12da1084a12ed57cb96db141d77 100755
--- a/test/app/console.test.lua
+++ b/test/app/console.test.lua
@@ -129,7 +129,7 @@ client:close()
server:shutdown()
server:close()
fiber.sleep(0) -- workaround for gh-712: console.test.lua fails in Fedora
--- Check that admon console has been stopped
+-- Check that admin console has been stopped
test:isnil(socket.tcp_connect("unix/", CONSOLE_SOCKET), "console.listen stopped")
-- Stop iproto
diff --git a/test/app/float_value.result b/test/app/float_value.result
index 76c7acde8226824518866d3967ed1a5df8341316..603693b2eb4e91d105d1a9b5b48478f73cfc4882 100644
--- a/test/app/float_value.result
+++ b/test/app/float_value.result
@@ -15,7 +15,7 @@ box.cfg
14 wal_mode:write
15 wal_dir:.
16 panic_on_snap_error:true
-17 panic_on_wal_error:false
+17 panic_on_wal_error:true
18 log_level:5
19 readahead:16320
20 slab_alloc_maximal:1048576
diff --git a/test/app/init_script.result b/test/app/init_script.result
index d9fe981cd130f6e24888c94ef74990821f66c5f1..b1cac69abde02e98401dba09c5887359b74309ac 100644
--- a/test/app/init_script.result
+++ b/test/app/init_script.result
@@ -19,7 +19,7 @@ box.cfg
14 wal_mode:write
15 rows_per_wal:500000
16 panic_on_snap_error:true
-17 panic_on_wal_error:false
+17 panic_on_wal_error:true
18 wal_dir:.
19 log_level:5
20 readahead:16320
diff --git a/test/big/iterator.result b/test/big/iterator.result
index 0f64084334ef8cedab4c176c3a2b6111eee99d0a..20228d4002ce0ee24d397ddd3d76bf7f1a7c6464 100644
--- a/test/big/iterator.result
+++ b/test/big/iterator.result
@@ -891,7 +891,7 @@ space.index['primary']:pairs({}, {iterator = -666 })
-- Test cases for #123: box.index.count does not check arguments properly
space.index['primary']:pairs(function() end, { iterator = box.index.EQ })
---
-- error: 'builtin/msgpackffi.lua:262: can not encode Lua type: ''function'''
+- error: 'builtin/msgpackffi.lua:261: can not encode Lua type: ''function'''
...
-- Check that iterators successfully invalidated when index deleted
gen, param, state = space.index['i1']:pairs(nil, { iterator = box.index.GE })
diff --git a/test/big/lua.result b/test/big/lua.result
index 0dd74ac6391edfd67c37cfec4d60ede97c4a37e0..d41273ab2ce11a7c09dc55d23094ecf96b234cbd 100644
--- a/test/big/lua.result
+++ b/test/big/lua.result
@@ -574,7 +574,7 @@ space.index['i1']:count()
-- Test cases for #123: box.index.count does not check arguments properly
space.index['i1']:count(function() end)
---
-- error: 'builtin/msgpackffi.lua:262: can not encode Lua type: ''function'''
+- error: 'builtin/msgpackffi.lua:261: can not encode Lua type: ''function'''
...
space:drop()
---
diff --git a/test/box/admin.result b/test/box/admin.result
index bd184b122aff15f7ce27fae3f4727a1c7617eb46..807cff8b1fdc2191de54ab3bfe0745a8b11243df 100644
--- a/test/box/admin.result
+++ b/test/box/admin.result
@@ -38,7 +38,7 @@ box.cfg
wal_mode: write
wal_dir: .
panic_on_snap_error: true
- panic_on_wal_error: false
+ panic_on_wal_error: true
log_level: 5
readahead: 16320
pid_file: tarantool.pid
diff --git a/test/box/bsdsocket.result b/test/box/bsdsocket.result
index 691d63bd6030755bf6f0b26ac5171952aa40fb2d..948aeb702425a96a89cae5efc1d5d53797c203c1 100644
--- a/test/box/bsdsocket.result
+++ b/test/box/bsdsocket.result
@@ -70,7 +70,7 @@ s:close()
s:close()
---
-- false
+- error: 'builtin/socket.lua:83: attempt to use closed socket'
...
LISTEN = require('uri').parse(box.cfg.listen)
---
@@ -279,7 +279,7 @@ s:getsockopt('SOL_SOCKET', 'SO_DEBUG')
...
s:setsockopt('SOL_SOCKET', 'SO_ACCEPTCONN', 1)
---
-- error: 'builtin/socket.lua:343: Socket option SO_ACCEPTCONN is read only'
+- error: 'builtin/socket.lua:357: Socket option SO_ACCEPTCONN is read only'
...
s:getsockopt('SOL_SOCKET', 'SO_RCVBUF') > 32
---
@@ -590,18 +590,20 @@ os.remove('/tmp/tarantool-test-socket')
- true
...
--# setopt delimiter ';'
-function aexitst(ai, host, port)
+function aexitst(ai, hostnames, port)
for i, a in pairs(ai) do
- if a.host == host and a.port == port then
- return true
+ for j, host in pairs(hostnames) do
+ if a.host == host and a.port == port then
+ return true
+ end
end
end
- return false
+ return ai
end;
---
...
aexitst( socket.getaddrinfo('localhost', 'http', { protocol = 'tcp',
- type = 'SOCK_STREAM'}), '127.0.0.1', 80 );
+ type = 'SOCK_STREAM'}), {'127.0.0.1', '::1'}, 80 );
---
- true
...
@@ -1028,7 +1030,7 @@ ch:get(1)
...
s:error()
---
-- null
+- error: 'builtin/socket.lua:83: attempt to use closed socket'
...
-- random port
port = 33123
diff --git a/test/box/bsdsocket.test.lua b/test/box/bsdsocket.test.lua
index 98ac0a4d2200e84ee7a28a3053135e794259db28..1774bda60f0185440c8927dcc99371fabd406df5 100644
--- a/test/box/bsdsocket.test.lua
+++ b/test/box/bsdsocket.test.lua
@@ -184,17 +184,20 @@ s:close()
os.remove('/tmp/tarantool-test-socket')
--# setopt delimiter ';'
-function aexitst(ai, host, port)
+function aexitst(ai, hostnames, port)
for i, a in pairs(ai) do
- if a.host == host and a.port == port then
- return true
+ for j, host in pairs(hostnames) do
+ if a.host == host and a.port == port then
+ return true
+ end
end
end
- return false
+ return ai
end;
+
aexitst( socket.getaddrinfo('localhost', 'http', { protocol = 'tcp',
- type = 'SOCK_STREAM'}), '127.0.0.1', 80 );
+ type = 'SOCK_STREAM'}), {'127.0.0.1', '::1'}, 80 );
--# setopt delimiter ''
#(socket.getaddrinfo('tarantool.org', 'http', {})) > 0
diff --git a/test/box/cfg.result b/test/box/cfg.result
index 26e161104db5d9817b8f6c22436a2c7a3dc9e4e0..61e12fb73d441be2a8f7e3918be35412a7201ef0 100644
--- a/test/box/cfg.result
+++ b/test/box/cfg.result
@@ -2,7 +2,7 @@
--# push filter 'admin: .*' to 'admin: <uri>'
box.cfg.nosuchoption = 1
---
-- error: '[string "-- load_cfg.lua - internal file..."]:258: Attempt to modify a read-only
+- error: '[string "-- load_cfg.lua - internal file..."]:260: Attempt to modify a read-only
table'
...
t = {} for k,v in pairs(box.cfg) do if type(v) ~= 'table' and type(v) ~= 'function' then table.insert(t, k..': '..tostring(v)) end end
@@ -25,7 +25,7 @@ t
- 'wal_mode: write'
- 'wal_dir: .'
- 'panic_on_snap_error: true'
- - 'panic_on_wal_error: false'
+ - 'panic_on_wal_error: true'
- 'log_level: 5'
- 'readahead: 16320'
- 'pid_file: tarantool.pid'
@@ -36,7 +36,7 @@ t
-- must be read-only
box.cfg()
---
-- error: '[string "-- load_cfg.lua - internal file..."]:204: bad argument #1 to ''pairs''
+- error: '[string "-- load_cfg.lua - internal file..."]:206: bad argument #1 to ''pairs''
(table expected, got nil)'
...
t = {} for k,v in pairs(box.cfg) do if type(v) ~= 'table' and type(v) ~= 'function' then table.insert(t, k..': '..tostring(v)) end end
@@ -59,7 +59,7 @@ t
- 'wal_mode: write'
- 'wal_dir: .'
- 'panic_on_snap_error: true'
- - 'panic_on_wal_error: false'
+ - 'panic_on_wal_error: true'
- 'log_level: 5'
- 'readahead: 16320'
- 'pid_file: tarantool.pid'
@@ -70,23 +70,23 @@ t
-- check that cfg with unexpected parameter fails.
box.cfg{sherlock = 'holmes'}
---
-- error: '[string "-- load_cfg.lua - internal file..."]:160: Error: cfg parameter
+- error: '[string "-- load_cfg.lua - internal file..."]:162: Error: cfg parameter
''sherlock'' is unexpected'
...
-- check that cfg with unexpected type of parameter failes
box.cfg{listen = {}}
---
-- error: '[string "-- load_cfg.lua - internal file..."]:180: Error: cfg parameter
+- error: '[string "-- load_cfg.lua - internal file..."]:182: Error: cfg parameter
''listen'' should be one of types: string, number'
...
box.cfg{wal_dir = 0}
---
-- error: '[string "-- load_cfg.lua - internal file..."]:174: Error: cfg parameter
+- error: '[string "-- load_cfg.lua - internal file..."]:176: Error: cfg parameter
''wal_dir'' should be of type string'
...
box.cfg{coredump = 'true'}
---
-- error: '[string "-- load_cfg.lua - internal file..."]:174: Error: cfg parameter
+- error: '[string "-- load_cfg.lua - internal file..."]:176: Error: cfg parameter
''coredump'' should be of type boolean'
...
--------------------------------------------------------------------------------
@@ -94,17 +94,17 @@ box.cfg{coredump = 'true'}
--------------------------------------------------------------------------------
box.cfg{slab_alloc_arena = "100500"}
---
-- error: '[string "-- load_cfg.lua - internal file..."]:174: Error: cfg parameter
+- error: '[string "-- load_cfg.lua - internal file..."]:176: Error: cfg parameter
''slab_alloc_arena'' should be of type number'
...
box.cfg{sophia = "sophia"}
---
-- error: '[string "-- load_cfg.lua - internal file..."]:168: Error: cfg parameter
+- error: '[string "-- load_cfg.lua - internal file..."]:170: Error: cfg parameter
''sophia'' should be a table'
...
box.cfg{sophia = {threads = "threads"}}
---
-- error: '[string "-- load_cfg.lua - internal file..."]:174: Error: cfg parameter
+- error: '[string "-- load_cfg.lua - internal file..."]:176: Error: cfg parameter
''sophia.threads'' should be of type number'
...
--------------------------------------------------------------------------------
diff --git a/test/box/misc.result b/test/box/misc.result
index 46a7821f266f3f5fccbf781cffcb67a5fe8220b2..0fe4994e168993ed3443eecb01de82a0155ed1ca 100644
--- a/test/box/misc.result
+++ b/test/box/misc.result
@@ -205,6 +205,7 @@ t;
- 'box.error.PASSWORD_MISMATCH : 47'
- 'box.error.NO_SUCH_ENGINE : 57'
- 'box.error.ACCESS_DENIED : 42'
+ - 'box.error.UPDATE_INTEGER_OVERFLOW : 95'
- 'box.error.LAST_DROP : 15'
- 'box.error.USER_EXISTS : 46'
- 'box.error.WAL_IO : 40'
diff --git a/test/box/net.box.result b/test/box/net.box.result
index d54d106f006ca3adce0707221d9e09286bf66170..7fb11049c6be505dbbc1ec774ad1a2237639fd91 100644
--- a/test/box/net.box.result
+++ b/test/box/net.box.result
@@ -26,9 +26,9 @@ log.info("create connection")
cn = remote:new(LISTEN.host, LISTEN.service)
---
...
-cn:_wait_state({'active', 'error'}, 1)
+cn:_wait_state({active = true, error = true}, 1)
---
-- true
+- active
...
log.info("state is %s", cn.state)
---
@@ -399,9 +399,9 @@ cn:call('test_foo')
cn = remote:new(LISTEN.host, LISTEN.service, { reconnect_after = .1 })
---
...
-cn:_wait_state({'active'}, 1)
+cn:_wait_state({active = true}, 1)
---
-- true
+- active
...
cn.space ~= nil
---
@@ -415,9 +415,9 @@ cn.space.net_box_test_space:select({}, { iterator = 'ALL' })
cn:_fatal 'Test error'
---
...
-cn:_wait_state({'active', 'activew'}, 2)
+cn:_wait_state({active = true, activew = true}, 2)
---
-- true
+- active
...
cn:ping()
---
@@ -588,7 +588,6 @@ cn:timeout(.01):call('ret_after', 1)
...
cn = remote:timeout(0.0000000001):new(LISTEN.host, LISTEN.service, { user = 'netbox', password = '123' })
---
-- error: Timeout exceeded
...
cn = remote:timeout(1):new(LISTEN.host, LISTEN.service, { user = 'netbox', password = '123' })
---
@@ -605,6 +604,14 @@ remote.self:timeout(123).space.net_box_test_space:select{234}
---
- - [234, 1, 2, 3]
...
+remote.self:is_connected()
+---
+- true
+...
+remote.self:wait_connected()
+---
+- true
+...
-- cleanup database after tests
space:drop()
---
diff --git a/test/box/net.box.test.lua b/test/box/net.box.test.lua
index f4240d147b80b76f0053a578037e8e7490ab63da..7c2d0d5a005b26feabc6a86e754fd74bf0a0f185 100644
--- a/test/box/net.box.test.lua
+++ b/test/box/net.box.test.lua
@@ -10,7 +10,7 @@ index = space:create_index('primary', { type = 'tree' })
-- low level connection
log.info("create connection")
cn = remote:new(LISTEN.host, LISTEN.service)
-cn:_wait_state({'active', 'error'}, 1)
+cn:_wait_state({active = true, error = true}, 1)
log.info("state is %s", cn.state)
cn:ping()
@@ -134,12 +134,12 @@ cn:call('test_foo')
-- -- 2 reconnect
cn = remote:new(LISTEN.host, LISTEN.service, { reconnect_after = .1 })
-cn:_wait_state({'active'}, 1)
+cn:_wait_state({active = true}, 1)
cn.space ~= nil
cn.space.net_box_test_space:select({}, { iterator = 'ALL' })
cn:_fatal 'Test error'
-cn:_wait_state({'active', 'activew'}, 2)
+cn:_wait_state({active = true, activew = true}, 2)
cn:ping()
cn.state
cn.space.net_box_test_space:select({}, { iterator = 'ALL' })
@@ -216,7 +216,8 @@ cn = remote:timeout(1):new(LISTEN.host, LISTEN.service, { user = 'netbox', passw
remote.self:ping()
remote.self.space.net_box_test_space:select{234}
remote.self:timeout(123).space.net_box_test_space:select{234}
-
+remote.self:is_connected()
+remote.self:wait_connected()
-- cleanup database after tests
diff --git a/test/box/tuple.result b/test/box/tuple.result
index 8a4f7a0bebde0a93d8b659751fb49a6092c02978..2c9e15e1a8bbc5b4874ea79cae635ffaf8a53940 100644
--- a/test/box/tuple.result
+++ b/test/box/tuple.result
@@ -305,12 +305,12 @@ t:unpack(2, 1)
...
t:totable(0)
---
-- error: '[string "-- tuple.lua (internal file)..."]:116: tuple.totable: invalid second
+- error: '[string "-- tuple.lua (internal file)..."]:111: tuple.totable: invalid second
argument'
...
t:totable(1, 0)
---
-- error: '[string "-- tuple.lua (internal file)..."]:125: tuple.totable: invalid third
+- error: '[string "-- tuple.lua (internal file)..."]:120: tuple.totable: invalid third
argument'
...
--
@@ -320,9 +320,9 @@ box.tuple.new{1, 2, 3}:totable()
---
- [1, 2, 3]
...
-getmetatable(box.tuple.new{1, 2, 3}:totable())
+getmetatable(box.tuple.new{1, 2, 3}:totable()).__serialize
---
-- __serialize: seq
+- seq
...
-- A test case for the key as an tuple
space = box.schema.space.create('tweedledum')
@@ -803,12 +803,12 @@ t = box.tuple.new({'a', 'b', 'c', 'd', 'e'})
...
t:update()
---
-- error: '[string "-- tuple.lua (internal file)..."]:165: Usage: tuple:update({ {
+- error: '[string "-- tuple.lua (internal file)..."]:160: Usage: tuple:update({ {
op, field, arg}+ })'
...
t:update(10)
---
-- error: '[string "-- tuple.lua (internal file)..."]:165: Usage: tuple:update({ {
+- error: '[string "-- tuple.lua (internal file)..."]:160: Usage: tuple:update({ {
op, field, arg}+ })'
...
t:update({})
@@ -873,6 +873,32 @@ msgpack.decode(msgpack.encode({1, {'x', 'y', t, 'z'}, 2, 3}))
msgpack.cfg{encode_load_metatables = encode_load_metatables}
---
...
+-- gh-738: Serializer hints are unclear
+t = box.tuple.new({1, 2, {}})
+---
+...
+map = t[3]
+---
+...
+getmetatable(map) ~= nil
+---
+- true
+...
+map
+---
+- []
+...
+map['test'] = 48
+---
+...
+map
+---
+- test: 48
+...
+getmetatable(map) == nil
+---
+- true
+...
space:drop()
---
...
diff --git a/test/box/tuple.test.lua b/test/box/tuple.test.lua
index 5c84de193b4b6f242642719b9b43380c4d9aeeb9..72b67ee313d7f89440f8580f285c27878884c0de 100644
--- a/test/box/tuple.test.lua
+++ b/test/box/tuple.test.lua
@@ -91,7 +91,7 @@ t:totable(1, 0)
-- Check that tuple:totable correctly sets serializer hints
--
box.tuple.new{1, 2, 3}:totable()
-getmetatable(box.tuple.new{1, 2, 3}:totable())
+getmetatable(box.tuple.new{1, 2, 3}:totable()).__serialize
-- A test case for the key as an tuple
space = box.schema.space.create('tweedledum')
@@ -280,4 +280,13 @@ msgpack.decode(msgpack.encode({1, {'x', 'y', t, 'z'}, 2, 3}))
-- restore configuration
msgpack.cfg{encode_load_metatables = encode_load_metatables}
+-- gh-738: Serializer hints are unclear
+t = box.tuple.new({1, 2, {}})
+map = t[3]
+getmetatable(map) ~= nil
+map
+map['test'] = 48
+map
+getmetatable(map) == nil
+
space:drop()
diff --git a/test/box/update.result b/test/box/update.result
index 2094e4a2ab63af5dcfd182f653c6de150a20f5d3..2262ba7a72ca62a8b6ccda7dff361bc6e76a2634 100644
--- a/test/box/update.result
+++ b/test/box/update.result
@@ -336,3 +336,303 @@ s:update({1}, {'=', 1, 1})
s:drop()
---
...
+-- #528: Different types in arithmetical update, overflow check
+ffi = require('ffi')
+---
+...
+s = box.schema.create_space('tweedledum')
+---
+...
+index = s:create_index('pk')
+---
+...
+s:insert{0, -1}
+---
+- [0, -1]
+...
+-- + --
+s:update({0}, {{'+', 2, "a"}}) -- err
+---
+- error: 'Argument type in operation ''+'' on field 2 does not match field type: expected
+ a NUMBER'
+...
+s:update({0}, {{'+', 2, 10}}) -- neg(ative) + pos(itive) = pos(itive) 9
+---
+- [0, 9]
+...
+s:update({0}, {{'+', 2, 5}}) -- pos + pos = pos 14
+---
+- [0, 14]
+...
+s:update({0}, {{'+', 2, -4}}) -- pos + neg = pos 10
+---
+- [0, 10]
+...
+s:update({0}, {{'+', 2, -22}}) -- pos + neg = neg -12
+---
+- [0, -12]
+...
+s:update({0}, {{'+', 2, -3}}) -- neg + neg = neg -15
+---
+- [0, -15]
+...
+s:update({0}, {{'+', 2, 7}}) -- neg + pos = neg -8
+---
+- [0, -8]
+...
+-- - --
+s:update({0}, {{'-', 2, "a"}}) -- err
+---
+- error: 'Argument type in operation ''-'' on field 2 does not match field type: expected
+ a NUMBER'
+...
+s:update({0}, {{'-', 2, 16}}) -- neg(ative) - pos(itive) = neg(ative) -24
+---
+- [0, -24]
+...
+s:update({0}, {{'-', 2, -4}}) -- neg - neg = neg 20
+---
+- [0, -20]
+...
+s:update({0}, {{'-', 2, -32}}) -- neg - neg = pos 12
+---
+- [0, 12]
+...
+s:update({0}, {{'-', 2, 3}}) -- pos - pos = pos 9
+---
+- [0, 9]
+...
+s:update({0}, {{'-', 2, -5}}) -- pos - neg = pos 14
+---
+- [0, 14]
+...
+s:update({0}, {{'-', 2, 17}}) -- pos - pos = neg -3
+---
+- [0, -3]
+...
+-- bit --
+s:replace{0, 0} -- 0
+---
+- [0, 0]
+...
+s:update({0}, {{'|', 2, 24}}) -- 24
+---
+- [0, 24]
+...
+s:update({0}, {{'|', 2, 2}}) -- 26
+---
+- [0, 26]
+...
+s:update({0}, {{'&', 2, 50}}) -- 18
+---
+- [0, 18]
+...
+s:update({0}, {{'^', 2, 6}}) -- 20
+---
+- [0, 20]
+...
+s:update({0}, {{'|', 2, -1}}) -- err
+---
+- error: 'Argument type in operation ''|'' on field 2 does not match field type: expected
+ a UINT'
+...
+s:update({0}, {{'&', 2, -1}}) -- err
+---
+- error: 'Argument type in operation ''&'' on field 2 does not match field type: expected
+ a UINT'
+...
+s:update({0}, {{'^', 2, -1}}) -- err
+---
+- error: 'Argument type in operation ''^'' on field 2 does not match field type: expected
+ a UINT'
+...
+s:replace{0, -1} -- -1
+---
+- [0, -1]
+...
+s:update({0}, {{'|', 2, 2}}) -- err
+---
+- error: 'Argument type in operation ''|'' on field 2 does not match field type: expected
+ a UINT'
+...
+s:update({0}, {{'&', 2, 40}}) -- err
+---
+- error: 'Argument type in operation ''&'' on field 2 does not match field type: expected
+ a UINT'
+...
+s:update({0}, {{'^', 2, 6}}) -- err
+---
+- error: 'Argument type in operation ''^'' on field 2 does not match field type: expected
+ a UINT'
+...
+s:replace{0, 1.5} -- 1.5
+---
+- [0, 1.5]
+...
+s:update({0}, {{'|', 2, 2}}) -- err
+---
+- error: 'Argument type in operation ''|'' on field 2 does not match field type: expected
+ a UINT'
+...
+s:update({0}, {{'&', 2, 40}}) -- err
+---
+- error: 'Argument type in operation ''&'' on field 2 does not match field type: expected
+ a UINT'
+...
+s:update({0}, {{'^', 2, 6}}) -- err
+---
+- error: 'Argument type in operation ''^'' on field 2 does not match field type: expected
+ a UINT'
+...
+-- double
+s:replace{0, 5} -- 5
+---
+- [0, 5]
+...
+s:update({0}, {{'+', 2, 1.5}}) -- int + double = double 6.5
+---
+- [0, 6.5]
+...
+s:update({0}, {{'|', 2, 2}}) -- err (double!)
+---
+- error: 'Argument type in operation ''|'' on field 2 does not match field type: expected
+ a UINT'
+...
+s:update({0}, {{'-', 2, 0.5}}) -- double - double = double 6
+---
+- [0, 6]
+...
+s:update({0}, {{'+', 2, 1.5}}) -- double + double = double 7.5
+---
+- [0, 7.5]
+...
+-- float
+s:replace{0, ffi.new("float", 1.5)} -- 1.5
+---
+- [0, 1.5]
+...
+s:update({0}, {{'+', 2, 2}}) -- float + int = float 3.5
+---
+- [0, 3.5]
+...
+s:update({0}, {{'+', 2, ffi.new("float", 3.5)}}) -- float + int = float 7
+---
+- [0, 7]
+...
+s:update({0}, {{'|', 2, 2}}) -- err (float!)
+---
+- error: 'Argument type in operation ''|'' on field 2 does not match field type: expected
+ a UINT'
+...
+s:update({0}, {{'-', 2, ffi.new("float", 1.5)}}) -- float - float = float 5.5
+---
+- [0, 5.5]
+...
+s:update({0}, {{'+', 2, ffi.new("float", 3.5)}}) -- float + float = float 9
+---
+- [0, 9]
+...
+s:update({0}, {{'-', 2, ffi.new("float", 9)}}) -- float + float = float 0
+---
+- [0, 0]
+...
+s:update({0}, {{'+', 2, ffi.new("float", 1.2)}}) -- float + float = float 1.2
+---
+- [0, 1.2000000476837]
+...
+-- overflow --
+s:replace{0, 0xfffffffffffffffeull}
+---
+- [0, 18446744073709551614]
+...
+s:update({0}, {{'+', 2, 1}}) -- ok
+---
+- [0, 18446744073709551615]
+...
+s:update({0}, {{'+', 2, 1}}) -- overflow
+---
+- error: Integer overflow when performing '+' operation on field 2
+...
+s:update({0}, {{'+', 2, 100500}}) -- overflow
+---
+- error: Integer overflow when performing '+' operation on field 2
+...
+s:replace{0, 1}
+---
+- [0, 1]
+...
+s:update({0}, {{'+', 2, 0xffffffffffffffffull}}) -- overflow
+---
+- error: Integer overflow when performing '+' operation on field 2
+...
+s:replace{0, -1}
+---
+- [0, -1]
+...
+s:update({0}, {{'+', 2, 0xffffffffffffffffull}}) -- ok
+---
+- [0, 18446744073709551614]
+...
+s:replace{0, 0}
+---
+- [0, 0]
+...
+s:update({0}, {{'-', 2, 0x7fffffffffffffffull}}) -- ok
+---
+- [0, -9223372036854775807]
+...
+s:replace{0, -1}
+---
+- [0, -1]
+...
+s:update({0}, {{'-', 2, 0x7fffffffffffffffull}}) -- ok
+---
+- [0, -9223372036854775808]
+...
+s:replace{0, -2}
+---
+- [0, -2]
+...
+s:update({0}, {{'-', 2, 0x7fffffffffffffffull}}) -- overflow
+---
+- error: Integer overflow when performing '-' operation on field 2
+...
+s:replace{0, 1}
+---
+- [0, 1]
+...
+s:update({0}, {{'-', 2, 0xffffffffffffffffull}}) -- overflow
+---
+- error: Integer overflow when performing '-' operation on field 2
+...
+s:replace{0, 0xffffffffffffffefull}
+---
+- [0, 18446744073709551599]
+...
+s:update({0}, {{'-', 2, -16}}) -- ok
+---
+- [0, 18446744073709551615]
+...
+s:update({0}, {{'-', 2, -16}}) -- overflow
+---
+- error: Integer overflow when performing '-' operation on field 2
+...
+s:replace{0, -0x4000000000000000ll}
+---
+- [0, -4611686018427387904]
+...
+s:update({0}, {{'+', 2, -0x4000000000000000ll}}) -- ok
+---
+- [0, -9223372036854775808]
+...
+s:replace{0, -0x4000000000000000ll}
+---
+- [0, -4611686018427387904]
+...
+s:update({0}, {{'+', 2, -0x4000000000000001ll}}) -- overflow
+---
+- error: Integer overflow when performing '+' operation on field 2
+...
+s:drop()
+---
+...
diff --git a/test/box/update.test.lua b/test/box/update.test.lua
index f662569f305d542586a883ee655ab38c1f7dd1be..4b6da698cad885b566962d621855db4bbd089c33 100644
--- a/test/box/update.test.lua
+++ b/test/box/update.test.lua
@@ -114,3 +114,84 @@ s:insert{1, 2, 3}
s:update({1})
s:update({1}, {'=', 1, 1})
s:drop()
+
+-- #528: Different types in arithmetical update, overflow check
+ffi = require('ffi')
+s = box.schema.create_space('tweedledum')
+index = s:create_index('pk')
+s:insert{0, -1}
+-- + --
+s:update({0}, {{'+', 2, "a"}}) -- err
+s:update({0}, {{'+', 2, 10}}) -- neg(ative) + pos(itive) = pos(itive) 9
+s:update({0}, {{'+', 2, 5}}) -- pos + pos = pos 14
+s:update({0}, {{'+', 2, -4}}) -- pos + neg = pos 10
+s:update({0}, {{'+', 2, -22}}) -- pos + neg = neg -12
+s:update({0}, {{'+', 2, -3}}) -- neg + neg = neg -15
+s:update({0}, {{'+', 2, 7}}) -- neg + pos = neg -8
+-- - --
+s:update({0}, {{'-', 2, "a"}}) -- err
+s:update({0}, {{'-', 2, 16}}) -- neg(ative) - pos(itive) = neg(ative) -24
+s:update({0}, {{'-', 2, -4}}) -- neg - neg = neg 20
+s:update({0}, {{'-', 2, -32}}) -- neg - neg = pos 12
+s:update({0}, {{'-', 2, 3}}) -- pos - pos = pos 9
+s:update({0}, {{'-', 2, -5}}) -- pos - neg = pos 14
+s:update({0}, {{'-', 2, 17}}) -- pos - pos = neg -3
+-- bit --
+s:replace{0, 0} -- 0
+s:update({0}, {{'|', 2, 24}}) -- 24
+s:update({0}, {{'|', 2, 2}}) -- 26
+s:update({0}, {{'&', 2, 50}}) -- 18
+s:update({0}, {{'^', 2, 6}}) -- 20
+s:update({0}, {{'|', 2, -1}}) -- err
+s:update({0}, {{'&', 2, -1}}) -- err
+s:update({0}, {{'^', 2, -1}}) -- err
+s:replace{0, -1} -- -1
+s:update({0}, {{'|', 2, 2}}) -- err
+s:update({0}, {{'&', 2, 40}}) -- err
+s:update({0}, {{'^', 2, 6}}) -- err
+s:replace{0, 1.5} -- 1.5
+s:update({0}, {{'|', 2, 2}}) -- err
+s:update({0}, {{'&', 2, 40}}) -- err
+s:update({0}, {{'^', 2, 6}}) -- err
+-- double
+s:replace{0, 5} -- 5
+s:update({0}, {{'+', 2, 1.5}}) -- int + double = double 6.5
+s:update({0}, {{'|', 2, 2}}) -- err (double!)
+s:update({0}, {{'-', 2, 0.5}}) -- double - double = double 6
+s:update({0}, {{'+', 2, 1.5}}) -- double + double = double 7.5
+-- float
+s:replace{0, ffi.new("float", 1.5)} -- 1.5
+s:update({0}, {{'+', 2, 2}}) -- float + int = float 3.5
+s:update({0}, {{'+', 2, ffi.new("float", 3.5)}}) -- float + int = float 7
+s:update({0}, {{'|', 2, 2}}) -- err (float!)
+s:update({0}, {{'-', 2, ffi.new("float", 1.5)}}) -- float - float = float 5.5
+s:update({0}, {{'+', 2, ffi.new("float", 3.5)}}) -- float + float = float 9
+s:update({0}, {{'-', 2, ffi.new("float", 9)}}) -- float + float = float 0
+s:update({0}, {{'+', 2, ffi.new("float", 1.2)}}) -- float + float = float 1.2
+-- overflow --
+s:replace{0, 0xfffffffffffffffeull}
+s:update({0}, {{'+', 2, 1}}) -- ok
+s:update({0}, {{'+', 2, 1}}) -- overflow
+s:update({0}, {{'+', 2, 100500}}) -- overflow
+s:replace{0, 1}
+s:update({0}, {{'+', 2, 0xffffffffffffffffull}}) -- overflow
+s:replace{0, -1}
+s:update({0}, {{'+', 2, 0xffffffffffffffffull}}) -- ok
+s:replace{0, 0}
+s:update({0}, {{'-', 2, 0x7fffffffffffffffull}}) -- ok
+s:replace{0, -1}
+s:update({0}, {{'-', 2, 0x7fffffffffffffffull}}) -- ok
+s:replace{0, -2}
+s:update({0}, {{'-', 2, 0x7fffffffffffffffull}}) -- overflow
+s:replace{0, 1}
+s:update({0}, {{'-', 2, 0xffffffffffffffffull}}) -- overflow
+s:replace{0, 0xffffffffffffffefull}
+s:update({0}, {{'-', 2, -16}}) -- ok
+s:update({0}, {{'-', 2, -16}}) -- overflow
+s:replace{0, -0x4000000000000000ll}
+s:update({0}, {{'+', 2, -0x4000000000000000ll}}) -- ok
+s:replace{0, -0x4000000000000000ll}
+s:update({0}, {{'+', 2, -0x4000000000000001ll}}) -- overflow
+
+s:drop()
+
diff --git a/test/replication/cluster.test.py b/test/replication/cluster.test.py
index 0f78c3efba9c4c2eecccdf4367255e9ae4c0f197..84872550ef8f0afbc63b1b194a486537e9f940ee 100644
--- a/test/replication/cluster.test.py
+++ b/test/replication/cluster.test.py
@@ -94,17 +94,18 @@ server.admin('box.snapshot()')
print '-------------------------------------------------------------'
print 'gh-434: Assertion if replace _cluster tuple'
print '-------------------------------------------------------------'
+server.stop()
+script = server.script
+server.script = "replication/panic.lua"
+server.deploy()
new_uuid = '8c7ff474-65f9-4abe-81a4-a3e1019bb1ae'
+# Check log message
# Requires panic_on_wal_error = false
server.admin("box.space._cluster:replace{{1, '{0}'}}".format(new_uuid))
server.admin("box.info.server.uuid")
-# Check log message
-server.stop()
-server.start()
-
line = "server UUID changed to " + new_uuid
print "check log line for '%s'" % line
print
@@ -124,6 +125,7 @@ server.admin("box.space._cluster:replace{1, require('uuid').NULL:str()}")
# Cleanup
server.stop()
+server.script = script
server.deploy()
print '-------------------------------------------------------------'
diff --git a/test/replication/panic.lua b/test/replication/panic.lua
new file mode 100644
index 0000000000000000000000000000000000000000..06c7f7eba43189ee90b90b4d6d25e10d02727eed
--- /dev/null
+++ b/test/replication/panic.lua
@@ -0,0 +1,12 @@
+#!/usr/bin/env tarantool
+os = require('os')
+box.cfg({
+ listen = os.getenv("LISTEN"),
+ slab_alloc_arena = 0.1,
+ pid_file = "tarantool.pid",
+ logger = "| cat - >> tarantool.log",
+ panic_on_wal_error = false,
+ custom_proc_title = "master",
+})
+
+require('console').listen(os.getenv('ADMIN'))
diff --git a/test/unit/CMakeLists.txt b/test/unit/CMakeLists.txt
index 72f7e9bed55ff441a1b3dae78524380e1e724bb0..4833461371e482ad674f8222e01a20de7945ca46 100644
--- a/test/unit/CMakeLists.txt
+++ b/test/unit/CMakeLists.txt
@@ -17,6 +17,7 @@ add_executable(rope_avl.test rope_avl.c ${CMAKE_SOURCE_DIR}/src/lib/salad/rope.c
add_executable(rope_stress.test rope_stress.c ${CMAKE_SOURCE_DIR}/src/lib/salad/rope.c)
add_executable(rope.test rope.c ${CMAKE_SOURCE_DIR}/src/lib/salad/rope.c)
add_executable(bit.test bit.c bit.c)
+add_executable(int96.test int96.cc)
target_link_libraries(bit.test bit)
add_executable(bitset_basic.test bitset_basic.c)
target_link_libraries(bitset_basic.test bitset)
@@ -64,6 +65,9 @@ target_link_libraries(fiber.test core)
add_executable(fiber_stress.test fiber_stress.cc)
target_link_libraries(fiber_stress.test core)
+add_executable(ipc.test ipc.cc ${CMAKE_SOURCE_DIR}/src/ipc.cc)
+target_link_libraries(ipc.test core)
+
add_executable(coio.test coio.cc unit.c
${CMAKE_SOURCE_DIR}/src/sio.cc
${CMAKE_SOURCE_DIR}/src/evio.cc
diff --git a/test/unit/fiber_stress.cc b/test/unit/fiber_stress.cc
index 1672b3be54e7831ca4a20992928cfb8a211f65a7..2afcb382f30a1e0b2a7f145605784dd909c8a7ff 100644
--- a/test/unit/fiber_stress.cc
+++ b/test/unit/fiber_stress.cc
@@ -2,8 +2,8 @@
#include "fiber.h"
enum {
- ITERATIONS = 5000,
- FIBERS = 10
+ ITERATIONS = 50000,
+ FIBERS = 100
};
void yield_f(va_list ap)
diff --git a/test/unit/int96.cc b/test/unit/int96.cc
new file mode 100644
index 0000000000000000000000000000000000000000..83113a0654a7df3f0f53ea0c8796489853f9689c
--- /dev/null
+++ b/test/unit/int96.cc
@@ -0,0 +1,71 @@
+#include <bit/int96.h>
+
+#include "unit.h"
+
+#define check(expr) if (!(expr)) printf("failed at %s:%d\n", __FILE__, __LINE__)
+
+static void
+test()
+{
+ header();
+
+ const uint64_t a = 0xFFFFFFFFFFFFFFFFull / 2;
+ int96_num num, num1, num2;
+ int96_set_unsigned(&num, 0);
+ int96_set_unsigned(&num1, a);
+ int96_set_unsigned(&num2, a);
+ int96_invert(&num2);
+ check(int96_is_neg_int64(&num2));
+ check(int96_extract_neg_int64(&num2) == -a);
+ check(int96_is_uint64(&num));
+ check(int96_extract_uint64(&num) == 0);
+ int96_add(&num, &num1);
+ check(int96_is_uint64(&num));
+ check(int96_extract_uint64(&num) == a);
+ int96_add(&num, &num1);
+ check(int96_is_uint64(&num));
+ check(int96_extract_uint64(&num) == a * 2);
+ for (int i = 1; i < 1000; i++) {
+ for(int j = 0; j < i; j++) {
+ int96_add(&num, &num1);
+ check(!int96_is_uint64(&num) && !int96_is_neg_int64(&num));
+ }
+ for(int j = 0; j < i - 1; j++) {
+ int96_add(&num, &num2);
+ check(!int96_is_uint64(&num) && !int96_is_neg_int64(&num));
+ }
+ int96_add(&num, &num2);
+ check(int96_is_uint64(&num));
+ check(int96_extract_uint64(&num) == a * 2);
+ }
+ int96_add(&num, &num2);
+ check(int96_is_uint64(&num));
+ check(int96_extract_uint64(&num) == a);
+ int96_add(&num, &num2);
+ check(int96_is_uint64(&num));
+ check(int96_extract_uint64(&num) == 0);
+ int96_add(&num, &num2);
+ check(int96_is_neg_int64(&num));
+ check(int96_extract_neg_int64(&num) == -a);
+ for (int i = 1; i < 1000; i++) {
+ for(int j = 0; j < i; j++) {
+ int96_add(&num, &num2);
+ check(!int96_is_uint64(&num) && !int96_is_neg_int64(&num));
+ }
+ for(int j = 0; j < i - 1; j++) {
+ int96_add(&num, &num1);
+ check(!int96_is_uint64(&num) && !int96_is_neg_int64(&num));
+ }
+ int96_add(&num, &num1);
+ check(int96_is_neg_int64(&num));
+ check(int96_extract_neg_int64(&num) == -a);
+ }
+
+ footer();
+}
+
+int
+main(int, const char **)
+{
+ test();
+}
diff --git a/test/unit/int96.result b/test/unit/int96.result
new file mode 100644
index 0000000000000000000000000000000000000000..081e0431ca2864f105d655ad0ec4b7c394ef0968
--- /dev/null
+++ b/test/unit/int96.result
@@ -0,0 +1,3 @@
+ *** test ***
+ *** test: done ***
+
\ No newline at end of file
diff --git a/test/unit/ipc.cc b/test/unit/ipc.cc
new file mode 100644
index 0000000000000000000000000000000000000000..c5812bbf90744b73442b3bea481480c995dea721
--- /dev/null
+++ b/test/unit/ipc.cc
@@ -0,0 +1,55 @@
+#include "memory.h"
+#include "fiber.h"
+#include "ipc.h"
+#include "unit.h"
+
+enum {
+ ITERATIONS = 100000,
+};
+
+void
+push_f(va_list ap)
+{
+ struct ipc_channel *channel = va_arg(ap, struct ipc_channel *);
+
+ for (int i = 0; i < ITERATIONS; i++)
+ ipc_channel_put(channel, NULL);
+}
+
+void
+pop_f(va_list ap)
+{
+ struct ipc_channel *channel = va_arg(ap, struct ipc_channel *);
+
+ for (int i = 0; i < ITERATIONS; i++)
+ (void) ipc_channel_get(channel);
+}
+
+void main_f(va_list ap)
+{
+ header();
+ struct fiber *push = fiber_new("push_f", push_f);
+ fiber_set_joinable(push, true);
+ struct fiber *pop = fiber_new("pop_f", pop_f);
+ fiber_set_joinable(pop, true);
+ struct ipc_channel *channel = ipc_channel_new(1);
+ fiber_start(push, channel);
+ fiber_start(pop, channel);
+ fiber_join(push);
+ fiber_join(pop);
+ ipc_channel_delete(channel);
+ ev_break(loop(), EVBREAK_ALL);
+ footer();
+}
+
+int main()
+{
+ memory_init();
+ fiber_init();
+ struct fiber *main= fiber_new("main", main_f);
+ fiber_wakeup(main);
+ ev_run(loop(), 0);
+ fiber_free();
+ memory_free();
+ return 0;
+}
diff --git a/test/unit/ipc.result b/test/unit/ipc.result
new file mode 100644
index 0000000000000000000000000000000000000000..f3398fb9c7731397e2535321288bd427198fba1e
--- /dev/null
+++ b/test/unit/ipc.result
@@ -0,0 +1,3 @@
+ *** main_f ***
+ *** main_f: done ***
+
\ No newline at end of file
diff --git a/test/xlog/xlog.lua b/test/xlog/xlog.lua
index ffe507f860771a457dbd6e3a0a67957d79c0529e..2041feb7c85ce43556df8351f065df579c9fcdf3 100644
--- a/test/xlog/xlog.lua
+++ b/test/xlog/xlog.lua
@@ -5,6 +5,7 @@ box.cfg{
listen = os.getenv("LISTEN"),
slab_alloc_arena = 0.1,
pid_file = "tarantool.pid",
+ panic_on_wal_error = false,
rows_per_wal = 50
}
diff --git a/third_party/coro/coro.c b/third_party/coro/coro.c
index a980561ce950b9a0f870ce069db95d32a0e68fd4..cb14846af5e38074153a1b40286767172479f227 100644
--- a/third_party/coro/coro.c
+++ b/third_party/coro/coro.c
@@ -123,7 +123,7 @@ trampoline (int sig)
asm (
"\t.text\n"
- #if _WIN32 || __CYGWIN__
+ #if _WIN32 || __CYGWIN__ || __APPLE__
"\t.globl _coro_transfer\n"
"_coro_transfer:\n"
#else