Примеры и шаблоны | Tarantool
Документация на русском языке
поддерживается сообществом

Примеры и шаблоны

This document contains general guidelines for describing the Tarantool API, as well as examples and templates.

Use this checklist for documenting a function or a method:

  • General description
  • Parameters
  • What this function returns (if nothing, write „none“)
  • Return type (if exists)
  • Possible errors (if exist)
  • Complexity factors (if exist)
  • Usage with memtx and vinyl (if differs)
  • Example(s)
  • Extra information (if needed)

We use the Sphinx directives .. module:: and .. function:: to describe functions of Tarantool modules:

..  module:: fiber

..  function:: create(function [, function-arguments])

    Create and start a fiber. The fiber is created and begins to run immediately.

    :param function: the function to be associated with the fiber
    :param function-arguments: what will be passed to function.
                               If the arguments are optional, put them in
                               square brackets in the function declaration.

    :return: created fiber object
    :rtype: userdata

    **Example:**

    ..  code-block:: tarantoolsession

        tarantool> fiber = require('fiber')
        ---
        ...
        tarantool> function function_name()
                 >   print("I'm a fiber")
                 > end
        ---
        ...
        tarantool> fiber_object = fiber.create(function_name); print("Fiber started")
        I'm a fiber
        Fiber started
        ---
        ...

The resulting output looks like this:

fiber.create(function[, function-arguments])

Создание и запуск файбера. Происходит создание файбера, который незамедлительно начинает работу.

Параметры:
  • function – функция, которая будет связана с файбером
  • function-arguments – what will be passed to function. If the arguments are optional, put them in square brackets in the function declaration.
возвращает:

созданный объект файбера

возвращаемое значение:
 

пользовательские данные

Пример:

tarantool> fiber = require('fiber')
---
...
tarantool> function function_name()
         >   print("I'm a fiber")
         > end
---
...
tarantool> fiber_object = fiber.create(function_name); print("Fiber started")
I'm a fiber
Fiber started
---
...

Примечание

The best practices for parameter description are listed below.

Methods are described similarly to functions, but the .. class:: directive, unlike .. module::, requires nesting.

As for data, it’s enough to write the description, the return type, and an example.

Here is the example documentation describing the method and data of the index_object class:

..  class:: index_object

    ..  method:: get(key)

        Search for a tuple :ref:`via the given index <box_index-note>`.

        :param index_object index_object: :ref:`object reference
                                          <app_server-object_reference>`
        :param scalar/table      key: values to be matched against the index key

        :return: the tuple whose index-key fields are equal to the passed key values
        :rtype:  tuple

        **Possible errors:**

        * No such index
        * Wrong type
        * More than one tuple matches

        **Complexity factors:** index size, index type.
        See also :ref:`space_object:get() <box_space-get>`.

        **Example:**

        ..  code-block:: tarantoolsession

            tarantool> box.space.tester.index.primary:get(2)
            ---
            - [2, 'Music']
            ...

    ..  data:: unique

        True if the index is unique, false if the index is not unique.

        :rtype: boolean

        ..  code-block:: tarantoolsession

            tarantool> box.space.tester.index.primary.unique
            ---
            - true
            ...

And the resulting output looks like this:

object index_object
index_object:get(key)

Search for a tuple via the given index.

Параметры:
  • index_object (index_object) – object reference
  • key (scalar/table) – значения для сопоставления с ключом индекса
возвращает:

the tuple whose index-key fields are equal to the passed key values

возвращаемое значение:
 

кортеж

Возможные ошибки:

  • No such index
  • Wrong type
  • More than one tuple matches

Complexity factors: index size, index type. See also space_object:get().

Пример:

tarantool> box.space.tester.index.primary:get(2)
---
- [2, 'Music']
...
index_object.unique

Если индекс уникальный – true, если индекс не уникален – false.

возвращаемое значение:
 boolean (логический)
tarantool> box.space.tester.index.primary.unique
---
- true
...

Примечание

The best practices for parameter description are listed below.

This section explains how to document specific function or class method parameters as described above. To learn how to document configuration parameters passed to Tarantool via the command line or in an initialization file, see the next section.

For every function or class method parameter, list the following details:

  • General description
  • Type
  • Default value (if optional), possible values

In the «Possible errors» section of the function or class method, consider explaining what happens if the parameter hasn’t been defined or has the wrong value.

For every configuration parameter, list the following details:

  • Since which Tarantool version
  • General description
  • Type
  • Corresponding environment variable (if applicable)
  • Default value
  • Possible values
  • Dynamic (yes or no)

..  confval:: wal_dir

    Since version 1.6.2.
    A directory where write-ahead log (``.xlog``) files are stored.
    Can be relative to :ref:`work_dir <cfg_basic-work_dir>`.
    Sometimes ``wal_dir`` and :ref:`memtx_dir <cfg_basic-memtx_dir>` are specified with different values,
    so that write-ahead log files and snapshot files can be stored on different disks.
    If not specified, defaults to ``work_dir``.

    | Type: string
    | Default: "."
    | Environment variable: TT_WAL_DIR
    | Dynamic: no

Result:

wal_dir

Since version 1.6.2. A directory where write-ahead log (.xlog) files are stored. Can be relative to work_dir. Sometimes wal_dir and memtx_dir are specified with different values, so that write-ahead log files and snapshot files can be stored on different disks. If not specified, defaults to work_dir.

Type: string
Default: «.»
Environment variable: TT_WAL_DIR
Dynamic: no