diff --git a/doc/platform/app/app_roles.rst b/doc/platform/app/app_roles.rst index e39c39759..454d89664 100644 --- a/doc/platform/app/app_roles.rst +++ b/doc/platform/app/app_roles.rst @@ -220,12 +220,12 @@ You can find the full example here: `application_role_cfg `, you can define the ``on_event`` callback for custom roles. The ``on_event`` callback is called +Since version :doc:`3.3.1 `, you can define the ``on_event`` callback for custom roles. The ``on_event`` callback is called every time a ``box.status`` system event is broadcasted. If multiple custom roles have the ``on_event`` callback defined, these callbacks are called one after another in the order defined by roles dependencies. -The ``on_event`` callback returns 3 arguments, when it is called: +The ``on_event`` callback accepts 3 arguments, when it is called: - ``config``, which contains the configuration of the role; @@ -234,7 +234,7 @@ The ``on_event`` callback returns 3 arguments, when it is called: - ``config.apply`` if the callback was triggered by a configuration update; - ``box.status`` if it was triggered by the ``box.status`` system event. -- ``value``, which shows and logs the information about the instance status as in the trigger ``box.status`` system event. +- ``value``, which shows the information about the instance status as in the trigger ``box.status`` system event. If the callback is triggered by a configuration update, the ``value`` shows the information of the most recent ``box.status`` system event. .. NOTE:: @@ -245,30 +245,7 @@ The ``on_event`` callback returns 3 arguments, when it is called: - All ``on_event`` callbacks are executed inside of a ``pcall``. If an error is raised for a callback, it is logged with the ``error`` level and the series execution continues. -.. code-block:: lua - - return { - validate = function() end, - apply = function() - _G.foo = 0 - end, - stop = function() - _G.foo = -1 - _G.bar = nil - end, - on_event = function(config, key, value) - assert(_G.foo >= 0) - assert(config == 12345) - if(_G.foo == 0) then - assert(key == 'config.apply') - else - assert(key == 'box.status') - end - _G.is_ro = value.is_ro - _G.foo = _G.foo + 1 - _G.bar = config - end, - } +The example of the ``on_event`` callback is provided in the :ref:`spaces creation ` article below. .. _roles_create_custom_role_init: @@ -306,14 +283,38 @@ You can check an instance state by subscribing to the ``box.status`` event using -- ... end) - .. NOTE:: Given that a role may be enabled when an instance is already in read-write mode, you also need to execute schema initialization code from :ref:`apply() `. To make sure a space is created only once, use the :ref:`if_not_exists ` option. +Since version :doc:`3.3.1 `, you can define space creation in a role via +the ``on_event`` :ref:`callback function `. +See the example of such definition below: + +.. code-block:: lua + + return { + validate = function() end, + apply = function() end, + stop = function() end, + on_event = function(config, key, value) + -- Can only create spaces on RW. + if value.is_ro then + return + end + -- Assume the role config is a table. + if type(config) ~= 'table' then + error('Config must be a table') + end + local space_name = config.space_name or 'default' + box.schema.space.create(space_name, { + if_not_exists = true, + }) + end + } .. _roles_life_cycle: