From 87934fe3738326270490cdb03feeef0a49b4e0b5 Mon Sep 17 00:00:00 2001
From: bigbes <bigbes@gmail.com>
Date: Mon, 8 Feb 2016 22:03:03 +0300
Subject: [PATCH] [documentation] CR for pgulutzan patches
---
doc/sphinx/book/box/atomic.rst | 62 ++++++++++++++---------------
doc/sphinx/book/box/sophia_diff.rst | 2 +-
doc/sphinx/book/connectors/__c.rst | 12 ------
3 files changed, 30 insertions(+), 46 deletions(-)
diff --git a/doc/sphinx/book/box/atomic.rst b/doc/sphinx/book/box/atomic.rst
index bfa4bdcc23..0fd0152ddf 100644
--- a/doc/sphinx/book/box/atomic.rst
+++ b/doc/sphinx/book/box/atomic.rst
@@ -4,9 +4,9 @@
Atomic execution
-------------------------------------------------------------------------------
-In several places in this manual 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.
+In several places in this manual 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:
@@ -15,26 +15,23 @@ That requires emphasis.
Cooperative multitasking environment
===========================================================
-Tarantool uses cooperative multitasking: unless a
-running fiber deliberately yields control, it is not
-preempted by some other fiber.
-But a running fiber will deliberately yield when it encounters a
-"yield point": an explicit yield() request, or an implicit
-yield due to an operating-system call.
-Any system call which can block will be performed asynchronously,
-and any running fiber which must wait for a system call will be
-preempted so that another ready-to-run fiber takes its place and
-becomes the new running fiber.
-This model makes all programmatic locks unnecessary:
-cooperative multitasking ensures that there will be no concurrency around a resource,
-no race conditions, and no memory consistency issues.
-
-When requests are small, for example simple UPDATE or INSERT or DELETE or 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.
-
-However, a function might perform complex computations or might be written in such a
-way that yields do not occur for a long time. This can lead to unfair
+Tarantool uses cooperative multitasking: unless a running fiber deliberately
+yields control, it is not preempted by some other fiber. But a running fiber
+will deliberately yield when it encounters a "yield point": an explicit
+`yield()` request, or an implicit yield due to an operating-system call. Any
+system call which can block will be performed asynchronously, and any running
+fiber which must wait for a system call will be preempted so that another
+ready-to-run fiber takes its place and becomes the new running fiber. This model
+makes all programmatic locks unnecessary: cooperative multitasking ensures that
+there will be no concurrency around a resource, no race conditions, and
+no memory consistency issues.
+
+When requests are small, for example simple UPDATE or INSERT or DELETE or 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.
+
+However, a function might perform complex computations or might be written in
+such a way that yields do not occur 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. For the default memtx storage engine
@@ -44,15 +41,14 @@ most of the box calls, including the data-change requests
:func:`box.space...delete <space_object.delete>`, are yield points;
however, :func:`box.space...select <space_object.select>` is not.
-Note re storage engine: sophia has different rules:
-insert or update or delete will very rarely cause a yield,
-but select can cause a yield.
+Note re storage engine: sophia has different rules: insert or update or delete
+will very rarely cause a yield, but select can cause a yield.
-In the absence of transactions, any function that contains yield points
-may see changes in the database state caused by fibers that preempt.
-Then the only safe atomic functions for memtx databases would be
-functions which contain only one database request, or functions which
-contain a select request followed by a data-change request.
+In the absence of transactions, any function that contains yield points may see
+changes in the database state caused by fibers that preempt. Then the only safe
+atomic functions for memtx databases would be functions which contain only one
+database request, or functions which contain a select request followed by a
+data-change request.
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
@@ -86,8 +82,8 @@ To ensure they are sent as a single block: put them in a function, or put them a
on one line, or use a delimiter so that multi-line requests are handled together.
**All database operations in a transaction should use the same storage engine**.
-It is not safe to access tuple sets that are defined with {engine='sophia'}
-and also access tuple sets that are defined with {engine='memtx'},
+It is not safe to access tuple sets that are defined with ``{engine='sophia'}``
+and also access tuple sets that are defined with ``{engine='memtx'}``,
in the same transaction.
===========================================================
diff --git a/doc/sphinx/book/box/sophia_diff.rst b/doc/sphinx/book/box/sophia_diff.rst
index 924ef45d3b..d885306750 100644
--- a/doc/sphinx/book/box/sophia_diff.rst
+++ b/doc/sphinx/book/box/sophia_diff.rst
@@ -55,7 +55,7 @@
It was explained :ref:`earlier <yields_must_happen>` that memtx does not "yield" on a select request,
it yields only on data-change requests. However, sophia does yield on a select
request, or on an equivalent such as get() or pairs(). This has significance
- for :ref:`cooperative multitasking <cooperative_multitasking>`.
+ for :ref:`cooperative multitasking <cooperative_multitasking>`.
For more about sophia, see Appendix E :ref:`sophia <sophia>`.
diff --git a/doc/sphinx/book/connectors/__c.rst b/doc/sphinx/book/connectors/__c.rst
index 5a610449d1..dae2f0b947 100644
--- a/doc/sphinx/book/connectors/__c.rst
+++ b/doc/sphinx/book/connectors/__c.rst
@@ -63,8 +63,6 @@ If the insert fails, the program will print "Insert failed" and an error number.
Here are notes corresponding to comments in the example program.
-.. _c_setup:
-
**SETUP:** The setup begins by creating a stream.
.. code-block:: c
@@ -86,8 +84,6 @@ Function description:
`struct tnt_stream *tnt_net(struct tnt_stream *s)`
`int tnt_set(struct tnt_stream *s, int option, variant option-value)`
-.. _c_connect:
-
**CONNECT:** Now that the stream named ``tnt`` exists and is associated with a
URI, this example program can connect to the server.
@@ -107,8 +103,6 @@ The connect might fail for a variety of reasons, such as:
the server is not running, or the URI contains an invalid password.
If the connect fails, the return value will be -1.
-.. _c_make_request:
-
**MAKE REQUEST:** Most requests require passing a structured value, such as
the contents of a tuple.
@@ -133,8 +127,6 @@ Function description:
ssize_t tnt_object_format(struct tnt_stream \*s, const char \*fmt, ...)
-.. _c_send_request:
-
**SEND REQUEST:** The database-manipulation requests are analogous to the
requests in the box library.
@@ -160,8 +152,6 @@ Function description:
ssize_t tnt_update(struct tnt_stream \*s, uint32_t space, uint32_t index,
struct tnt_stream \*key, struct tnt_stream \*ops)
-.. _c_get_reply:
-
**GET REPLY:** For most requests the client will receive a reply containing some indication
whether the result was successful, and a set of tuples.
@@ -183,8 +173,6 @@ Function description:
tnt->read_reply(struct tnt_stream \*s, struct tnt_reply \*r)
void tnt_reply_free(struct tnt_reply \*r)
-.. _c_teardown:
-
**TEARDOWN:** When a session ends, the connection that was made with
tnt_connect() should be closed and the objects that were made in the setup
should be destroyed.
--
GitLab