Skip to content

Commit d684baf

Browse files
committed
Document the 'experimental.connpool' module
1 parent 96e100a commit d684baf

File tree

2 files changed

+173
-0
lines changed

2 files changed

+173
-0
lines changed
Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
.. _connpool_module:
2+
3+
Module experimental.connpool
4+
============================
5+
6+
**Since:** :doc:`3.1.0 </release/3.1.0>`
7+
8+
.. important::
9+
10+
``experimental.connpool`` is an experimental module and is subject to changes.
11+
12+
An ``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.
13+
14+
15+
.. _connpool_module_load:
16+
17+
Loading a module
18+
----------------
19+
20+
To load the ``experimental.connpool`` module, use the ``require()`` directive:
21+
22+
.. code-block:: lua
23+
24+
connpool = require('experimental.connpool')
25+
26+
27+
.. _connpool_module_api_reference:
28+
29+
API Reference
30+
-------------
31+
32+
.. container:: table
33+
34+
.. rst-class:: left-align-column-1
35+
.. rst-class:: left-align-column-2
36+
37+
.. list-table::
38+
:widths: 35 65
39+
40+
* - **Functions**
41+
-
42+
43+
* - :ref:`connpool.call() <connpool_module_call>`
44+
- Execute the specified function on a remote instance
45+
46+
* - :ref:`connpool.connect() <connpool_module_connect>`
47+
- Create a connection to the specified instance
48+
49+
* - :ref:`connpool.filter() <connpool_module_filter>`
50+
- Get names of instances that match the specified conditions
51+
52+
53+
54+
55+
56+
.. module:: connpool
57+
58+
.. _connpool_module_api_reference_functions:
59+
60+
Functions
61+
~~~~~~~~~
62+
63+
.. _connpool_module_call:
64+
65+
.. function:: call(func_name, args, opts)
66+
67+
Execute the specified function on a remote instance.
68+
69+
.. NOTE::
70+
71+
You need to grant the ``execute`` :ref:`permission <configuration_credentials_managing_users_roles_granting_privileges>` for the specified function to a user used for replication to execute this function on a remote instance.
72+
73+
:param string func_name: a name of the function to execute.
74+
:param table/nil args: function arguments.
75+
:param table/nil opts: options used to select candidates on which the function should be executed:
76+
77+
* ``labels`` -- the :ref:`labels <configuration_reference_labels>` an instance has.
78+
* ``roles`` -- the :ref:`roles <configuration_application_roles>` of an instance.
79+
* ``prefer_local`` -- if ``true``, ``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.
80+
* ``mode`` -- a mode that allows filtering candidates based on their read-only status. This option accepts the following values:
81+
82+
* ``nil`` -- don't check the read-only status of instances.
83+
* ``ro`` -- consider only read-only instances.
84+
* ``rw`` -- consider only read-write instances.
85+
* ``prefer_ro`` -- consider read-only instances, then read-write instances.
86+
* ``prefer_rw`` -- consider read-write instances, then read-only instances.
87+
88+
* ``instances`` -- the names of instances to consider as candidates.
89+
* ``replicasets`` -- the names of replica sets whose instances are considered as candidates.
90+
* ``groups`` -- the names of groups whose instances are considered as candidates.
91+
* ``timeout`` -- a connection timeout (in seconds).
92+
* ``buffer`` -- a :ref:`buffer <buffer-module>` used to read a returned value.
93+
* ``on_push`` -- a function to execute when the client receives an out-of-band message. Learn more from :ref:`box_session-push`.
94+
* ``on_push_ctx`` -- an argument of the function executed when the client receives an out-of-band message. Learn more from :ref:`box_session-push`.
95+
* ``is_async`` -- whether to wait for the result of the call.
96+
97+
:return: a function's return value.
98+
99+
**Example**
100+
101+
In the example below, the following conditions are specified to choose an instance to execute the :ref:`vshard.storage.buckets_count <storage_api-buckets_count>` function:
102+
103+
* An instance has the ``roles.crud-storage`` role.
104+
* An instance has the ``dc`` label set to ``east``.
105+
* An instance is read-only.
106+
107+
.. code-block:: lua
108+
109+
local buckets_count = connpool.call('vshard.storage.buckets_count',
110+
nil,
111+
{ roles = { 'roles.crud-storage' },
112+
labels = { dc = 'east' },
113+
mode = 'ro' }
114+
)
115+
116+
117+
.. _connpool_module_connect:
118+
119+
.. function:: connect(instance_name, opts)
120+
121+
Create a connection to the specified instance.
122+
123+
:param string instance_name: an instance name.
124+
:param table/nil opts: none, any, or all of the following parameters:
125+
126+
* ``connect_timeout`` -- a connection timeout (in seconds).
127+
* ``wait_connected`` -- if ``true``, the connection is blocked until it is established. If ``false``, the connection is returned immediately.
128+
* ``fetch_schema`` -- whether to fetch schema changes from a remote instance.
129+
130+
:return: a :ref:`net.box <net_box-module>` connection.
131+
132+
**Example**
133+
134+
In the example below, ``connect()`` is used to create the active connection to ``storage-b-002``:
135+
136+
.. code-block:: lua
137+
138+
local conn = connpool.connect("storage-b-002", { fetch_schema = true })
139+
140+
Once you have a connection, you can execute requests on a remote instance, for example, select data from a space using :ref:`conn.space.\<space-name\>:select() <conn-select>`.
141+
142+
143+
.. _connpool_module_filter:
144+
145+
.. function:: filter(opts)
146+
147+
Get names of instances that match the specified conditions.
148+
149+
:param table/nil opts: none, any, or all of the following parameters:
150+
151+
* ``labels`` -- the :ref:`labels <configuration_reference_labels>` an instance has.
152+
* ``roles`` -- the :ref:`roles <configuration_application_roles>` of an instance.
153+
* ``mode`` -- a mode that allows filtering candidates based on their read-only status. This option accepts the following values:
154+
155+
* ``nil`` -- don't check the read-only status of instances.
156+
* ``ro`` -- consider only read-only instances.
157+
* ``rw`` -- consider only read-write instances.
158+
159+
* ``instances`` -- the names of instances to consider as candidates.
160+
* ``replicasets`` -- the names of replica sets whose instances are considered as candidates.
161+
* ``groups`` -- the names of groups whose instances are considered as candidates.
162+
163+
:return: an array of instance names.
164+
165+
**Example**
166+
167+
In the example below, ``filter()`` should return a list of instances with the ``roles.crud-storage`` role and specified label value:
168+
169+
.. code-block:: lua
170+
171+
local instance_names = connpool.filter({ roles = { 'roles.crud-storage' },
172+
labels = { dc = 'east' } })

doc/reference/reference_lua/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ This reference covers Tarantool's built-in Lua modules.
3333
decimal
3434
digest
3535
errno
36+
connpool
3637
fiber
3738
fio
3839
fun

0 commit comments

Comments
 (0)