the experimental.connpool module

[TarantoolBot]

Related dev. issue(s): tarantool/tarantool#9842
Related doc. issue(s): #4151, #4156

Product: Tarantool
Since: 3.1
Root document:

• https://www.tarantool.io/en/doc/latest/reference/reference_lua/
• See also: https://www.tarantool.io/en/doc/latest/release/3.1.0/#experimental-connpool-module

Related cartridge docs:

• https://www.tarantool.io/en/doc/2.11/book/cartridge/cartridge_api/modules/cartridge.pool/
• https://www.tarantool.io/en/doc/2.11/book/cartridge/cartridge_api/modules/cartridge.rpc/

SME: @ ImeevMA

Details

The experimental.connpool module contains some functions that allow you
to retrieve the names of instances from the configuration that satisfy
specified conditions, or to execute a function on one of these
instances. Additionally, this module has a function that returns the
active connection to the instance with the specified name.

Currently this module contains three functions:

1. connect() takes an instance name and options and returns the active
   connection to the instance with the specified name. The
   connect_timeout and fetch_schema options are passed directly to
   net.box.connect(). The wait_connected option is also passed to
   net.box.connect(), but here it can be true or false, numeric
   values are not allowed.
2. filter() accepts only options as its only argument. It returns an
   array of instance names that match the provided options. Currently only
   two options are supported:
   a) labels that instances must have ( New labels in config schema #4096)
   b) roles that instances must have ( Roles #3702)
3. call takes the name of the function to execute, arguments for this
   function, and options. The labels and roles options are used to
   select candidates on which the function will be executed. If the
   prefer_local option is false, call will try to connect to a random
   candidate until a connection is established or there are no more
   candidates. If the prefer_local option is true or nil and the instance
   in which call is executed is one of the candidates, call will
   attempt to connect to that instance first. Moreover, call has options
   timeout, buffer, on_push, on_push_ctx and is_async, which are
   passed directly to net.box.call(). Note that the connection option
   works for the net.box.call() part. The potential maximum execution
   time is <number of candidates> * <default connect_timeout for net.box.connect()> + connection.
   Requested by @ ImeevMA in tarantool/tarantool@9355933.