MR::Tarantool::Box::XS

Перловая обвязка для libtarantoolbox. Помимо прочего поддерживается:

• упаковка/распаковка туплов из массивов и из хэшей;
• именованные поля в туплах;
• возврат хэша туплов индексированному по определенному полю вместо массива туплов;
• опциональная проверка диапазонов целых типов.

Объект класса MR::Tarantool::Box::XS представляет собой namespace в кластере серверов. Конструктор поддерживает следующие параметры:

• iproto - объект класса MR::IProto::XS для соответствующего кластера;
• microsharding - количество микрошардов (если отсутствует, то микрошардинг не используется);
• namespace - номер namespace в коробке;
• fields - массив имен полей туплов;
• format - сторка формата полей туплов;
• indexes- массив индексов, каждый из которых хэш с ключами:
  • name - имя индекса;
  • keys - массив имен полей, входящих в индекс, или их номеров;
  • default - является ли индексом по-умолчанию.

Например объект коробочки JUDispatch можно создать так:

my $dispatch = MR::Tarantool::Box::XS->new(
    iproto    => MR::IProto::XS->new(masters => ['188.93.61.206:13013']),
    namespace => 0,
    format    => 'l& SSLL',
    fields    => [qw/ID Email ShardNum HistoryShardNum Base Flags/],
    indexes   => [
        { name => 'primary_id', keys => ['ID'], default => 1 },
        { name => 'primary_email', keys => ['Email'] },
    ],
);

Аналогично MR::IProto::XS есть возможность создать/удалить синглетон методами create_singleton, remove_singleton. create_singleton принимает те же параметры, что и конструктор. Для того, чтобы получить используемый для взаимодействия с коробкой объект MR::IProto::XS, применяется метод iproto.

Для полей туплов поддерживаются следующие форматы:

• Q - uint64_t (см. ниже)
• q - int64_t (см. ниже)
• L - uint32_t
• l - int32_t
• S - uint16_t
• s - int16_t
• C - uint8_t
• c - int8_t
• & - байтовая строка
• $ - строка в UTF-8

Поддержка упаковки/распаковки 64-битных целых чисел на 32-битной платформе осуществляется при помощи класса Math::Int64. Важно, что в перле такие числа всегда должны представляться либо объектами Math::Int64, либо строками, но никогда не числами, иначе из-за автоматического преобразования к плавающей точке произойдет потеря точности и, как результат, искажение числа. На входе MR::Tarantool::Box::XS принимает как объекты Math::Int64, так и строки, на выходе отдает объекты. На 64-битной платформе пакет автоматически собирается без поддержки Math::Int64 и используются нативные 64-битные числа.

Аналогично MR::IProto::XS отправка запросов осуществляется при помощи методов bulk и do. Хэш запроса понимает следующие параметры:

• type - тип запроса: "select", "insert", "update", "delete";
• inplace - модифицировать хэш запроса и поместить ответ в него же;
• shard_num - номер микрошарда, в случае применения микрошардинга, либо номер ноды (в обоих случаях нумерация с единицы);
• параметры сообщения, которые понимает MR::IProto::XS (только те, для которых есть соответствующий параметр в опциях сообщения libiprotocluster);
• прочие параметры в зависимости от типа запроса.

В ответе всегда будет ключ error, содержащий dualvar значение, которое в числовом контексте - код ошибки, а в строковом ее описание (аналогично $!).

select

Поддерживаются следующие параметры:

• use_index - имя или номер используемого индекса, если не указан, то используется индекс по умолчанию;
• keys - массив ключей для индекса;
• offset - смещение результата;
• limit - ограничение результата;
• hash_by - вернуть вместо массива туплов хэш с индексом по указанному полю.

В ответе будут содержаться ключи:

• tuples - массив (или хэш, если указан hash_by) туплов;
• replica - со значением 1, если данные получены из реплики.

my $resp = $dispatch->bulk([{
    type      => 'select',
    use_index => 'primary_email',
    keys      => ['[email protected]', '[email protected]'],
}]);

insert

Поддерживаются параметры:

• tuple - тупл, который необходимо вставить;
• action- как именно вставлять:
  • "set" - установить тупл (по умолчанию);
  • "add" - добавить, только если тупла еще нет;
  • "replace" - заменить, только если тупл уже есть;
