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/doc/sphinx/.gitignore b/doc/sphinx/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..803a390878133a4b2156b4e85eedae407043a82c --- /dev/null +++ b/doc/sphinx/.gitignore @@ -0,0 +1,2 @@ +!Makefile +!.gitignore diff --git a/doc/sphinx/Makefile b/doc/sphinx/Makefile new file mode 100644 index 0000000000000000000000000000000000000000..9789a4c80aa17832ae2c053de47f9337cdc1da4c --- /dev/null +++ b/doc/sphinx/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Tarantool.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Tarantool.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Tarantool" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Tarantool" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/doc/sphinx/_build/.gitignore b/doc/sphinx/_build/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..803a390878133a4b2156b4e85eedae407043a82c --- /dev/null +++ b/doc/sphinx/_build/.gitignore @@ -0,0 +1,2 @@ +!Makefile +!.gitignore 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/_templates/.gitignore b/doc/sphinx/_templates/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..803a390878133a4b2156b4e85eedae407043a82c --- /dev/null +++ b/doc/sphinx/_templates/.gitignore @@ -0,0 +1,2 @@ +!Makefile +!.gitignore diff --git a/doc/www/content/doc/box-protocol.rst b/doc/sphinx/box-protocol.rst similarity index 97% rename from doc/www/content/doc/box-protocol.rst rename to doc/sphinx/box-protocol.rst index 13e2c1c228dc46e3e213db5e36ccc566023af64f..0714b32860ddbbdcad8538ce02c040818fe5af93 100644 --- a/doc/www/content/doc/box-protocol.rst +++ b/doc/sphinx/box-protocol.rst @@ -5,9 +5,13 @@ :template: old_documentation -------------------------------------------------------------------------------- - Notion in diagrams + IProto Protocol -------------------------------------------------------------------------------- +================================================================================ + Notion in diagrams +================================================================================ + .. code-block:: bash 0 X @@ -37,15 +41,15 @@ MsgPack data types: * **MP_OBJECT** - Any MsgPack object --------------------------------------------------------------------------------- +================================================================================ Overview --------------------------------------------------------------------------------- +================================================================================ IPROTO is a binary request/response protocol. --------------------------------------------------------------------------------- +================================================================================ Greeting Package --------------------------------------------------------------------------------- +================================================================================ .. code-block:: bash @@ -68,9 +72,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 --------------------------------------------------------------------------------- +================================================================================ Once a greeting is read, the protocol becomes pure request/response and features a complete access to Tarantool functionality, including: @@ -201,9 +205,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 @@ -366,9 +370,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 +415,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 @@ -484,9 +488,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/conf.py b/doc/sphinx/conf.py new file mode 100644 index 0000000000000000000000000000000000000000..55a64bcfb1d5dbb2b54d63603913a46ff506aa95 --- /dev/null +++ b/doc/sphinx/conf.py @@ -0,0 +1,262 @@ +# -*- 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.mathjax', + 'sphinx.ext.ifconfig', +] + +# 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'2014, 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 short X.Y version. +version = '1.6' +# The full version, including alpha/beta/rc tags. +release = '1.6.3' + +# 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'] + +# 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 = True + +# 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/www/content/doc/faq.rst b/doc/sphinx/faq.rst similarity index 89% rename from doc/www/content/doc/faq.rst rename to doc/sphinx/faq.rst index 37cdebadf061fab97454372d3e65254fecefa876..81f36ed088caa667d82c3b14556db0a25c9dac52 100644 --- a/doc/www/content/doc/faq.rst +++ b/doc/sphinx/faq.rst @@ -1,7 +1,6 @@ :title: FAQ's :slug: faq -:save_as: doc/faq.html -:template: old_documentation +:save_as: faq.html ------------------------------------------------------------------------------- Frequently Asked Questions @@ -26,9 +25,9 @@ **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. + Tarantool provides a rich database feature set (HASH, TREE BITSET indexes, + secondary indexes, composite indexes, asynchronous replication, hot standby, + data durability) 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 @@ -41,7 +40,7 @@ :: We continuously improve server performance. On the feature front, automatic - sharding and online upgrade are the two major goals of 2015. + sharding and online upgrade are the two major goals of 2014. **Who is developing Tarantool?** :: diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..52e94a21666d07515b9f08996cea056c17fa251b --- /dev/null +++ b/doc/sphinx/index.rst @@ -0,0 +1,24 @@ +===================================== + Documentation +===================================== + +.. toctree:: + :maxdepth: 2 + + box-protocol.rst + faq.rst + +Contents: + + * `User Guide (Multi page HTML) </doc/user_guide/>`_ + * `User Guide (Single page HTML) </doc/user_guide.html>`_ + * `FAQ </faq.html>`_ + * `Developer Guide </doc/dev_guide.html>`_ + +===================================== + Indices and tables +===================================== + +* :ref:`genindex` +* :ref:`search` + diff --git a/doc/sphinx/preface.rst b/doc/sphinx/preface.rst new file mode 100644 index 0000000000000000000000000000000000000000..3f9b16f51ca099a9f0c9e7c5c61664a9a27f0e5f --- /dev/null +++ b/doc/sphinx/preface.rst @@ -0,0 +1,142 @@ +------------------------------------------------------------------------------- + Preface +------------------------------------------------------------------------------- + +=========================================================== + 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 <http://www.gnu.org/licenses/license-list.html#ModifiedBSD>`_. +The supported platforms are GNU/Linux, Mac OS and FreeBSD. + +Tarantool's creator and biggest user is `Mail.Ru <https://en.wikipedia.org/wiki/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 <http://www.alexa.com/siteinfo/mail.ru>`_ +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. + +Users can create, modify and drop **Lua functions** at runtime. Or they can define +**Lua programs** 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 **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 is lock-free**. 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%. + +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. + +Ordinarily the server **keeps all the data in random-access memory**, and therefore has +very low read latency. The server **keeps persistent copies of the data in non-volatile +storage**, such as disk, when users request "snapshots". The server **maintains a +write-ahead log (WAL)** to ensure consistency and crash safety of the persistent copies. +The server **performs inserts and updates atomically** -- changes are not considered +complete until the WAL is written. The logging subsystem supports group commit. + +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 **snapshots are quick, resource-savvy, and non-blocking**. 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. + +Unlike most NoSQL DBMSs, Tarantool supports **secondary index keys and multi-part index keys** +as well as primary keys. The possible index types are HASH, TREE, and BITSET. + + +Tarantool supports **asynchronous replication**, locally or to remote hosts. In this latest +version 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. + +=========================================================== + Conventions +=========================================================== + +This manual is written in `ReStructuredText <http://docutils.sourceforge.net/rst.html>`_ +markup language + +UNIX shell command input is prefixed with '$ ' and is in a fixed-width font: +:code:`$ tarantool --help` + +File names are also in a fixed-width font: :file:`/path/to/var/dir` + +Text that represents user input is in boldface: :samp:`$ {your input here}` + +Within user input, replaceable items are in italics: :samp:`$ tarantool {--option}` + +=========================================================== + How to read the documentation +=========================================================== + +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 http://try.tarantool.org. Either way, the first tryout can be a matter +of following the example in the second part of chapter 2: "Starting Tarantool +and making your first database". + +Chapter 3 "Lua and the Tarantool Lua packages" 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. + +Chapter 4 "Databases" 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 "Replication") will not be +necessary. Once again, the detailed instructions about each package can be +regarded as reference material. + +Chapter 6 "Server administration" and Chapter 7 "Configuration reference" are +primarily for administrators; however, every user should know something about +how the server is configured so the section about :code:`box.cfg` is not skippable. +Chapter 8 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. + +The two long tutorials in Appendix B -- "Insert one million tuples with a Lua +stored procedure" and "Sum a JSON field for all tuples" -- start slowly and +contain commentary that is especially aimed at users who may not consider +themselves experts at either Lua or NoSQL database management. + +Finally, Appendix C "Plugins" has examples that will be essential for those +users who want to connect the Tarantool server to another DBMS: MySQL or PostgreSQL. + +For experienced users, there is also a developer's guide and an extensive set of +comments in the source code. + +=========================================================== + Reporing Bugs +=========================================================== + +Please report bugs in Tarantool at http://github.com/tarantool/tarantool/issues/. +You can contact developers directly on the +`#tarantool <irc://irc.freenode.net#tarantool>`_ IRC channel on freenode, or via +a mailing list, `Tarantool Google group <https://googlegroups.com/group/tarantool>`_ 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 > -->