Top.Mail.Ru
Примеры и шаблоны | Tarantool
Tarantool
Узнайте содержание релиза 2.8

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

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

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:

  • Base description
  • Параметры
  • 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

    :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 – что передается в функцию
возвращает:

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

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

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

Пример:

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
---
...

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: an :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.

Параметры:
возвращает:

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

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

кортеж

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

  • отсутствие такого индекса;
  • неправильный тип;
  • больше одного кортежа подходят.

Факторы сложности: Размер индекса, тип индекса. См. также 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
...