Module experimental.connpool

Since: 3.1.0

The experimental.connpool module provides a set of features for connecting to remote cluster instances and for executing remote procedure calls on an instance that satisfies the specified criteria.

To load the experimental.connpool module, use the require() directive:

 
local connpool = require('experimental.connpool')

Execute the specified function on a remote instance.

Parameters:

• func_name (string) — a name of the function to execute.

• args (table/nil) — function arguments.

• opts (table/nil) — options used to select candidates on which the function should be executed:

• labels – the labels an instance has.

• roles – the roles of an instance.

• prefer_local – whether to prefer a local or remote instance to execute call() on:

  • if true (default), call() tries to execute the specified function on a local instance.
  • if false, call() tries to connect to a random candidate until a connection is established.

• mode – a mode that allows filtering candidates based on their read-only status. This option accepts the following values:

  • nil (default) – don't check the read-only status of instances.
  • ro – consider only read-only instances.
  • rw – consider only read-write instances.
  • prefer_ro – consider read-only instances, then read-write instances.
  • prefer_rw – consider read-write instances, then read-only instances.

• instances – the names of instances to consider as candidates.

• replicasets – the names of replica sets whose instances are considered as candidates.

• groups – the names of groups whose instances are considered as candidates.

• timeout – a connection timeout (in seconds).

• buffer – a buffer used to read a returned value.

• on_push – a function to execute when the client receives an out-of-band message. Learn more from box_session-push.

• on_push_ctx – an argument of the function executed when the client receives an out-of-band message. Learn more from box_session-push.

• is_async – whether to wait for the result of the call.

Returns

a function's return value.

Example

In the example below, the following conditions are specified to choose an instance to execute the vshard.storage.buckets_count function:

• An instance has the roles.crud-storage role.
• An instance has the dc label set to east.
• An instance is read-only.

 
local connpool = require('experimental.connpool')local buckets_count = connpool.call('vshard.storage.buckets_count',        nil,        { roles = { 'roles.crud-storage' },          labels = { dc = 'east' },          mode = 'ro' })

Create a connection to the specified instance.

Parameters:

• instance_name (string) — an instance name.

• opts (table/nil) — none, any, or all of the following parameters:

• connect_timeout – a connection timeout (in seconds).

• wait_connected – whether to block the connection until it is established:

  • if true (default), the connection is blocked until it is established.
  • if false, the connection is returned immediately.

• fetch_schema – whether to fetch schema changes from a remote instance.

Returns

a net.box connection.

Example

In the example below, connect() is used to create the active connection to storage-b-002:

 
local connpool = require('experimental.connpool')local conn = connpool.connect("storage-b-002", { fetch_schema = true })

Once you have a connection, you can execute requests on the remote instance, for example, select data from a space using conn.space.:select().

Get names of instances that match the specified conditions.

Parameters:

• opts (table/nil) — none, any, or all of the following parameters:

• labels – the labels an instance has.

• roles – the roles of an instance.

• mode – a mode that allows filtering candidates based on their read-only status. This option accepts the following values:

  • nil (default) – don't check the read-only status of instances.
  • ro – consider only read-only instances.
  • rw – consider only read-write instances.

• instances – the names of instances to consider as candidates.

• replicasets – the names of replica sets whose instances are considered as candidates.

• groups – the names of groups whose instances are considered as candidates.

Returns

an array of instance names.

Example

In the example below, filter() should return a list of instances with the roles.crud-storage role and specified label value:

 
local connpool = require('experimental.connpool')local instance_names = connpool.filter({ roles = { 'roles.crud-storage' },                                         labels = { dc = 'east' } })