From 334ddfa092b32dc22addf06ca1915af0c8ad91d8 Mon Sep 17 00:00:00 2001 From: andreyaksenov Date: Mon, 1 Jul 2024 17:07:36 +0300 Subject: [PATCH 1/4] Document the 'experimental.connpool' module --- doc/reference/reference_lua/connpool.rst | 175 +++++++++++++++++++++++ doc/reference/reference_lua/index.rst | 1 + 2 files changed, 176 insertions(+) create mode 100644 doc/reference/reference_lua/connpool.rst diff --git a/doc/reference/reference_lua/connpool.rst b/doc/reference/reference_lua/connpool.rst new file mode 100644 index 0000000000..a56712aef3 --- /dev/null +++ b/doc/reference/reference_lua/connpool.rst @@ -0,0 +1,175 @@ +.. _connpool_module: + +Module experimental.connpool +============================ + +**Since:** :doc:`3.1.0 ` + +.. important:: + + ``experimental.connpool`` is an experimental module and is subject to changes. + +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. + + +.. _connpool_module_load: + +Loading a module +---------------- + +To load the ``experimental.connpool`` module, use the ``require()`` directive: + +.. code-block:: lua + + local connpool = require('experimental.connpool') + + +.. _connpool_module_api_reference: + +API Reference +------------- + +.. container:: table + + .. rst-class:: left-align-column-1 + .. rst-class:: left-align-column-2 + + .. list-table:: + :widths: 35 65 + + * - **Functions** + - + + * - :ref:`connpool.call() ` + - Execute the specified function on a remote instance + + * - :ref:`connpool.connect() ` + - Create a connection to the specified instance + + * - :ref:`connpool.filter() ` + - Get names of instances that match the specified conditions + + + + + +.. module:: connpool + +.. _connpool_module_api_reference_functions: + +Functions +~~~~~~~~~ + +.. _connpool_module_call: + +.. function:: call(func_name, args, opts) + + Execute the specified function on a remote instance. + + .. NOTE:: + + You need to grant the ``execute`` :ref:`permission ` for the specified function to a user used for replication to execute this function on a remote instance. + + :param string func_name: a name of the function to execute. + :param table/nil args: function arguments. + :param table/nil opts: options used to select candidates on which the function should be executed: + + * ``labels`` -- the :ref:`labels ` an instance has. + * ``roles`` -- the :ref:`roles ` of an instance. + * ``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. + * ``mode`` -- a mode that allows filtering candidates based on their read-only status. This option accepts the following values: + + * ``nil`` -- 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 :ref:`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 :ref:`box_session-push`. + * ``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`. + * ``is_async`` -- whether to wait for the result of the call. + + :return: a function's return value. + + **Example** + + In the example below, the following conditions are specified to choose an instance to execute the :ref:`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. + + .. code-block:: lua + + local connpool = require('experimental.connpool') + local buckets_count = connpool.call('vshard.storage.buckets_count', + nil, + { roles = { 'roles.crud-storage' }, + labels = { dc = 'east' }, + mode = 'ro' } + ) + + +.. _connpool_module_connect: + +.. function:: connect(instance_name, opts) + + Create a connection to the specified instance. + + :param string instance_name: an instance name. + :param table/nil opts: none, any, or all of the following parameters: + + * ``connect_timeout`` -- a connection timeout (in seconds). + * ``wait_connected`` -- if ``true``, 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. + + :return: a :ref:`net.box ` connection. + + **Example** + + In the example below, ``connect()`` is used to create the active connection to ``storage-b-002``: + + .. code-block:: lua + + 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 a remote instance, for example, select data from a space using :ref:`conn.space.\:select() `. + + +.. _connpool_module_filter: + +.. function:: filter(opts) + + Get names of instances that match the specified conditions. + + :param table/nil opts: none, any, or all of the following parameters: + + * ``labels`` -- the :ref:`labels ` an instance has. + * ``roles`` -- the :ref:`roles ` of an instance. + * ``mode`` -- a mode that allows filtering candidates based on their read-only status. This option accepts the following values: + + * ``nil`` -- 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. + + :return: 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: + + .. code-block:: lua + + local connpool = require('experimental.connpool') + local instance_names = connpool.filter({ roles = { 'roles.crud-storage' }, + labels = { dc = 'east' } }) diff --git a/doc/reference/reference_lua/index.rst b/doc/reference/reference_lua/index.rst index 2002f75e4f..72e7204179 100644 --- a/doc/reference/reference_lua/index.rst +++ b/doc/reference/reference_lua/index.rst @@ -33,6 +33,7 @@ This reference covers Tarantool's built-in Lua modules. decimal digest errno + connpool fiber fio fun From 5be239a1ea03d4e76160e4d179ddce6bfddee634 Mon Sep 17 00:00:00 2001 From: andreyaksenov Date: Wed, 3 Jul 2024 15:23:53 +0300 Subject: [PATCH 2/4] Specify default values --- doc/reference/reference_lua/connpool.rst | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/doc/reference/reference_lua/connpool.rst b/doc/reference/reference_lua/connpool.rst index a56712aef3..53f1754cf6 100644 --- a/doc/reference/reference_lua/connpool.rst +++ b/doc/reference/reference_lua/connpool.rst @@ -76,10 +76,14 @@ Functions * ``labels`` -- the :ref:`labels ` an instance has. * ``roles`` -- the :ref:`roles ` of an instance. - * ``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. + * ``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`` -- don't check the read-only status of instances. + * ``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. @@ -125,7 +129,11 @@ Functions :param table/nil opts: none, any, or all of the following parameters: * ``connect_timeout`` -- a connection timeout (in seconds). - * ``wait_connected`` -- if ``true``, the connection is blocked until it is established. If ``false``, the connection is returned immediately. + * ``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. :return: a :ref:`net.box ` connection. From daf43753045809e70001e2416f378e464f34f126 Mon Sep 17 00:00:00 2001 From: andreyaksenov Date: Wed, 3 Jul 2024 17:25:22 +0300 Subject: [PATCH 3/4] Update per review --- doc/reference/reference_lua/connpool.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/reference/reference_lua/connpool.rst b/doc/reference/reference_lua/connpool.rst index 53f1754cf6..48a7e8a4df 100644 --- a/doc/reference/reference_lua/connpool.rst +++ b/doc/reference/reference_lua/connpool.rst @@ -11,6 +11,11 @@ Module experimental.connpool 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. +.. NOTE:: + + Note that the execution time for ``experimental.connpool`` functions depends on the number of instances and the time required to connect to each instance. + + .. _connpool_module_load: @@ -162,7 +167,7 @@ Functions * ``roles`` -- the :ref:`roles ` of an instance. * ``mode`` -- a mode that allows filtering candidates based on their read-only status. This option accepts the following values: - * ``nil`` -- don't check the read-only status of instances. + * ``nil`` (default) -- don't check the read-only status of instances. * ``ro`` -- consider only read-only instances. * ``rw`` -- consider only read-write instances. From 28ba6720ac5d508dae1d46cff89dd8edf584d47f Mon Sep 17 00:00:00 2001 From: andreyaksenov Date: Thu, 4 Jul 2024 11:46:47 +0300 Subject: [PATCH 4/4] Update per TW review --- doc/reference/reference_lua/connpool.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/reference/reference_lua/connpool.rst b/doc/reference/reference_lua/connpool.rst index 48a7e8a4df..4fa71a4b30 100644 --- a/doc/reference/reference_lua/connpool.rst +++ b/doc/reference/reference_lua/connpool.rst @@ -9,7 +9,7 @@ Module experimental.connpool ``experimental.connpool`` is an experimental module and is subject to changes. -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. +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. .. NOTE:: @@ -73,7 +73,8 @@ Functions .. NOTE:: - You need to grant the ``execute`` :ref:`permission ` for the specified function to a user used for replication to execute this function on a remote instance. + The function is executed on behalf of the user that maintains replication in the cluster. + Ensure that this user has the ``execute`` :ref:`permission ` for the function to execute. :param string func_name: a name of the function to execute. :param table/nil args: function arguments. @@ -152,7 +153,7 @@ Functions 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 a remote instance, for example, select data from a space using :ref:`conn.space.\:select() `. + Once you have a connection, you can execute requests on the remote instance, for example, select data from a space using :ref:`conn.space.\:select() `. .. _connpool_module_filter: