Skip to content

Commit

Permalink
Fix links, wording and formatting in the Connectors section
Browse files Browse the repository at this point in the history 
Resolves #2365, #2320
  • Loading branch information
@NickVolynkin
NickVolynkin committed Oct 15, 2021
1 parent b3c2ea5 commit 4f1b2cd
Show file tree
Hide file tree
Showing 22 changed files with 212 additions and 190 deletions.
26 changes: 13 additions & 13 deletions doc/book/connectors/index.rst → doc/book/connectors.rst
View file
Expand Up @@ -6,7 +6,7 @@

This chapter documents APIs for various programming languages:

* :doc:`C++ <cxx/tntcxx_api>`
* :doc:`C++ <connectors/cxx/tntcxx_api>`
* :ref:`Java <index_connector_java>`
* :ref:`Go <index_connector_go>`
* :ref:`R <index_connector_r>`
Expand All @@ -21,7 +21,7 @@ This chapter documents APIs for various programming languages:
.. toctree::
:hidden:

C++ <cxx/tntcxx_api>
C++ <connectors/cxx/tntcxx_api>

=====================================================================
Protocol
Expand Down Expand Up @@ -124,42 +124,42 @@ script:
.. _index_connector_java:

.. include:: __java.rst
.. include:: connectors/__java.rst

.. _index_connector_go:

.. include:: __go.rst
.. include:: connectors/__go.rst

.. _index_connector_r:

.. include:: __r.rst
.. include:: connectors/__r.rst

.. _index_connector_erlang:

.. include:: __erlang.rst
.. include:: connectors/__erlang.rst

.. _index_connector_perl:

.. include:: __perl.rst
.. include:: connectors/__perl.rst

.. _index_connector_php:

.. include:: __php.rst
.. include:: connectors/__php.rst

.. _index_connector_py:

.. include:: __python.rst
.. include:: connectors/__python.rst

.. _index_connector_nodejs:

.. include:: __nodejs.rst
.. include:: connectors/__nodejs.rst

.. _index_connector_csharp:

.. include:: __csharp.rst
.. include:: connectors/__csharp.rst

.. _index_connector_c:

.. include:: __c.rst
.. include:: connectors/__c.rst

.. include:: __results.rst
.. include:: connectors/__results.rst
85 changes: 50 additions & 35 deletions doc/book/connectors/__c.rst
View file
@@ -1,17 +1,15 @@
=====================================================================
C
=====================================================================
C
=

Here follow two examples of using Tarantool's high-level C API.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Example 1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Example 1
---------

Here is a complete C program that inserts :code:`[99999,'B']` into
space :code:`examples` via the high-level C API.

.. code-block:: c
.. code-block:: c
#include <stdio.h>
#include <stdlib.h>
Expand Down Expand Up @@ -44,7 +42,7 @@ space :code:`examples` via the high-level C API.
Paste the code into a file named :file:`example.c` and install ``tarantool-c``.
One way to install ``tarantool-c`` (using Ubuntu) is:

.. code-block:: console
.. code-block:: console
$ git clone git://github.com/tarantool/tarantool-c.git ~/tarantool-c
$ cd ~/tarantool-c
Expand All @@ -54,9 +52,9 @@ One way to install ``tarantool-c`` (using Ubuntu) is:
$ make
$ make install
To compile and link the program, say:
To compile and link the program, run:

.. code-block:: console
.. code-block:: console
$ # sometimes this is necessary:
$ export LD_LIBRARY_PATH=/usr/local/lib
Expand All @@ -72,11 +70,14 @@ If Tarantool is not running on localhost with listen address = 3301, the program
will print “Connection refused”.
If the insert fails, the program will print "Insert failed" and an error number
(see all error codes in the source file
`/src/box/errcode.h <https://github.com/tarantool/tarantool/blob/2.1/src/box/errcode.h>`_).
`/src/box/errcode.h <https://github.com/tarantool/tarantool/blob/2.1/src/box/errcode.h>`__).

Here are notes corresponding to comments in the example program.

**SETUP:** The setup begins by creating a stream.
SETUP
~~~~~

The setup begins by creating a stream.

.. code-block:: c
Expand All @@ -96,28 +97,34 @@ Function description:
struct tnt_stream *tnt_net(struct tnt_stream *s)
int tnt_set(struct tnt_stream *s, int option, variant option-value)
**CONNECT:** Now that the stream named ``tnt`` exists and is associated with a
CONNECT
~~~~~~~

Now that the stream named ``tnt`` exists and is associated with a
URI, this example program can connect to a server instance.

