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
  • Loading branch information
@NickVolynkin
NickVolynkin committed Oct 11, 2021
1 parent 7073e32 commit 0f262eb
Show file tree
Hide file tree
Showing 11 changed files with 183 additions and 168 deletions.
4 changes: 2 additions & 2 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
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>`__.

120 changes: 60 additions & 60 deletions doc/book/connectors/__csharp.rst
View file
Expand Up @@ -3,91 +3,91 @@
=====================================================================

The most commonly used C# driver is
`progaudi.tarantool <https://github.com/progaudi/progaudi.tarantool>`_,
`progaudi.tarantool <https://github.com/progaudi/progaudi.tarantool>`__,
previously named ``tarantool-csharp``. It is not supplied as part of the
Tarantool repository; it must be installed separately. The makers recommend
`cross-platform installation using Nuget <https://www.nuget.org/packages/progaudi.tarantool>`_.
`cross-platform installation using Nuget <https://www.nuget.org/packages/progaudi.tarantool>`__.

To be consistent with the other instructions in this chapter, here is a way to
install the driver directly on Ubuntu 16.04.

1. Install .net core from Microsoft. Follow
`.net core installation instructions <https://dotnet.microsoft.com/download>`_.
1. Install .net core from Microsoft. Follow
`.net core installation instructions <https://dotnet.microsoft.com/download>`__.

.. NOTE::
.. note::

* Mono will not work, nor will .Net from xbuild. Only .net core supported on
Linux and Mac.
* Read the Microsoft End User License Agreement first, because it is not an
ordinary open-source agreement and there will be a message during
installation saying "This software may collect information about you and
your use of the software, and send that to Microsoft."
Still you can
`set environment variables <https://docs.microsoft.com/en-us/dotnet/core/tools/telemetry>`_
to opt out from telemetry.
* Mono will not work, nor will .Net from xbuild. Only .net core supported on
Linux and Mac.
* Read the Microsoft End User License Agreement first, because it is not an
ordinary open-source agreement and there will be a message during
installation saying "This software may collect information about you and
your use of the software, and send that to Microsoft."
Still you can
`set environment variables <https://docs.microsoft.com/en-us/dotnet/core/tools/telemetry>`__
to opt out from telemetry.

2. Create a new console project.
2. Create a new console project.

.. code-block:: console
.. code-block:: console
$ cd ~
$ mkdir progaudi.tarantool.test
$ cd progaudi.tarantool.test
$ dotnet new console
$ cd ~
$ mkdir progaudi.tarantool.test
$ cd progaudi.tarantool.test
$ dotnet new console
3. Add ``progaudi.tarantool`` reference.
3. Add ``progaudi.tarantool`` reference.

.. code-block:: console
.. code-block:: console
$ dotnet add package progaudi.tarantool
$ dotnet add package progaudi.tarantool
4. Change code in ``Program.cs``.
4. Change code in ``Program.cs``.

.. code-block:: console
.. code-block:: console
$ cat <<EOT > Program.cs
using System;
using System.Threading.Tasks;
using ProGaudi.Tarantool.Client;
$ cat <<EOT > Program.cs
using System;
using System.Threading.Tasks;
using ProGaudi.Tarantool.Client;
public class HelloWorld
{
static public void Main ()
{
Test().GetAwaiter().GetResult();
}
static async Task Test()
{
var box = await Box.Connect("127.0.0.1:3301");
var schema = box.GetSchema();
var space = await schema.GetSpace("examples");
await space.Insert((99999, "BB"));
}
}
EOT
public class HelloWorld
{
static public void Main ()
{
Test().GetAwaiter().GetResult();
}
static async Task Test()
{
var box = await Box.Connect("127.0.0.1:3301");
var schema = box.GetSchema();
var space = await schema.GetSpace("examples");
await space.Insert((99999, "BB"));
}
}
EOT
5. Build and run your application.
5. Build and run your application.

Before trying to run, check that the server is listening at ``localhost:3301``
and that the space ``examples`` exists, as
:ref:`described earlier <index-connector_setting>`.
Before trying to run, check that the server is listening at ``localhost:3301``
and that the space ``examples`` exists, as
:ref:`described earlier <index-connector_setting>`.

.. code-block:: console
.. code-block:: console
$ dotnet restore
$ dotnet run
$ dotnet restore
$ dotnet run
The program will:
The program will:

* connect using an application-specific definition of the space,
* open a socket connection with the Tarantool server at `localhost:3301`,
* send an INSERT request, and — if all is well — end without saying anything.
* connect using an application-specific definition of the space,
* open a socket connection with the Tarantool server at ``localhost:3301``,
* send an INSERT request, and — if all is well — end without saying anything.

If Tarantool is not running on localhost with listen port = 3301, or if user
'guest' does not have authorization to connect, or if the INSERT request
fails for any reason, the program will print an error message, among other
things (stacktrace, etc).
If Tarantool is not running on localhost with listen port = 3301, or if user
'guest' does not have authorization to connect, or if the INSERT request
fails for any reason, the program will print an error message, among other
things (stacktrace, etc).

The example program only shows one request and does not show all that’s
necessary for good practice. For that, please see the
`progaudi.tarantool driver repository <https://github.com/progaudi/progaudi.tarantool>`_.
`progaudi.tarantool driver repository <https://github.com/progaudi/progaudi.tarantool>`__.
2 changes: 1 addition & 1 deletion doc/book/connectors/__erlang.rst
View file
Expand Up @@ -2,4 +2,4 @@
Erlang
=====================================================================

See `Erlang tarantool driver <https://github.com/stofel/taran>`_.
Use the `Erlang tarantool driver <https://github.com/stofel/taran>`__.
2 changes: 1 addition & 1 deletion doc/book/connectors/__go.rst
View file
Expand Up @@ -2,4 +2,4 @@
Go
=====================================================================

Please see https://github.com/mialinx/go-tarantool.
Use the `go-tarantool <https://github.com/tarantool/go-tarantool>`__ connector.

0 comments on commit 0f262eb

Please sign in to comment.