---
name: "MR::Tarantool::Box::Singleton"
section: "3pm"
platform: "linux"
package: "libmr-tarantool-perl"
version: "0.0.24-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/MR::Tarantool::Box::Singleton"
---

# MR::Tarantool::Box::Singleton(3pm)

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

## 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