METHODS¶

new

    my $box = $class->new(\%args);

%args:

spaces => [ \%space, ... ]

%space:

default_space => $default_space_name_string_or_id_uint32

Space "space" or "name" to be used by default. Must be set if there are more than one "\%space"s.

timeout => $timeout_fractional_seconds_float || 23

A common timeout for network operations.

select_timeout => $select_timeout_fractional_seconds_float || 2

Select queries timeout for network operations. See "select_retry".

retry => $retry_int || 1

A common retries number for network operations.

select_retry => $select_retry_int || 3

Select queries retries number for network operations.

Sometimes we need short timeout for select's and long timeout for critical update's, because in case of timeout we don't know if the update has succeeded. For the same reason we can't retry update operation.

So increasing "timeout" and setting "retry => 1" for updates lowers possibility of such situations (but, of course, does not exclude them at all), and guarantees that we don't do the same more then once.

soft_retry => $soft_retry_int || 3

A common retries number for Tarantool/Box temporary errors (these marked by 1 in the lowest byte of "error_code"). In that case we know for sure that the request was declined by Tarantool/Box for some reason (a tuple was locked for another update, for example), and we can try it again.

This is also limited by "retry"/"select_retry" (depending on query type).

retry_delay => $retry_delay_fractional_seconds_float || 1

Specify a delay between retries for network operations.

raise => $raise_bool || 1

Should we raise an exceptions? If so, exceptions are raised when no more retries left and all tries failed (with timeout, fatal, or temporary error).

debug => $debug_level_int || 0

Debug level, 0 - print nothing, 9 - print everything

name => $name

A string used for self-description. Mainly used for debugging purposes.

Error

Last error code, or 'fail' for some network reason, oftenly a timeout.

    $box->Insert(@tuple) or die sprintf "Error %X", $box->Error; # die "Error 202"

ErrorStr

Last error code and description in a single string.

    $box->Insert(@tuple) or die $box->ErrorStr;                  # die "Error 00000202: Illegal Parameters"

Call

Call a stored procedure. Returns an arrayref of the result tuple(s) upon success.

    my $results = $box->Call('stored_procedure_name', \@procedure_params, \%options) or die $box->ErrorStr; # Call failed
    my $result_tuple = @$results && $results->[0] or warn "Call succeeded, but returned nothing";

@procedure_params

An array of bytestrings to be passed as is to the procecedure.

%options

Add, Insert, Replace

    $box->Add(@tuple) or die $box->ErrorStr;         # only store a new tuple
    $box->Replace(@tuple, { space => "secondary" }); # only store an existing tuple
    $box->Insert(@tuple, { space => "main" });       # store anyway

Insert a @tuple into the storage into $options{space} or "default_space" space. All of them return "true" upon success.

All of them have the same parameters:

@tuple

A tuple to insert. All fields must be defined. All fields will be "pack()"ed according to "format" (see "new")

%options

The difference between them is the behaviour concerning tuple with the same primary key:

• Add will succeed if and only if duplicate-key tuple does not exist
• Replace will succeed if and only if a duplicate-key tuple exists
• Insert will succeed anyway. Duplicate-key tuple will be overwritten

Select

Select tuple(s) from storage

    my $key = $id;
    my $key = [ $firstname, $lastname ];
    my @keys = ($key, ...);
    my $tuple  = $box->Select($key)              or $box->Error && die $box->ErrorStr;
    my $tuple  = $box->Select($key, \%options)   or $box->Error && die $box->ErrorStr;
    my @tuples = $box->Select(@keys)             or $box->Error && die $box->ErrorStr;
    my @tuples = $box->Select(@keys, \%options)  or $box->Error && die $box->ErrorStr;
    my $tuples = $box->Select(\@keys)            or die $box->ErrorStr;
    my $tuples = $box->Select(\@keys, \%options) or die $box->ErrorStr;

$key, @keys, \@keys

Specify keys to select. All keys must be defined.

Contextual behaviour:

%options

Delete

Delete tuple from storage. Return false upon error.

    my $n_deleted = $box->Delete($key) or die $box->ErrorStr;
    my $n_deleted = $box->Delete($key, \%options) or die $box->ErrorStr;
    warn "Nothing was deleted" unless int $n_deleted;
    my $deleted_tuple_set = $box->Delete($key, { want_deleted_tuples => 1 }) or die $box->ErrorStr;
    warn "Nothing was deleted" unless @$deleted_tuple_set;