.. code-block:: c
.. code-block:: c
if (tnt_connect(tnt) < 0)
{ printf("Connection refused\n"); exit(-1); }
Function description:

.. code-block:: text
.. code-block:: text
int tnt_connect(struct tnt_stream *s)
The connection might fail for a variety of reasons, such as:
the server is not running, or the URI contains an invalid :ref:`password<authentication-passwords>`.
If the connection fails, the return value will be -1.

**MAKE REQUEST:** Most requests require passing a structured value, such as
MAKE REQUEST
~~~~~~~~~~~~

Most requests require passing a structured value, such as
the contents of a tuple.

.. code-block:: c
.. code-block:: c
struct tnt_stream *tuple = tnt_object(NULL);
tnt_object_format(tuple, "[%d%s]", 99999, "B");
Expand All @@ -133,14 +140,17 @@ then the integer value, then a pointer to the string value.

Function description:

.. code-block:: text
.. code-block:: text
ssize_t tnt_object_format(struct tnt_stream *s, const char *fmt, ...)
**SEND REQUEST:** The database-manipulation requests are analogous to the
SEND REQUEST
~~~~~~~~~~~~

The database-manipulation requests are analogous to the
requests in the box library.

.. code-block:: c
.. code-block:: c
tnt_insert(tnt, 999, tuple);
tnt_flush(tnt);
Expand All @@ -152,7 +162,7 @@ the program passes the ``tnt_stream`` that was used for connection

Function description:

.. code-block:: text
.. code-block:: text
ssize_t tnt_insert(struct tnt_stream *s, uint32_t space, struct tnt_stream *tuple)
ssize_t tnt_replace(struct tnt_stream *s, uint32_t space, struct tnt_stream *tuple)
Expand All @@ -162,10 +172,13 @@ Function description:
ssize_t tnt_update(struct tnt_stream *s, uint32_t space, uint32_t index,
struct tnt_stream *key, struct tnt_stream *ops)
**GET REPLY:** For most requests, the client will receive a reply containing some
GET REPLY
~~~~~~~~~

For most requests, the client will receive a reply containing some
indication whether the result was successful, and a set of tuples.

.. code-block:: c
.. code-block:: c
struct tnt_reply reply; tnt_reply_init(&reply);
tnt->read_reply(tnt, &reply);
Expand All @@ -176,40 +189,42 @@ This program checks for success but does not decode the rest of the reply.

Function description:

.. code-block:: text
.. code-block:: text
struct tnt_reply *tnt_reply_init(struct tnt_reply *r)
tnt->read_reply(struct tnt_stream *s, struct tnt_reply *r)
void tnt_reply_free(struct tnt_reply *r)
**TEARDOWN:** When a session ends, the connection that was made with
TEARDOWN
~~~~~~~~

When a session ends, the connection that was made with
:c:func:`tarantoolc:tnt_connect()` should be closed, and the objects that were
made in the setup should be destroyed.

.. code-block:: c
.. code-block:: c
tnt_close(tnt);
tnt_stream_free(tuple);
tnt_stream_free(tnt);
Function description:

.. code-block:: text
.. code-block:: text
void tnt_close(struct tnt_stream *s)
void tnt_stream_free(struct tnt_stream *s)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Example 2
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Example 2
---------

Here is a complete C program that selects, using index key ``[99999]``, from
space ``examples`` via the high-level C API.
To display the results, the program uses functions in the
`MsgPuck <https://github.com/tarantool/msgpuck>`_ library which allow decoding of
`MessagePack <https://en.wikipedia.org/wiki/MessagePack>`_ arrays.
`MsgPuck <https://github.com/tarantool/msgpuck>`__ library which allow decoding of
`MessagePack <https://en.wikipedia.org/wiki/MessagePack>`__ arrays.

.. code-block:: c
.. code-block:: c
#include <stdio.h>
#include <stdlib.h>
Expand Down Expand Up @@ -281,13 +296,13 @@ Similarly to the first example, paste the code into a file named

To compile and link the program, say:

.. code-block:: console
.. code-block:: console
$ gcc -o example2 example2.c -ltarantool
To run the program, say :samp:`./example2`.

The two example programs only show a few requests and do not show all that's
necessary for good practice. See more in the
`tarantool-c documentation at GitHub <http://github.com/tarantool/tarantool-c>`_.
`tarantool-c documentation at GitHub <http://github.com/tarantool/tarantool-c>`__.

0 comments on commit 4f1b2cd

Please sign in to comment.