Skip to content

Commit 39fe077

Browse files
authored
Adds description of the on_event callback to custom application roles (#5232)
* Adds description of the on_event callback to custom application roles * Added general info about custom roles as an intro to the section' * Fixes #4666
1 parent 633dfaf commit 39fe077

File tree

1 file changed

+35
-0
lines changed

1 file changed

+35
-0
lines changed

doc/platform/app/app_roles.rst

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,13 +64,42 @@ Creating a custom role
6464
Overview
6565
~~~~~~~~
6666

67+
A custom application role is an object which implements custom functions or logic adding to Tarantool's built-in roles and roles provided by third-party Lua modules.
68+
For example, a logging role can be created to add logging functionality on top of the built-in one.
69+
70+
Since version :doc:`3.4.0 </release/3.4.0>`, you can define an ``on_event`` callback for custom roles. The ``on_event`` callback is called
71+
every time a ``box.status`` system event is broadcasted.
72+
If multiple custom roles have the ``on_event`` callback defined, these callbacks are called one after another in the order
73+
defined by roles dependencies.
74+
75+
The ``on_event`` callback returns 3 arguments, when it is called:
76+
77+
- ``config``, which contains the configuration of the role;
78+
79+
- ``key``, which reflects the trigger event and is set to:
80+
81+
- ``config.apply`` if the callback was triggered by a configuration update;
82+
83+
- ``box.status`` if it was triggered by the ``box.status`` system event.
84+
- ``value``, which shows and logs the information about the instance status as in the trigger ``box.status`` system event.
85+
If the callback is triggered by a configuration update, the ``value`` shows the information of the most recent ``box.status`` system event.
86+
87+
.. NOTE::
88+
89+
- All ``on_event`` callbacks with the ``config.apply`` key are executed as a part of the configuration process.
90+
Process statuses ``ready`` or ``check_warnings`` are reached only after all such ``on_event`` callbacks are done.
91+
92+
- All ``on_event`` callbacks are executed inside of a ``pcall``. If an error is raised for a callback, it is logged
93+
with the ``error`` level and the series execution continues.
94+
6795
Creating a custom role includes the following steps:
6896

6997
#. (Optional) Define the role configuration schema.
7098
#. Define a function that validates a role configuration.
7199
#. Define a function that applies a validated configuration.
72100
#. Define a function that stops a role.
73101
#. (Optional) Define roles from which this custom role depends on.
102+
#. (Optional) Define the ``on_event`` callback function.
74103

75104
As a result, a role module should return an object that has corresponding functions and fields specified:
76105

@@ -81,6 +110,12 @@ As a result, a role module should return an object that has corresponding functi
81110
apply = function() -- ... -- end,
82111
stop = function() -- ... -- end,
83112
dependencies = { -- ... -- },
113+
on_event = function(config, key, value)
114+
local log = require('log')
115+
log.info('roles_cfg.my_role.foo: ' .. config.foo)
116+
log.info('on_event is triggered by ' .. key)
117+
log.info('is_ro: ' .. value.is_ro)
118+
end,
84119
}
85120
86121
The examples below show how to do this.

0 commit comments

Comments
 (0)