diff --git a/doc/sphinx/book/connectors/__c.rst b/doc/sphinx/book/connectors/__c.rst new file mode 100644 index 0000000000000000000000000000000000000000..75f51e6f570ba4da4edc706d0c41fa3ac3c3bd9c --- /dev/null +++ b/doc/sphinx/book/connectors/__c.rst @@ -0,0 +1,107 @@ +===================================================================== + C +===================================================================== + +Here is a complete C program that inserts ``[99999,'B']`` into +space ``examples`` via the high-level C API. + +.. code-block:: c + + #include <stdio.h> + #include <tarantool/tarantool.h> + #include <tarantool/tnt_net.h> + #include <tarantool/tnt_opt.h> + void main() + { + struct tnt_stream *tnt = tnt_net(NULL); /* See note = SETUP */ + tnt_set(tnt, TNT_OPT_URI, "localhost:3301"); + if (tnt_connect(tnt) < 0) /* See note = CONNECT */ + { printf("Connection refused\n"); exit(-1); } + struct tnt_stream *tuple = tnt_object(NULL); /* See note = MAKE REQUEST */ + tnt_object_format(tuple, "[%d%s]", 999, "B"); + tnt_insert(tnt, 999, tuple); /* See note = SEND REQUEST */ + tnt_flush(tnt); + struct tnt_reply reply; tnt_reply_init(&reply); /* See note = GET REPLY */ + tnt->read_reply(tnt, &reply); + if (reply.code != 0) + { printf("Insert failed %lu.\n", reply.code); } + tnt_close(tnt); /* See below = TEARDOWN */ + tnt_stream_free(tuple); + tnt_stream_free(tnt); + } + +To prepare, paste the code into a file named example.c and install +tarantool-c. One way to install tarantool-c (using Ubuntu) is: |br| +|nbsp| |nbsp| :codenormal:`git clone git://github.com/tarantool/tarantool-c.git ~/tarantool-c` |br| +|nbsp| |nbsp| :codenormal:`cd tarantool-c` |br| +|nbsp| |nbsp| :codenormal:`git submodule init` |br| +|nbsp| |nbsp| :codenormal:`git submodule update` |br| +|nbsp| |nbsp| :codenormal:`cmake .` |br| +|nbsp| |nbsp| :codenormal:`make` |br| +|nbsp| |nbsp| :codenormal:`make install` |br| +To compile and link the program, say: |br| +|nbsp| |nbsp| :codenormal:`#Sometimes this is necessary: export LD_LIBRARY_PATH=/usr/local/lib` |br| +|nbsp| |nbsp| :codenormal:`gcc -o example example.c -ltarantool -ltarantoolnet` |br| +Before trying to run, +check that the server is listening and that :code:`examples` exists, as described at the start of this chapter. +To run the program, say ``./example``. The program will connect +to the server, and will send the request. +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. + +Here are notes corresponding to comments in the example program. + +SETUP: The setup begins by creating a stream. +In this program the stream will be named :code:`tnt`. +Before connecting on the tnt stream, some options may have to be set. +The most important option is TNT_OPT_URI. +In this program the URI is "localhost:3301", since that is where the +Tarantool server is supposed to be listening. |br| +Function description: :samp:`struct tnt_stream *tnt_net(struct tnt_stream *s);` |br| +Function description: :samp:`int tnt_set(struct tnt_stream *s, int option, variant option-value);` + +CONNECT: Now that the stream named :codenormal:`tnt` exists and is associated with a +URI, this example program can connect to the server. |br| +Function description: :samp:`int tnt_connect(struct tnt_stream *s);` |br| +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. + +MAKE REQUEST: Most requests require passing a structured value, such as +the contents of a tuple. In this program the request will +be an insert, and the tuple contents will be an integer +and a string. This is a simple serial set of values, that +is, there are no sub-structures or arrays. Therefore it +is easy in this case to format what will be passed using +the same sort of arguments that one would use with a C +printf() function: "%d" for the integer, "%s" for the string, +then the integer value, then a pointer to the string value. |br| +Function description: :samp:`ssize_t tnt_object_format(struct tnt_stream *s, const char *fmt, ...)` + +SEND REQUEST: The database-manipulation requests are analogous to the +requests in the box library. |br| +Function description: :samp:`tnt_insert(struct tnt_stream *s, uint32_t space, struct tnt_stream *tuple);` |br| +Function description: :samp:`tnt_replace(struct tnt_stream *s, uint32_t space, struct tnt_stream *tuple);` |br| +Function description: :samp:`tnt_select(struct tnt_stream *s, uint32_t space, uint32_t index, uint32_t limit, uint32_t offset, uint8_t iterator, struct tnt_stream *key);` |br| +Function description: :samp:`ssize_t tnt_update(struct tnt_stream *s, uint32_t space, uint32_t index, struct tnt_stream *key, struct tnt_stream *ops);` |br| +In this program the choice is to do an insert request, so +the program passes the tnt_stream that was used for connection +(:code:`tnt`) and the stream that was set up with tnt_object_format (:code:`tuple`). + +GET REPLY: For most requests the client will receive a reply containing some indication +whether the result was successful, and a set of tuples. +This program checks for success but does not decode the rest of the reply. |br| +Function description: :samp:`struct tnt_reply *tnt_reply_init(struct tnt_reply *r);` |br| +Function description: :samp:`tnt->read_reply(struct tnt_stream *s, struct tnt_reply *r);` |br| +Function description: :samp:`void tnt_reply_free(struct tnt_reply *r);` + +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. |br| +Function description: :samp:`tnt_close(struct tnt_stream *s);` |br| +Function description: :samp:`tnt_stream_free(struct tnt_stream *s);` + +The example program only shows one request and does not show all that's +necessary for good practice. For that, see http://github.com/tarantool/tarantool-c. + +.. _Queue managers on Tarantool: https://github.com/tarantool/queue diff --git a/doc/sphinx/book/connectors/__php.rst b/doc/sphinx/book/connectors/__php.rst index e21827bf6bd38a50ddb021524d13a51dda349e81..aa42ae761aed8ba9f8e6f607229d5f9c1f391da4 100644 --- a/doc/sphinx/book/connectors/__php.rst +++ b/doc/sphinx/book/connectors/__php.rst @@ -33,7 +33,7 @@ directory and tell PHP where to find the ``php.ini`` file that contains that lin Here is a complete PHP program that inserts [99999,'BB'] into a space named 'examples' via the PHP API. Before trying to run, check that the server is listening and that -``examples`` exists, as `described earlier`_. To run, paste the code into a file named +``examples`` exists, as described at the start of this chapter. To run, paste the code into a file named example.php and say ``php example.php``. The program will open a socket connection with the tarantool server at localhost:3301, then send an INSERT request, then — if all is well — print "Insert succeeded". If the tuple already exists, the program will print @@ -59,5 +59,4 @@ applications. The example program only shows one command and does not show all that's necessary for good practice. For that, please see `tarantool-php`_ project at GitHub. -.. _described earlier: https://en.wikipedia.org/wiki/Cpan .. _tarantool-php: https://github.com/tarantool/tarantool-php diff --git a/doc/sphinx/book/connectors/__python.rst b/doc/sphinx/book/connectors/__python.rst index b39d64cdd2344b9205542592c7721ce01d35799f..22302695892b6ee9f004ffd842432b55705aa17a 100644 --- a/doc/sphinx/book/connectors/__python.rst +++ b/doc/sphinx/book/connectors/__python.rst @@ -18,7 +18,7 @@ To prepare, paste the code into a file named example.py and install tarantool-python with either ``pip install tarantool\>0.4`` to install in ``/usr`` (requires **root** privilege) or ``pip install tarantool\>0.4 --user`` to install in ``~`` i.e. user's default directory. Before trying to run, -check that the server is listening and that examples exists, as `described earlier`_. +check that the server is listening and that examples exists, as described at the start of this chapter. To run the program, say ``python example.py``. The program will connect to the server, will send the request, and will not throw an exception if all went well. If the tuple already exists, the program will throw @@ -29,5 +29,4 @@ necessary for good practice. For that, see http://github.com/tarantool/tarantool For an example of a Python API for `Queue managers on Tarantool`_, see https://github.com/tarantool/tarantool-queue-python. -.. _described earlier: https://en.wikipedia.org/wiki/Cpan .. _Queue managers on Tarantool: https://github.com/tarantool/queue diff --git a/doc/sphinx/book/connectors/index.rst b/doc/sphinx/book/connectors/index.rst index efc7bbf2977ba3ec67909e7e32c43a45947c89dc..a7175aeb29c8dae4588b916bfeecccc3d9a3200c 100644 --- a/doc/sphinx/book/connectors/index.rst +++ b/doc/sphinx/book/connectors/index.rst @@ -95,3 +95,6 @@ script: .. include:: __php.rst .. include:: __python.rst + +.. include:: __c.rst +