%options

UpdateMulti

Apply several update operations to a tuple.

    my @op = ([ f1 => add => 10 ], [ f1 => and => 0xFF], [ f2 => set => time() ], [ misc_string => cutend => 3 ]);
    my $n_updated = $box->UpdateMulti($key, @op) or die $box->ErrorStr;
    my $n_updated = $box->UpdateMulti($key, @op, \%options) or die $box->ErrorStr;
    warn "Nothing was updated" unless int $n_updated;
    my $updated_tuple_set = $box->UpdateMulti($key, @op, { want_result => 1 }) or die $box->ErrorStr;
    warn "Nothing was updated" unless @$updated_tuple_set;

Different fields can be updated at one shot. The same field can be updated more than once. All update operations are done atomically. Returns false upon error.

@op = ([ $field => $op => $value ], ...)

%options

AnyEvent¶

"Insert, UpdateMulti, Select, Delete, Call" methods can be given the following options:

callback => sub { my ($data, $error) = @_; }

Do an async request using AnyEvent. $data contains unpacked and processed according to request options data. $error contains a message string in case of error. Set up "raise => 0" to use this option.

"Continuations"¶

"Select" methods can be given the following options:

return_fh => 1

The request does only send operation on network, and returns "{ fh => $IO_Handle, continue => $code }" or false if send operation failed. $code reads data from network, unpacks, processes according to options and returns it.

You should handle timeouts and retries manually (using select() call for example). Usage example:

    my $continuation = $box->Select(13,{ return_fh => 1 });
    ok $continuation, "select/continuation";
    my $rin = '';
    vec($rin,$continuation->{fh}->fileno,1) = 1;
    my $ein = $rin;
    ok 0 <= select($rin,undef,$ein,2), "select/continuation/select";
    my $res = $continuation->{continue}->();
    use Data::Dumper;
    is_deeply $res, [13, 'some_email@test.mail.ru', 1, 2, 3, 4, '123456789'], "select/continuation/result";
    

LongTuple¶

If "format" given to "new", or "unpack_format" given to "Call" ends with a star ("*") long tuple is enabled. Last field or group of fields of "format" represent variable-length tail of the tuple. "long_fields" option given to "new" will fold the tail into array of hashes.

    $box->Insert(1,"2",3);         #1
    $box->Insert(3,"2",3,4,5);     #2
    $box->Insert(5,"2",3,4,5,6,7); #3

If we set up

    format => "L&CL*",
    fields => [qw/ a b c d /], # d is the folding field here
    # no long_fields - no folding into hash

we'll get:

    $result = $box->Select([1,2,3,4,5]);
    $result = [
        { a => 1, b => "2", c => 3, d => [] },        #1
        { a => 3, b => "2", c => 3, d => [4,5] },     #2
        { a => 5, b => "2", c => 3, d => [4,5,6,7] }, #3
    ];

And if we set up

    format => "L&C(LL)*",
    fields => [qw/ a b c d /], # d is the folding field here
    long_fields => [qw/ d1 d2 /],

we'll get:

    $result = [
        { a => 1, b => "2", c => 3, d => [] },                               #1
        { a => 3, b => "2", c => 3, d => [{d1=>4, d2=>5}] },                 #2
        { a => 5, b => "2", c => 3, d => [{d1=>4, d2=>5}, {d1=>6, d2=>7}] }, #3
    ];

"UpdateMulti" can be given a field number in several ways:

$linear_index_int

    $box->UpdateMulti(5, [ 5 => set => $val ]) #3: set 6 to $val
    

an arrayref of [$index_of_folded_subtuple_int, $long_field_name_str_or_index_int]

    $box->UpdateMulti(5, [ [1,0]    => set => $val ]) #3: set 6 to $val
    $box->UpdateMulti(5, [ [1,'d1'] => set => $val ]) #3: set 6 to $val
    

utf8¶

Utf8 strings are supported very simply. When pushing any data to tarantool (with any query, read or write), the utf8 flag is set off, so all data is pushed as bytestring. When reading response, for fields marked a dollar sign "$" (see "new") (including such in "LongTuple" tail) utf8 flag is set on. That's all. Validity is on your own.