diff --git a/doc/user/configuration-reference.xml b/doc/user/configuration-reference.xml
index b547c08ce8f040f65102b7aeb824c96555d90501..bb3f805f7049a72418f24e752674819f55e27ae5 100644
--- a/doc/user/configuration-reference.xml
+++ b/doc/user/configuration-reference.xml
@@ -321,17 +321,6 @@ Tarantool 1.4.0-69-g45551dd
reads until the replica becomes a master.</entry>
</row>
- <row>
- <entry xml:id="secondary_port"
- xreflabel="secondary_port">secondary_port</entry>
- <entry>integer</entry>
- <entry>none</entry>
- <entry>no</entry>
- <entry>no</entry>
- <entry>Additional, read-only port. Normally set to
- 33014. Not used unless is set.</entry>
- </row>
-
<row>
<entry xml:id="admin_port" xreflabel="admin_port">admin_port</entry>
<entry>integer</entry>
@@ -446,22 +435,6 @@ tarantool_box: primary@sessions pri: 33013 sec: 33014 adm: 33015</programlisting
and the distribution of item sizes.</entry>
</row>
- <row>
- <entry>space</entry>
- <entry>array of objects</entry>
- <entry>none</entry>
- <entry><emphasis role="strong">yes</emphasis></entry>
- <entry><emphasis role="strong">no</emphasis></entry>
- <entry>This is the main Tarantool parameter, describing
- the data structure that users get access to via the
- client/server protocol. It holds an array of
- entries, and each entry describes a tuple set
- and its indexes. Every entry is a composite object,
- best seen as a C programming language "struct"
- <footnote><xi:include href="space.xml"/></footnote>.
- </entry>
- </row>
-
</tbody>
</tgroup>
</table>
@@ -535,7 +508,7 @@ tarantool_box: primary@sessions pri: 33013 sec: 33014 adm: 33015</programlisting
</row>
<row>
- <entry>wal_fsync_delay</entry>
+ <entry xml:id="wal_fsync_delay" xreflabel="wal_fsync_delay">wal_fsync_delay</entry>
<entry>float</entry>
<entry>0</entry>
<entry>no</entry>
diff --git a/doc/user/data-model.xml b/doc/user/data-model.xml
index 511b501181018cab68f0f57d5ee08153679e1456..0e369a74d787279baa03b2dc110f39f634590eaa 100644
--- a/doc/user/data-model.xml
+++ b/doc/user/data-model.xml
@@ -270,7 +270,7 @@ so advanced users may be able to start a second Tarantool
server on the same processor without ill effects.
</para>
<para>
- Additional examples of data-manipulation requests can be found in the <citetitle
+ Additional examples of SQL statements 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
diff --git a/doc/user/lua-tutorial.xml b/doc/user/lua-tutorial.xml
index 07bf19e5b68659c4121ed6ab06fa51b73299967f..a1c41ad89ef9a400fbb4f64a7c85f6570750f018 100644
--- a/doc/user/lua-tutorial.xml
+++ b/doc/user/lua-tutorial.xml
@@ -153,7 +153,7 @@ so that, instead of returning a fixed literal 'Hello world", it returns a random
lua function string_function()
local random_number
local random_string
- random_number = math.random(65,90)
+ random_number = math.random(65, 90)
random_string = string.char(random_number)
return random_string
end!
@@ -184,7 +184,7 @@ The screen now looks like this:
localhost> <userinput>lua function string_function()</userinput>
-> <userinput>local random_number</userinput>
-> <userinput>local random_string</userinput>
- -> <userinput>random_number = math.random(65,90)</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>
@@ -209,7 +209,7 @@ lua function string_function()
local random_string
random_string = ""
for x = 1,10,1 do
- random_number = math.random(65,90)
+ random_number = math.random(65, 90)
random_string = random_string .. string.char(random_number)
end
return random_string
@@ -238,7 +238,7 @@ localhost> <userinput>lua function string_function()</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_number = math.random(65, 90)</userinput>
-> <userinput>random_string = random_string .. string.char(random_number)</userinput>
-> <userinput>end</userinput>
-> <userinput>return random_string</userinput>
@@ -262,7 +262,7 @@ a function in Tarantool's library of Lua functions.
lua function main_function()
local string_value
string_value = string_function()
- t = box.tuple.new({1,string_value})
+ t = box.tuple.new({1, string_value})
return t
end!
</programlisting>
@@ -286,7 +286,7 @@ The screen now looks like this:
localhost> <userinput>lua 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>t = box.tuple.new({1, string_value})</userinput>
-> <userinput>return t</userinput>
-> <userinput>end!</userinput>
---
@@ -308,14 +308,14 @@ the first space that was defined in the configuration file, so it's like a datab
lua function main_function()
local string_value
string_value = string_function()
- t = box.tuple.new({1,string_value})
- box.replace(0,t)
+ t = box.tuple.new({1, string_value})
+ box.replace(0, t)
end!
</programlisting>
-The new line here is box.replace(0,t). The first parameter is 0, because the
+The new line here is box.replace(0, t). The first parameter is 0, because the
insertion is going to be to space[0]. The second parameter is the tuple value.
-To be perfectly correct we could have said box.insert(0,t) here, rather than
-box.replace(0,t), but "replace" means <quote>insert even if there is already a tuple
+To be perfectly correct we could have said box.insert(0, t) here, rather than
+box.replace(0, 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.
@@ -344,8 +344,8 @@ The screen now looks like this:
localhost> <userinput>lua 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.replace(0,t)</userinput>
+ -> <userinput>t = box.tuple.new({1, string_value})</userinput>
+ -> <userinput>box.replace(0, t)</userinput>
-> <userinput>end!</userinput>
---
...
@@ -373,8 +373,8 @@ lua function main_function()
start_time = os.clock()
for i = 1,1000000,1 do
string_value = string_function()
- t = box.tuple.new({i,string_value})
- box.replace(0,t)
+ t = box.tuple.new({i, string_value})
+ box.replace(0, t)
end
end_time = os.clock()
end!
@@ -411,7 +411,7 @@ lua function string_function()
local random_string
random_string = ""
for x = 1,10,1 do
- random_number = math.random(65,90)
+ random_number = math.random(65, 90)
random_string = random_string .. string.char(random_number)
end
return random_string
@@ -422,8 +422,8 @@ lua function main_function()
start_time = os.clock()
for i = 1,1000000,1 do
string_value = string_function()
- t = box.tuple.new({i,string_value})
- box.replace(0,t)
+ t = box.tuple.new({i, string_value})
+ box.replace(0, t)
end
end_time = os.clock()
end!
@@ -440,7 +440,7 @@ localhost> <userinput>lua function string_function()</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_number = math.random(65, 90)</userinput>
-> <userinput>random_string = random_string .. string.char(random_number)</userinput>
-> <userinput>end</userinput>
-> <userinput>return random_string</userinput>
@@ -452,8 +452,8 @@ localhost> <userinput>lua function main_function()</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.replace(0,t)</userinput>
+ -> <userinput>t = box.tuple.new({i, string_value})</userinput>
+ -> <userinput>box.replace(0, t)</userinput>
-> <userinput>end</userinput>
-> <userinput>end_time = os.clock()</userinput>
-> <userinput>end!</userinput>
@@ -493,20 +493,8 @@ 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>
-</para>
-
-<para>
-The purpose of the exercise is to show one way to read and process tuples.
-This is harder than the first exercise because the function is useful.
-A function which is useful, and therefore is going to be used more than
-once by more than one person, has to be robust and understandable.
-So here is the function. It's best to start by looking at each line --
-there are only twelve lines so it will only take a few minutes to guess what they do.
-Then it will take somewhat longer to read the detailed
-comments about the function, and follow the links wherever necessary.
-Once again, to further enhance learning, type the statements
-in with the tarantool client while reading along. At the very end there
-is an example that shows how to make a few tuples and invoke the function.
+The purpose of the exercise is to get experience in one way
+to read and process tuples.
</para>
<programlisting language="lua">
@@ -527,22 +515,6 @@ lua function sum_json_field(field_name)
SETOPT DELIMITER=''!
</programlisting>
-<para>
-SPACES. There is one space after every comma (line 3, line 5). There is one space
-before and one space after every operator such as '<code>=</code>' or '<code>==</code>' or '<code>+</code>' (line 2,
-line 3, line 5, line 7, line 8). There are no spaces around parentheses.
-Each indentation is two spaces (actually Tarantool developers often use four
-spaces but we follow the unofficial <link xlink:href="http://lua-users.org/wiki/LuaStyleGuide">Lua Style Guide</link> here).
-Indentation starts within a function, and within every block that is introduced
-by "<code>for</code>" or "<code>if</code>", and ends when the block ends with "<code>end</code>" (lines 4 to 10, lines 6 to 9).
-</para>
-
-<para>
-COMMENTS. Every comment begins with "<code>--[[</code>" and ends with "<code>]]</code>". Although this example uses comments to
-indicate line numbers, the normal practice is to put comments when the
-meaning of the code would not be clear by merely looking at the code.
-</para>
-
<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,
@@ -553,23 +525,6 @@ that are declared in line 1, because all of them are for use only within the
function.
</para>
-<para>
-LINE 1: NAMES. Single-letter variable names like <code>'v</code>' are okay when they're
-strictly for use as an iterator -- '<code>v</code>' is going to be the thing that goes
-up in the "<code>for t in v do</code>" statement in line 4. Terse names like '<code>sum</code>'
-are okay for local variables when there's only one sum and the name is
-not an abbreviation. The prefix "is_" in the name "<code>is_valid_json</code>" is
-there because the variable will get a Boolean (true/false) value and
-will be true only for a string that "is valid [according to] JSON [format rules]".
-</para>
-
-<para>
-LINE 2: INITIALIZING. The only variable that needs initializing is <code>sum</code>, which
-must start at zero, so line 2 is "<code>sum = 0</code>". It's easier to do initialization
-on the declaration line, that is, we could have said "<code>local sum = 0</code>". We
-chose to put it on a separate line to make sure that it's visible.
-</para>
-
<para>
LINE 3: WHY INDEX ITERATOR". Our job is to go through all the rows and there are two ways
to do it: with <olink targetptr="box.select_range">box.select_range()</olink> or with
@@ -578,12 +533,6 @@ index[].iterator because it works regardless of the index type, that is,
it works with HASH, TREE, and BITSET indexes.
</para>
-<para>
-LINE 3: MEANING. The value zero is hard-coded so this will only work for space[0]
-and index[0] -- we're making some hopeful assumptions here. The meaning is "variable <code>v</code> gets
-the iterator for the primary index of the first space".
-</para>
-
<para>
LINE 4: 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
@@ -602,7 +551,7 @@ will know what to do about it later.
<para>
LINE 5: MEANING. The function is <olink targetptr="box.cjson">box.cjson.decode</olink> which means decode a JSON
string, and the parameter is <code>t[1]</code> which is a reference to a JSON string.
-Once again there's a bit of hard coding here, we're assuming that the second
+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[0]: 444
field[1]: '{"Hello": "world", "Quantity": 15}'
</programlisting>meaning that the tuple's first field, the primary key field, is a number
@@ -613,13 +562,6 @@ set <code>is_valid_json = true</code> and set <code>lua_table</code> = a Lua tab
decoded string".
</para>
-<para>
-LINE 6. This "<code>if</code>" statement means "if the <code>box.cjson.decode</code> function failed,
-don't execute the next indented lines", so <code>sum</code> will be unchanged if
-<code>box.cjson.decode</code> failed. Although "<code>if is_valid_json == true</code>" would be clearer, the
-usual style is to say "<code>if is_valid_json</code>" and let "<code>== true</code>" be assumed.
-</para>
-
<para>
LINE 7. At last we are ready to get the JSON field value from the Lua
table that came from the JSON string.
@@ -638,42 +580,11 @@ LINE 8: 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.
-Again, as in line 5, this is slightly paranoid -- anyone who knows
-that the database is in perfect shape can skip this kind of thing.
-Incidentally the "<code>if ... end</code>" statement is so short that it fits on
-a single line, which is acceptable but optional practice.
+Anyone who knows that the database is in perfect shape can skip this kind of thing.
</para>
<para>
-LINE 8: MEANING. The meat, the whole reason for the function's existence,
-is in the words "<code>sum = sum + field_value</code>". This addition of <code>field_value</code>
-to <code>sum</code> will happen for every tuple, provided the field is there and is
-numeric.
-</para>
-
-<para>
-LINE 9. This "<code>end</code>" statement matches the "<code>if is_valid_json</code>" statement
-in line 6.
-</para>
-
-<para>
-LINE 10. This "<code>end</code>" statement matches the "<code>for t in v do</code>" statement
-in line 4. The effect is that another iteration of the loop will take
-place, unless there are no more tuples.
-</para>
-
-<para>
-LINE 11: This is after the end of the "<code>for t in v do</code>" loop. Return <code>sum</code> to the caller.
-This effectively ends the execution of the whole function, so all the
-local variables are destroyed and the function's caller gets the result.
-</para>
-
-<para>
-LINE 12: This "<code>end</code>" statement matches the start of the function.
-</para>
-
-<para>
-And the function is complete. Time to test it.
+And the function is complete. It's time to test it.
Starting with an empty database, defined the same way as the
sandbox database that was introduced in
<olink
@@ -696,8 +607,8 @@ Therefore the real sum of the Quantity field in the JSON strings should be:
<para>
Invoke the function with either <code>CALL sum_json_field("Quantity")</code> or
<code>lua sum_json_field("Quantity")</code>.
-<programlisting language="lua">
<prompt>localhost></prompt> <userinput>lua sum_json_field("Quantity")</userinput>
+<programlisting>
---
- 22
...
@@ -711,12 +622,6 @@ 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>
-<para>
-What has been shown is that a 12-line Lua function can scan a database and
-process JSON strings, in a way that's useful, robust, and -- now that
-this tutorial exercise is over -- understandable.
-</para>
-
</section>
</appendix>
@@ -725,3 +630,4 @@ this tutorial exercise is over -- understandable.
vim: tw=66 syntax=docbk
vim: spell spelllang=en_us
-->
+
diff --git a/doc/user/plugins.xml b/doc/user/plugins.xml
index 4c36b7960daa67a811ecbaafe557c4bc4ffae3bd..e37342ca568a1dba4515b928d998171e47d71eb1 100644
--- a/doc/user/plugins.xml
+++ b/doc/user/plugins.xml
@@ -72,9 +72,10 @@ OK
OK
# Check that the mysql client can connect using some factory defaults:
-# port = 3306, user = 'root', user password = '', database = 'test'.
+# port = 3306, user = 'root', user password = 'root', database = 'test'.
+# (Do not use a blank password.)
# These can be changed, provided one changes them in all places.
-<prompt>$ </prompt><userinput>~/mysql-5.5/bin/mysql --port=3306 -h 127.0.0.1 --user=root --database=test</userinput>
+<prompt>$ </prompt><userinput>~/mysql-5.5/bin/mysql --port=3306 -h 127.0.0.1 --user=root --password=root--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)
@@ -111,6 +112,7 @@ Bye
<prompt>$ </prompt><userinput>make</userinput>
...
[ 49%] Built target core
+Scanning dependencies of target mysql
[ 50%] Building CXX object src/plugin/mysql/CMakeFiles/mysql.dir/mysql.cc.o
Linking CXX shared library libmysql.so
[ 50%] Built target mysql
@@ -119,17 +121,42 @@ Linking CXX shared library libmysql.so
[100%] Built target man
<prompt>$ </prompt>
-# Before starting Tarantool server, tell it where the MySQL plugin is.
-<prompt>$ </prompt><userinput>export TARANTOOL_PLUGIN_DIR=~/tarantool-stable/src/plugin/mysql</userinput>
-<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/tarantool/1.5/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 contains the tarantool.cfg file.
+# For this example we assume that the name of this directory is
+# /home/pgulutzan/tarantool_test. (Change "/home/pgulutzan" to whatever
+# is the actual base directory for the machine that's used for this test.)
+# Edit the tarantool.cfg file and add this line:
+# script_dir = "/home/pgulutzan/tarantool_test"
+# The script_dir is the directory where the init.lua file must be.
+# Now create a file named /home/pgulutzan/tarantool_test/init.lua
+# and put the following lines in it (again, change "/home/pgulutzan"
+# to whatever the real directory is that contains tarantool-stable):
+package.path = "/home/pgulutzan/tarantool-stable/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")
+
+# Now, to help tarantool_box find the essential mysql.so file, execute these lines:
+<userinput>cd /home/pgulutzan/tarantool_test</userinput>
+<userinput>mkdir box</userinput>
+<userinput>mkdir box/net</userinput>
+<userinput>cp ~/tarantool-stable/src/module/mysql/mysql.so ./box/net/mysql.so</userinput>
# Start the Tarantool server.
# Run it in the background but let the initial display be in the foreground.
# So it's possible to see the message that the plugin was loaded.
<prompt>$ </prompt><userinput>~/tarantool-stable/src/box/tarantool_box&</userinput>
2013-12-03 17:46:16.239 [12957] 1/sched C> version 1.5.1-271-g610930e
-... Loading plugin: ~/tarantool-stable/src/plugin/mysql/libmysql.so ...
-... Plugin 'mysql' was loaded, version: 1
+... loading /home/pgulutzan/tarantool_test/init.lua ...
...
2013-12-03 17:46:16.244 [12957] 1/sched C> entering event loop
@@ -137,25 +164,20 @@ Linking CXX shared library libmysql.so
<prompt>$ </prompt><userinput>~/tarantool-stable/client/tarantool/tarantool</userinput>
<prompt>localhost> </prompt>
-# Say <quote>show plugins</quote>. Since all has gone well, this is certain to work.
-<prompt>localhost> </prompt> <userinput>show plugins</userinput>
----
-plugins:
- - { name: "mysql", version: 1 }
-...
-
# Create a Lua function that will connect to the MySQL 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>localhost> </prompt><userinput>SETOPT delimiter = '!'</userinput>
<prompt>localhost> </prompt><userinput>lua function mysql_select ()</userinput>
+ <prompt>-> </prompt><userinput> local resulter</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> 'mysql', '127.0.0.1', 3306, 'root', 'root', 'test')</userinput>
<prompt>-> </prompt><userinput> local test = dbh:select('SELECT * FROM test WHERE s1 = 1')</userinput>
<prompt>-> </prompt><userinput> for i, card in pairs(test) do</userinput>
- <prompt>-> </prompt><userinput> print(card.s2)</userinput>
+ <prompt>-> </prompt><userinput> resulter = card.s2</userinput>
<prompt>-> </prompt><userinput> end</userinput>
+ <prompt>-> </prompt><userinput> return resulter</userinput>
<prompt>-> </prompt><userinput> end!</userinput>
---
...
@@ -164,8 +186,9 @@ plugins:
# Execute the Lua function.
<prompt>localhost> </prompt><userinput>CALL mysql_select()</userinput>
-2013-12-03 17:57:24.688 [12957] 102/iproto I> MySQL row
-Call OK, 0 rows affected
+localhost> CALL mysql_select()
+Call OK, 1 rows affected
+['MySQL row']
# Observe the result. It contains "MySQL row".
# So this is the row that was inserted into the MySQL database.
@@ -174,8 +197,9 @@ Call OK, 0 rows affected
<para xml:id="plugin-postgresql-example">
<bridgehead renderas="sect4">PostgreSQL Example</bridgehead>
+Warning: This example is obsolete; a new example is being prepared to replace it.
This example assumes that a recent version of PostgreSQL has been installed.
-The PostgreSQL library library and include files are also necessary.
+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
diff --git a/doc/user/stored-procedures.xml b/doc/user/stored-procedures.xml
index ce325afa57f02ebb851d4fa0faf866508d5d329e..6f260dff6f12a55b5e43350e8abd806cca8eb8e6 100644
--- a/doc/user/stored-procedures.xml
+++ b/doc/user/stored-procedures.xml
@@ -317,14 +317,50 @@ localhost> <userinput>lua type(i), i / 2, i - 2, i * 2, i + 2, i % 2, i ^ 2</use
</tbody>
</tgroup>
</table>
- A tuple is returned in binary format (like <code>12345: {'A B C'}</code>) if
- the function is called via the administrative port; a tuple is returned in
- YAML format (like <code>[12345, 'A B C']</code>) if the function is called
- from the primary port; a few functions may return multiple tuples;
- for more tuple examples see <code xlink:href="#box.tuple">box.tuple</code>.
- A scalar may be converted to a tuple with only one field.
- A Lua table may contain all of a tuple's fields except the "key" (the primary-key fields).
+ When a function returns a tuple, the tarantool client may display it as
+ <code>12345: {'A B C'}</code> if the call is from the administrative port,
+ or as <code>[12345, 'A B C']</code> if the call is from the primary port.
+ A few functions may return multiple tuples.
+ For more tuple examples see <code xlink:href="#box.tuple">box.tuple</code>.
</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_range, can retrieve
+ multiple tuples. This factor is usually less
+ important than the others.</entry></row>
+ <row><entry>WAL settings</entry> <entry>The important settings for the write-ahead log are
+ wal_fsync_delay and <olink targetptr="wal_mode"/>.
+ If the settings cause no writing or delayed writing,
+ this factor is unimportant. If the settings cause
+ 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>
+
</section>
<section xml:id="sp-box">
@@ -399,6 +435,9 @@ localhost> <userinput>lua type(i), i / 2, i - 2, i * 2, i + 2, i % 2, i ^ 2</use
<para>
Returns: (type = tuple) zero or more tuples.
</para>
+ <para>
+ Complexity Factors: Index size, Index type.
+ </para>
<para>
Possible Errors: Same as in <code>box.process()</code>. Any error
results in a Lua exception.
@@ -437,6 +476,9 @@ localhost> <userinput>lua box.select(5, 1, 'first_name', 'last_name')</userinput
<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: If a tuple with the same primary key already exists,
<code>box.insert()</code> returns an error ER_TUPLE_FOUND.
@@ -465,6 +507,9 @@ localhost> <userinput>lua box.select(5, 1, 'first_name', 'last_name')</userinput
<para>
Returns: (type = tuple) zero or more tuples.
</para>
+ <para>
+ Complexity Factors: Index size, Index type, Number of tuples accessed.
+ </para>
</listitem>
</varlistentry>
@@ -486,6 +531,9 @@ localhost> <userinput>lua box.select(5, 1, 'first_name', 'last_name')</userinput
<para>
Returns: (type = tuple) the inserted tuple.
</para>
+ <para>
+ Complexity Factors: Index size, Index type, Number of indexes accessed, WAL settings.
+ </para>
</listitem>
</varlistentry>
@@ -530,6 +578,9 @@ localhost> <userinput>lua box.select(5, 1, 'first_name', 'last_name')</userinput
<para>
Returns: (type = tuple) the updated tuple.
</para>
+ <para>
+ Complexity Factors: Index size, Index type, number of indexes accessed, WAL settings.
+ </para>
<para>
<bridgehead renderas="sect4">Example</bridgehead>
<programlisting>
@@ -619,6 +670,9 @@ lua box.update(0, 999, ':p', 1, box.pack('ppp', 1, 1, '!'))
</para>
<para>
Returns: (type = tuple) the deleted tuple.
+ </para>
+ <para>
+ Complexity Factors: Index size, Index type
<bridgehead renderas="sect4">Example</bridgehead>
<programlisting>
localhost> <userinput>call box.delete('0', 'test#1')</userinput>
@@ -658,6 +712,9 @@ Call ERROR, Illegal parameters, key is not u32 (ER_ILLEGAL_PARAMS)
If <code>key</code> is <code>nil</code> or unspecified,
the selection starts from the start of the index.
</para>
+ <para>
+ Complexity Factors: Index size, Index type, Number of tuples accessed.
+ </para>
<para>
Possible errors:
For BITSET indexes, box.select_range() does not work.
@@ -736,6 +793,9 @@ localhost> <userinput>lua box.select_range(4, 1, 2, '1')</userinput>
If <code>key</code> is <code>nil</code> or unspecified,
the selection starts from the end of the index.
For other index types this call is not supported.
+ </para>
+ <para>
+ Complexity Factors: Index size, Index type, Number of tuples accessed.
<bridgehead renderas="sect4">Example</bridgehead>
<programlisting>localhost> <userinput>show configuration</userinput>
---
@@ -946,11 +1006,11 @@ localhost> <userinput>lua num, str, num64 = box.unpack('ppp', box.pack('ppp', 66
> <userinput> 'string',tonumber64('666666666666666')))!</userinput>
---
...
-localhost> <userinput>lua print(box.unpack('i', num));!</userinput>
+localhost> <userinput>lua print(box.unpack('i', num))!</userinput>
---
666
...
-localhost> <userinput>lua print(str);!</userinput>
+localhost> <userinput>lua print(str)!</userinput>
---
string
...
@@ -1155,6 +1215,9 @@ error: 'WAL I/O error'
<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>
@@ -1187,6 +1250,9 @@ localhost> <userinput>lua box.auto_increment(0, 'Fld#3')</userinput>
<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>localhost> <userinput>lua box.counter.inc(0, 'top.mail.ru')</userinput>
---
@@ -1216,6 +1282,9 @@ localhost> <userinput>lua box.counter.inc(0, 'top.mail.ru')</userinput>
<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>localhost> <userinput>lua box.counter.dec(0, 'top.mail.ru')</userinput>
---
@@ -2113,6 +2182,9 @@ localhost> <userinput>lua box.space[0].index[0].idx:max()</userinput>
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
@@ -2205,6 +2277,9 @@ error: 'Iterator type is not supported'
<para>
Returns: (type = tuple) the tuple for the first key in the index.
</para>
+ <para>
+ Complexity Factors: Index size, Index type.
+ </para>
<para>
Possible errors: index is not of type 'TREE'.
</para>
@@ -2230,6 +2305,9 @@ error: 'Iterator type is not supported'
<para>
Returns: (type = tuple) the tuple for the last key in the index.
</para>
+ <para>
+ Complexity Factors: Index size, Index type.
+ </para>
<para>
Possible errors: index is not of type 'TREE'.
</para>
@@ -2261,6 +2339,9 @@ error: 'Iterator type is not supported'
<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>localhost> <userinput>lua box.space[0].index[0]:random(1)</userinput>
@@ -2472,7 +2553,8 @@ procedures.
<listitem>
<para>
Detach the current fiber. This is a cancellation point. This is a yield point.
- It is usually more convenient to use <code>box.fiber.wrap()</code> for detaching.
+ It is usually more convenient to use <code>box.fiber.wrap()</code> to create
+ a fiber which is already detached when it is created.
</para>
</listitem>
</varlistentry>
@@ -2623,7 +2705,7 @@ fiber=104. dead. gvar=22
<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 record, or setting up triggers
+ 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>
@@ -2715,9 +2797,11 @@ for instructions about defining triggers for connect and disconnect events
<!-- end of lib -->
<section xml:id="sp-box-ipc">
- <title>Package <code>box.ipc</code> — inter procedure communication</title>
+ <title>Package <code>box.ipc</code> — inter-process communication</title>
<para>
- The <code>box.ipc</code> package allows sending and receiving messages between different procedures of a session.
+ The <code>box.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>box.ipc.channel()</code> to allocate space and get a channel object, which will be
@@ -3602,7 +3686,7 @@ Select OK, 1 rows affected
<title>Package <code xml:id="box.cfg">box.cfg</code></title>
<para>
The box.cfg package provides read-only access to
- all server configuration parameters.
+ some server configuration parameters.
</para>
<varlistentry>
<term><emphasis role="lua">box.cfg</emphasis></term>
diff --git a/doc/user/tutorial.xml b/doc/user/tutorial.xml
index 5e61171e2dc6962a4027e01d0398430e876c2e76..75f0239524f8ced90671201a417e8770e75d5aa2 100644
--- a/doc/user/tutorial.xml
+++ b/doc/user/tutorial.xml
@@ -427,10 +427,10 @@ This is the end of the list of steps to take for source downloads.
<para>
For your added convenience, github.com has README files with example scripts:
-<productname xlink:href="https://github.com/tarantool/tarantool/blob/stable/README.CentOS">README.CentOS</productname> for CentOS 5.8,
-<productname xlink:href="https://github.com/tarantool/tarantool/blob/stable/README.FreeBSD">README.FreeBSD</productname> for FreeBSD 8.3,
-<productname xlink:href="https://github.com/tarantool/tarantool/blob/stable/README.MacOSX">README.MacOSX</productname> for Mac OS X <quote>Lion</quote>,
-<productname xlink:href="https://github.com/tarantool/tarantool/blob/stable/README.md">README.md</productname> for generic GNU/Linux.
+<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 and the client (but not the documentation), and run tests after build.