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

perl v5.30.3                                       2020-07-21                 MR::Tarantool::Box::Singleton(3pm)