From d87b5b3bb686546d8c5fc312458345e32ddb6593 Mon Sep 17 00:00:00 2001
From: ocelot-inc <pgulutzan@ocelot.ca>
Date: Fri, 18 Jul 2014 17:00:09 -0600
Subject: [PATCH] nine xml files, renaming and adding
---
doc/user/configuration-reference.xml | 20 +++---
doc/user/connectors.xml | 19 +++---
doc/user/databases.xml | 92 +++++++++++++++++++++++-----
doc/user/lua-and-packages.xml | 2 +-
doc/user/proctitle.xml | 7 +--
doc/user/replication.xml | 2 +-
doc/user/server-administration.xml | 8 +--
doc/user/stored-procedures.xml | 4 +-
doc/user/tutorial.xml | 8 +--
9 files changed, 114 insertions(+), 48 deletions(-)
diff --git a/doc/user/configuration-reference.xml b/doc/user/configuration-reference.xml
index ca291be974..7996ee6067 100644
--- a/doc/user/configuration-reference.xml
+++ b/doc/user/configuration-reference.xml
@@ -95,8 +95,8 @@ The Lua program almost always begins by invoking <code>box.cfg()</code>,
if the database server will be used or if ports need to be opened.
For example, suppose <filename>script.lua</filename> contains the lines<programlisting>#!/usr/bin/env tarantool
box.cfg{
- primary_port = os.getenv("PRIMARY_PORT"),
- admin_port = os.getenv("ADMIN_PORT"),
+ listen = os.getenv("LISTEN"),
+ admin = os.getenv("ADMIN"),
slab_alloc_arena = 0.1,
pid_file = "tarantool.pid",
rows_per_wal = 50
@@ -112,7 +112,7 @@ Then the screen might look like this:<programlisting>
2014-07-02 10:19:29.086 ... initialized
2014-07-02 10:19:29.101 ... recovery start
2014-07-02 10:19:29.107 ... bound to primary port tcp://0.0.0.0:3303
-2014-07-02 10:19:29.108 ... I am primary
+2014-07-02 10:19:29.108 ... ready to accept requests
Starting ARG
2014-07-02 10:19:29.108 ... entering the event loop</programlisting>
</para>
@@ -138,7 +138,7 @@ Starting ARG
</para>
<para>
To see all the non-null parameters, say <code>box.cfg</code> (no parentheses).
- To see a particular parameter, for example the primary port, say <code>box.cfg.primary_port</code>.
+ To see a particular parameter, for example the listen address, say <code>box.cfg.listen</code>.
</para>
<para>
The following tables describe all parameters for basic operation,
@@ -212,7 +212,7 @@ Starting ARG
<entry>Deprecated. Do not use.</entry>
</row>
<row>
- <entry xml:id="primary_port" xreflabel="primary_port">primary_port</entry>
+ <entry xml:id="primary_port" xreflabel="primary_port">listen</entry>
<entry>integer or string</entry>
<entry>null</entry>
<entry>no</entry>
@@ -220,7 +220,7 @@ Starting ARG
Has no default value, so <emphasis
role="strong">must be specified</emphasis>
if connections will occur from remote clients
- that do not use admin_port.
+ 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.
@@ -228,7 +228,7 @@ Starting ARG
</row>
<row>
- <entry xml:id="admin_port" xreflabel="admin_port">admin_port</entry>
+ <entry xml:id="admin_port" xreflabel="admin_port">admin</entry>
<entry>integer or string</entry>
<entry>null</entry>
<entry>no</entry>
@@ -472,7 +472,7 @@ tarantool: primary@sessions pri: 3303 adm: 3313</programlisting>
For example, if replication_source = "1.2.3.4:55555" then
the replica server tries to connect to 1.2.3.4 port 55555.
A replica server does not accept updates
- on <olink targetptr="primary_port"/>. This parameter is
+ on <olink targetptr="primary_port">listen</olink>. This 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}".</entry>
@@ -643,8 +643,8 @@ tarantool: primary@sessions pri: 3303 adm: 3313</programlisting>
instances of the server using the same configuration file.
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 primary_port
- and admin_port, but will fail because the
+ The standby instance will initialize and will try to connect on listen
+ address and admin address, but will fail because the
primary instance has already taken them.
So the standby instance goes into a loop, reading the write
ahead log which the primary instance is writing (so the
diff --git a/doc/user/connectors.xml b/doc/user/connectors.xml
index 44e2617814..65d6cf65be 100644
--- a/doc/user/connectors.xml
+++ b/doc/user/connectors.xml
@@ -113,7 +113,8 @@ And that is why APIs exist for drivers for C, Perl, Python, PHP, Ruby, and so on
the necessary file <filename>tp.h</filename>, and the default library path contains
the directory where Tarantool library files were placed at installation time.
Before trying to run, check that the server
- (tarantool) is running on localhost (127.0.0.1) and its primary port is the default (3303) and
+ (tarantool) is running on localhost (127.0.0.1) and its listen address is the default
+ (local host, port 3303) and
space[513]'s primary key type is numeric (space[513].index[0].key_field[1].type = "NUM").
To run, say <code>./example</code>.
The program will open a socket connection with the tarantool server at localhost:3303,
@@ -219,14 +220,15 @@ sudo cpan install DR::Tarantool
<para>
Here is a complete Perl program that inserts [99999,'BB'] into space[0] via the Perl API.
Before trying to run, check that the server
- (tarantool) is running on localhost (127.0.0.1) and its primary port is the default (3303) and
+ (tarantool) is running on localhost (127.0.0.1) and its listen address is the default
+ (local host, port 3303) and
space[0]'s primary key type is numeric (space[0].index[0].key_field[1].type = "NUM" in configuration file).
To run, paste the code into a file named example.pl and say <code>perl example.pl</code>.
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:3303, then send an INSERT request,
then — if all is well — end without displaying any messages.
- If tarantool is not running on localhost with primary port = 3303, the program will print
+ If tarantool is not running on localhost with listen address = port 3303, the program will print
<quote>Connection refused</quote>.
</para>
<para>
@@ -237,7 +239,7 @@ use DR::Tarantool ':all';
my $tnt = tarantool
host => '127.0.0.1', # look for tarantool on localhost
- port => 3303, # assume tarantool primary port = default
+ port => 3303, # assume tarantool listen address = default
spaces => {
0 => { # definition of space[0] ...
name => 't0', # space[0] name = 't0'
@@ -295,7 +297,8 @@ export PHP_INI_SCAN_DIR=~/tarantool-php/test/share
<para>
Here is a complete PHP program that inserts [99999,'BB'] into space[0] via the PHP API.
Before trying to run, check that the server
- (tarantool) is running on localhost (127.0.0.1) and its primary port is the default (3303) and
+ (tarantool) is running on localhost (127.0.0.1) and its listen address is the default
+ (local host, port 3303) and
space[0]'s primary key type is numeric (space[0].index[0].key_field[1].type = "NUM" in configuration file).
To run, paste the code into a file named example.php and say <code>php example.php</code>.
The program will open a socket connection
@@ -333,11 +336,11 @@ catch (Exception $e) {
<userinput><code>pip install tarantool</code></userinput> to install in <filename>/usr</filename> (requires root privilege)
or
<userinput><code>pip install tarantool --user</code></userinput> to install in <filename>~</filename> i.e. user's default directory.
- The program is assuming that the server (tarantool) is running on localhost (127.0.0.1) and its primary port is
- the default (3303) and space99's primary key type is string (box.space.space99.index['primary'].key_field[1].type = "STR")
+ The program is assuming that the server (tarantool) is running on localhost (127.0.0.1) and its listen address is
+ the default (local host, port 3303) and space99's primary key type is string (box.space.space99.index['primary'].key_field[1].type = "STR")
and user 'guest' has permission to read and write on space99. An administrator could fulfill all those conditions by
starting the tarantool server and executing these requests:<programlisting>
-box.cfg{primary_port = 3303}
+box.cfg{listen = 3303}
box.schema.create_space('space99')
box.space.space99:create_index('primary',{parts = {1,'STR'}})
box.schema.user.grant('guest', 'read', 'space', '_space')
diff --git a/doc/user/databases.xml b/doc/user/databases.xml
index 57477de80f..77bd03ad48 100644
--- a/doc/user/databases.xml
+++ b/doc/user/databases.xml
@@ -1188,7 +1188,7 @@ session.delimiter('')!
<varlistentry>
<term>
<emphasis role="lua" xml:id="boxindexiterator" xreflabel="box.index.iterator(type, ...)">
- box.space.<replaceable>space-name</replaceable>.index.<replaceable>index-name</replaceable>]:iterator(<replaceable>iterator-type, bitset-value | field-value...</replaceable>)</emphasis>
+ box.space.<replaceable>space-name</replaceable>.index[.<replaceable>index-name</replaceable>]:pairs(<replaceable>bitset-value | field-value..., iterator-type</replaceable>)</emphasis>
</term>
<listitem>
<para>
@@ -1298,7 +1298,7 @@ session.delimiter('')!
<varlistentry>
<term>
<emphasis role="lua" xml:id="box.index.iterator" xreflabel="box.index.select(type, ...)">
- box.space.<replaceable>space-name</replaceable>.index.<replaceable>index-name</replaceable>]:select(<replaceable>{fields, {parameters}]</replaceable>)</emphasis>
+ box.space.<replaceable>space-name</replaceable>[.index.<replaceable>index-name</replaceable>]:select(<replaceable>{fields, {parameters}]</replaceable>)</emphasis>
</term>
<listitem>
<para>
@@ -1334,9 +1334,15 @@ The result will be a table of tuples and will look like this:
...
</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>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>
<emphasis role="lua">box.space.<replaceable>space-name</replaceable>.index.<replaceable>index-name</replaceable>:min([key])</emphasis>
@@ -2262,11 +2268,11 @@ session.delimiter('')!
<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.primary_port == 3303 then</userinput>
-<prompt> -></prompt><userinput> table.insert(ta,'The local server primary port number = 3303')</userinput>
+<prompt> -></prompt><userinput> if box.cfg.listen == '3303' then</userinput>
+<prompt> -></prompt><userinput> table.insert(ta,'The local server listen address = 3303')</userinput>
<prompt> -></prompt><userinput> else</userinput>
-<prompt> -></prompt><userinput> table.insert(ta, 'The local server primary port number is not 3303')</userinput>
-<prompt> -></prompt><userinput> table.insert(ta, '( (maybe box.cfg{...primary_port=3303...} was not stated)')</userinput>
+<prompt> -></prompt><userinput> table.insert(ta, 'The local server listen address is not 3303')</userinput>
+<prompt> -></prompt><userinput> table.insert(ta, '( (maybe box.cfg{...listen="3303"...} was not stated)')</userinput>
<prompt> -></prompt><userinput> table.insert(ta, '( (so connect will fail)')</userinput>
<prompt> -></prompt><userinput> end</userinput>
<prompt> -></prompt><userinput> conn = box.net.box.new('127.0.0.1', 3303)</userinput>
@@ -2297,7 +2303,7 @@ session.delimiter('')!
---
- - self:ping() succeeded
- ' (no surprise -- self connection is pre-established)'
- - The local server primary port number = 3303 = default
+ - The local server's listen address's port number = 3303 = default
- conn:delete done on tester.
- conn:insert done on tester, index 0
- ' primary key value = 800.'
@@ -3013,12 +3019,13 @@ error: can't save snapshot, errno 17 (File exists)
</variablelist>
</section>
-<section xml:id="sp-limitations">
-<title>A limitation that affects long-running Lua functions</title>
+<section xml:id="multitasking">
+<title>Atomic execution</title>
<para>
- There is a limitation in stored procedures support one should
- be aware of: execution atomicity.
+ 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>
@@ -3059,10 +3066,67 @@ error: can't save snapshot, errno 17 (File exists)
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.
+ </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 fiber.yield() will have the same effect.
+ </para></listitem>
+ </varlistentry>
+
+ </variablelist>
+
+<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>
+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()</programlisting>
+</para>
</section>
<section xml:id="errcode">
@@ -3388,7 +3452,7 @@ session.su(<replaceable>user-name</replaceable>) #allows changing current user
<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"/> instead of primary_port), then the user by default is 'admin' and has
+<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
diff --git a/doc/user/lua-and-packages.xml b/doc/user/lua-and-packages.xml
index 889d6551e2..3cdee6a4ef 100644
--- a/doc/user/lua-and-packages.xml
+++ b/doc/user/lua-and-packages.xml
@@ -5,7 +5,7 @@
<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">
+ xml:id="lua-and-packages">
<title>Lua and the Tarantool Lua Packages</title>
diff --git a/doc/user/proctitle.xml b/doc/user/proctitle.xml
index 5476dce8bc..fc2c90c1c9 100644
--- a/doc/user/proctitle.xml
+++ b/doc/user/proctitle.xml
@@ -42,18 +42,17 @@
</para></listitem>
</itemizedlist>
Possible port names are: <quote>pri</quote> for
- <olink targetptr="primary_port"/>, <quote>sec</quote> for <olink
- targetptr="secondary_port"/> and <quote>adm</quote> for <olink
+ <olink targetptr="primary_port">listen</olink>, and <quote>adm</quote> for <olink
targetptr="admin_port"/>.
</para>
<para>
For example:
<itemizedlist>
<listitem><para>
- <command>tarantool: primary pri: 50000 sec: 50001 adm: 50002</command>
+ <command>tarantool: primary pri: 50000 adm: 50002</command>
</para></listitem>
<listitem><para>
- <command>tarantool: primary@infobox pri: 15013 sec: 15523 adm: 10012</command>
+ <command>tarantool: primary@infobox pri: 15013 adm: 10012</command>
</para></listitem>
</itemizedlist>
</para>
diff --git a/doc/user/replication.xml b/doc/user/replication.xml
index 2c0dd16531..fd91426958 100644
--- a/doc/user/replication.xml
+++ b/doc/user/replication.xml
@@ -54,7 +54,7 @@
updates from the master having identical LSNs would
not be applied. In fact, if replication is ON, Tarantool
does not accept updates, even on its <olink
- targetptr="primary_port"/>.
+ targetptr="primary_port">"listen" address</olink>.
</para>
</section>
diff --git a/doc/user/server-administration.xml b/doc/user/server-administration.xml
index e65cf27445..fd79f4398b 100644
--- a/doc/user/server-administration.xml
+++ b/doc/user/server-administration.xml
@@ -61,7 +61,7 @@ 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 "admin_port=..." or "primary_port=..." so
+configuration information including "admin=..." or "listen=..." so
that a separate program can connect to the server via one of the ports.
</para>
<para>
@@ -161,7 +161,7 @@ Here is an example of an interactive-mode tarantool client session:
<programlisting>
<prompt>$ </prompt>tarantool
[ tarantool will display an introductory message including version number here ]
-tarantool> box.cfg{admin_port=3313, primary_port=3303}
+tarantool> box.cfg{admin=3313, listen=3303}
[ tarantool will display configuration information here ]
tarantool> s = box.schema.create_space('tester')
[ tarantool may display an in-progress message here ]
@@ -189,10 +189,10 @@ Explanatory notes about what tarantool displayed in the above example:
</para>
<para>
* Many requests return typed objects.
- In the case of "box.cfg{admin_port=3313, primary_port=3303}",
+ In the case of "box.cfg{admin=3313, listen=3303}",
this result is displayed on the screen.
If the request had assigned the result to a variable, for example
- "c = box.cfg{admin_port=3313, primary_port=3303}", then
+ "c = box.cfg{admin=3313, listen=3303}", then
the result would not have been displayed on the screen.
</para>
<para>
diff --git a/doc/user/stored-procedures.xml b/doc/user/stored-procedures.xml
index 7ec2ed0fef..7df0bb4226 100644
--- a/doc/user/stored-procedures.xml
+++ b/doc/user/stored-procedures.xml
@@ -451,8 +451,8 @@ tarantool> <userinput>box.space.tester:update({0}, {{'^', 2, 4}})</userinput>
(<link xlink:href="https://en.wikipedia.org/wiki/Cyclic_redundancy_check">CRC32</link>).
The functions in <code>digest</code> are:<programlisting><code> digest.crc32(<replaceable>string</replaceable>) Returns 32-bit checksum made with CRC32.
digest.crc32_update(<replaceable>number</replaceable>,<replaceable>string</replaceable>) Returns update of a checksum calculated with crc32.
- digest.sha0(<replaceable>string</replaceable>) Returns 160-bit digest made with SHA-0. Not recommended.
- digest.sha0_hex(<replaceable>string</replaceable>) Returns hexadecimal of a digest calculated with sha0.
+ digest.sha(<replaceable>string</replaceable>) Returns 160-bit digest made with SHA-0. Not recommended.
+ digest.sha_hex(<replaceable>string</replaceable>) Returns hexadecimal of a digest calculated with sha.
digest.sha1(<replaceable>string</replaceable>) Returns 160-bit digest made with SHA-1.
digest.sha1_hex(<replaceable>string</replaceable>) Returns hexadecimal of a digest calculated with sha1.
digest.sha224(<replaceable>string</replaceable>) Returns 224-bit digest made with SHA-2.
diff --git a/doc/user/tutorial.xml b/doc/user/tutorial.xml
index 184c5d3fbd..e900c30508 100644
--- a/doc/user/tutorial.xml
+++ b/doc/user/tutorial.xml
@@ -490,7 +490,7 @@ The server name is <computeroutput><filename>tarantool</filename></computeroutpu
<para>
The server starts in interactive mode and outputs a command prompt.
To turn on the database, configure it:
-<programlisting><prompt>tarantool></prompt> <userinput>box.cfg{admin_port=3313}</userinput></programlisting>
+<programlisting><prompt>tarantool></prompt> <userinput>box.cfg{admin=3313}</userinput></programlisting>
(this minimal example is sufficient).
</para>
@@ -508,7 +508,7 @@ If all goes well, you will see the server displaying progress as it initializes,
2014-06-10 11:53:41.095 ... 0.0M rows written
2014-06-10 11:53:41.126 ... done
2014-06-10 11:53:41.126 ... bound to admin port tcp://0.0.0.0:3313
-2014-06-10 11:53:41.127 ... I am primary
+2014-06-10 11:53:41.127 ... ready to accept requests
</programlisting>
</para>
@@ -637,8 +637,8 @@ inserted and selected tuples.
"script_dir" no longer exists, use #! instead (see below re "Tarantool = a shell script processor").
</para>
<para>CHANGES IN PORT CONFIGURATION.
- "secondary_port" no longer exists; use "primary_port".
- "replication_port" no longer exists; use "primary_port".
+ "secondary_port" no longer exists; use "listen".
+ "replication_port" no longer exists; use "listen".
"memcached" no longer exists (memcached is not supported).
The admin port is Lua-only now, and the lua prefix is gone.
</para>
--
GitLab