From Code to Community: Sponsoring The Perl and Raku Conference 2025 Learn more

 / 
MR-Tarantool-0.0.24
River stage zero No dependents
/ MR::Tarantool::Box::Singleton

NAME

MR::Tarantool::Box::Singleton - A singleton wrapper for MR::Tarantool::Box.

Provides connection-persistence and replica fallback. Please read "MR::Tarantool::Box manual" first.

SYNOPSIS


            

              
              
package Some::Tarantool::Box::Singleton;
use MR::Tarantool::Box::Singleton;
use base 'MR::Tarantool::Box::Singleton';
BEGIN { # generates "TUPLE_$field_name" constants, and methods: FIELDS, FIELDS_HASH
    __PACKAGE__->mkfields(qw/ id f1 f2 f3 field4 f5 f6 f7 misc_string /); # applicable for DEFAULT_SPACE only
}
sub SERVER   { Some::Config->GetBoxServer()   }
sub REPLICAS { Some::Config->GetBoxReplicas() }
sub DEFAULT_SPACE { 0 }
sub SPACES   {[{
    space         => 0,
    indexes => [ {
        index_name   => 'primary_id',
        keys         => [TUPLE_id],
    }, {
        index_name   => 'secondary_f1f2',
        keys         => [TUPLE_f1, TUPLE_f2],
    }, ],
    format        => 'QqLlSsCc&',
    default_index => 'primary_id',
}, {
    space         => 1,
    indexes => [ {
        index_name   => 'primary_id',
        keys         => [0],
    }, ],
    format        => '&&&&',
    fields        => [qw/ string1 str2 s3 s4 /],
}]}

DESCRIPTION

METHODS

mkfields


            

              
              
BEGIN {
    $CLASS->mkfields(@names);
}

  • Generates constants "TUPLE_$fieldname" => $fieldposition in $CLASS. Just Like if you say use constant TUPLE_id => 0, TUPLE_f1 => 1, ...;

  • Generates $CLASS variable @fields containing field names, and a $CLASS method FIELDS returning @fields.

  • Generates $CLASS variable %fields containing field names mapping to positions, and a $CLASS method FIELDS_HASH returning \%fields.

  • These @fields are applied to the DEFAULT_SPACE, if fields were not set explicitly for that space.

declare_stored_procedure


            

              
              
$CLASS->declare_stored_procedure(%args);
$CLASS->declare_stored_procedure(
    name             => "box.do.something",                        # internal procedure name, in da box
    method_name      => "CallMyTestingStoredProcedure",            # will generate method named
    options          => { default => options },                    # MR::Tarantool::Box->Call \%options
    params           => [ qw{ P1 P2 P3 Param4 }],                  # names
    unpack_format    => "&LSC(L$)*",
    params_format    => [qw{ C S L a* }],
    params_default   => [ 1, 2, undef, 'the_default' ],            # undef's are mandatory params
);
...
my $data = $CLASS->CallMyTestingStoredProcedure(
    P1 => $val1,
    P2 => $val2,
    P3 => $val3,
    Param4 => $val3,
    { option => $value }, # optional
) or warn $CLASS->ErrorStr;

Declare a stored procedure. This generates $CLASS method $args{method_name} which calls Tarantool/Box procedure $args{name}, using $args{options} as default \%options for MR::Tarantool::Box->Call call. The generated method has the following prototype:


            

              
              
$CLASS->CallMyTestingStoredProcedure( %sp_params, \%optional_options );

Parameters description:

%args:
name => $tarantool_box_sp_name

The name of procedure in Tarantool/Box to call.

method_name => $class_method_name

Class method name to generate.

options => \%options

Options to pass to MR::Taranatool::Box-Call|MR::Taranatool::Box/Call> method.

params => \@names

Procedure input parameters' names

params_default => \@defaults

Procedure input parameters default values. Undefined or absent value makes its parameter mandatory.

params_format => \@format

pack()-compatible format to pack input parameters. Must match params.

unpack_format => $format

pack()-compatible format to unpack procedure output.

%sp_params:

Name => $value pairs.

%optional_options:

Options to pass to MR::Taranatool::Box-Call|MR::Taranatool::Box/Call> method. This overrides %options values key-by-key.

Configuration methods

SERVER

Must return a string of ip:port of master server.

REPLICAS

Must return a comma separated string of ip:port pairs of replica servers (see "is_replica"). Server is chosen from the list randomly.

MR_TARANTOOL_BOX_CLASS

Must return name of the class implementing MR::Tarantool::Box interface, or it's descendant.

SPACES, RAISE, TIMEOUT, SELECT_TIMEOUT, RETRY, SELECT_RETRY, SOFT_RETRY, DEBUG

See corresponding arguments of MR::Tarantool::Box-new|MR::Tarantool::Box/new> method.

Add, Insert, Replace, UpdateMulti, Delete

These methods operate on SERVER only. See corresponding methods of MR::Tarantool::Box class.

Select, Call

These methods operate on SERVER at first, and then may try to query REPLICAS.

See corresponding methods of MR::Tarantool::Box class.

These methods have additional %options params:

is_replica => \$is_result_from_replica

If this option is set, then if the query to SERVER fails, REPLICAS will be queried one-by-one until query succeeds or the list ends, and $is_result_from_replica will be set to true, no matter whether any query succeeds or not.

Error, ErrorStr

Return error code or description (see <MR::Tarantool::Box|MR::Tarantool::Box/Error>).

LICENCE AND COPYRIGHT

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

SEE ALSO

http://tarantool.org

MR::Tarantool::Box