• want_result - вернуть вставленный тупл в ответе.

В ответе будут ключи:

• tuple - количество добавленных туплов либо тупл, если указан want_result и тупл ровно один.

my $resp = $ns->bulk([{
    type  => 'insert',
    tuple => {
        ID    => 1234568,
        Email => '[email protected]',
        Name  => 'Test',
    },
}]);

update

Параметры:

• key - первичный ключ обновляемой записи;
• ops - массив операций, каждая операция массив из имени поля, имени операции и значения;
• want_result - вернуть обновленный тупл в ответе.

Поддерживаются операции:

• add - числовое сложение;
• and - логическое and;
• xor - логическое xor;
• or - логическое or;
• num_add - алиас к add;
• num_sub - тот же add, но с отрицательным значением;
• bit_set - алиас к or;
• bit_clear - тот же and, но с инверсным значением;
• splice - операция аналогична перловой функции, принимает 3 параметра: смещение, длину и значение;
• substr - алиас к splice;
• append - добавить значение в начало;
• prepend - добавить значение в конец;
• cutbeg - отрезать с начала N байт;
• cutend - отрезать с конца N байт;
• delete - удалить поле;
• insert - вставить новое поле с указанным значением.

В ответе будут ключи:

• tuple - количество модифицированных туплов либо тупл, если указан want_result и тупл ровно один.

my $resp = $ns->do({
    type => 'update',
    key  => 12345678,
    ops  => [ [ BirthdayDay => set => 15 ], [ MyAccess => xor => 0x81000102 ] ],
    want_result => 1,
});

delete

Параметры:

• key - значение первичного ключа удаляемой записи;
• want_result - вернуть удаленный тупл в ответе.

В ответе будут ключи:

• tuple - количество удаленных туплов либо тупл, если указан want_result и тупл ровно один.

my $resp = $ns->bulk([{
    type => 'delete',
    key  => 12345678,
}]);

MR::Tarantool::Box::XS::Function

Перловая обвязка для libtarantoolbox. Предназначена для работы с хранимыми lua-процедурами. Работает аналогично MR::Tarantool::Box::XS, живет в том же модуле, поэтому нужно использовать именно use MR::Tarantool::Box::XS;

Объект класса MR::Tarantool::Box::XS::Function представляет собой lua-процедуру в кластере серверов. Конструктор поддерживает следующие параметры:

• iproto - объект класса MR::IProto::XS для соответствующего кластера;
• microsharding - количество микрошардов (если отсутствует, то микрошардинг не используется);
• name - имя lua-функции;
• in_fields - массив имен аргументов функции;
• in_format - строка формата аргументов функции;
• out_fields - массив имен полей результата функции (или массив массивов, если для каждого тупла результата имена полей разные, при этом последний формат распространяется до конца списка туплов);
• out_format - строка формата полей результата функции (или массив строк аналогично out_fields).

Например:

my $function = MR::Tarantool::Box::XS::Function->new(
    iproto     => $lua_iproto,
    name       => 'client_autotest.complex',
    in_format  => 'CSLQ$',
    in_fields  => [qw/ uint8 uint16 uint32 uint64 string /],
    out_format => [ '$$L', 'S$', '$L', '$L' ],
    out_fields => [ [ '1st', '2nd', '3rd' ], [ 'num', 'str' ], undef, [ 'key', 'val' ] ],
);

Аналогично MR::Tarantool::Box::XS работает создание синглетона и есть метод iproto. Запросы к коробке осуществляются также аналогично, поддерживается единственный тип запроса call.

call

Поддерживаются следующие параметры (помимо стандартных, см. MR::Tarantool::Box::XS):

• tuple - аргументы функции;
• hash_by - вернуть вместо массива туплов хэш с индексом по указанному полю.

Ответ будет аналогичен select:

• tuples - массив (или хэш, если указан hash_by) туплов;
• replica - со значением 1, если данные получены из реплики.

$resp = $function->do({
    type  => 'call',
    tuple => [ 8, 16, 32, 64, 'string' ],
});

Установка

Зависимости

• MR::IProto::XS
• libtarantoolbox

Сборка

perl Makefile.PL
make
make install