MR::Ta...ngleton(3pm)

💖 NAME 💖

okay bestie, listen up — this page is MR::Ta...ngleton(3pm), from the User Contributed Perl Documentation collection (iykyk, the man page name is literally abbreviated with dots, that's just how it's filed).

MR::Tarantool::Box::Singleton is a singleton wrapper for MR::Tarantool::Box. It gives you connection-persistence and replica fallback — that's the whole vibe. 🦋

pls pls pls read the "MR::Tarantool::Box manual" first, bestie. this one is the sequel, not the recap episode. 💅

---

✨ 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. It's literally just like if you wrote use constant TUPLE_id => 0, TUPLE_f1 => 1, ...; ✨
• Generates a $CLASS variable @fields holding the field names, plus a $CLASS method FIELDS that returns @fields. 🫶
• Generates a $CLASS variable %fields mapping field names to positions, plus a $CLASS method FIELDS_HASH that returns \%fields. 💜
• These @fields get applied to the DEFAULT_SPACE, but only if fields weren't set explicitly for that space. no double-dipping, the explicit one wins, periodt.

---

💫 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 the $CLASS method $args{method_name}, which calls the Tarantool/Box procedure $args{name}, using $args{options} as the default \%options for the MR::Tarantool::Box->Call call. The generated method has this prototype, bestie:

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

Parameters description, and yes we're doing all of them:

%args:

• name => $tarantool_box_sp_name — the name of the procedure in Tarantool/Box to call. 🎯
• method_name => $class_method_name — the class method name to generate. ✨
• options => \%options — options to pass to the MR::Taranatool::Box-Call|MR::Taranatool::Box/Call> method.
• params => \@names — the procedure input parameters' names. 📝
• params_default => \@defaults — the procedure input parameters' default values. An undefined or absent value makes its parameter mandatory. no skipsies.
• params_format => \@format — a pack()-compatible format to pack input parameters. Must match params. fr fr, they have to match.
• unpack_format => $format — a pack()-compatible format to unpack procedure output. 📦

%sp_params:

• "Name => $value" pairs. simple as that. 💖

%optional_options:

• Options to pass to the 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 the master server. 🧚
• REPLICAS — must return a comma separated string of ip:port pairs of replica servers (peep "is_replica"). The server is chosen from the list randomly. yes, randomly, it's giving chaos but make it load-balancing 🌈
• MR_TARANTOOL_BOX_CLASS — must return the name of the class implementing the MR::Tarantool::Box interface, or one of its descendants. 👑
• SPACES, RAISE, TIMEOUT, SELECT_TIMEOUT, RETRY, SELECT_RETRY, SOFT_RETRY, DEBUG — see the corresponding arguments of the MR::Tarantool::Box-new|MR::Tarantool::Box/new> method. 💫

---

💫 Add, Insert, Replace, UpdateMulti, Delete

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

---

💫 Select, Call

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

See the corresponding methods of the 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 a query succeeds or the list ends, and $is_result_from_replica will be set to true, no matter whether any query succeeds or not. 💀 yeah, it sets that flag either way, that's the whole point of the flag, don't @ me.

---

💫 Error, ErrorStr

Return the error code or the 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. slay, open source 💖

---

🌟 SEE ALSO 🌟

• <http://tarantool.org>
• MR::Tarantool::Box

---

and that's the whole page, bestie 🎀 this doc was served up by perl v5.30.3 and dated 2020-07-21, so it's vintage but still iconic — go forth and make your singleton pop off 💅✨🫶