Module cartridge.roles¶
Role management (internal module).
The module consolidates all the role management functions:
cfg
, some getters, validate_config
and apply_config
.
The module is almost stateless, it’s only state is a collection of registered roles.
(Added in v1.2.0-20)
Functions¶
reload ()¶
Perform hot-reload of cartridge roles code.
This is an experimental feature, it’s only allowed if the application
enables it explicitly: cartridge.cfg({roles_reload_allowed =
true})
.
Reloading starts by stopping all roles and restoring the initial state. It’s supposed that a role cleans up the global state when stopped, but even if it doesn’t, cartridge kills all fibers and removes global variables and HTTP routes.
All Lua modules that were loaded during cartridge.cfg are unloaded, including supplementary modules required by a role. Modules, loaded before cartridge.cfg aren’t affected.
Instance performs roles reload in a dedicated state ReloadingRoles
.
If reload fails, the instance enters the ReloadError
state, which
can later be retried. Otherwise, if reload succeeds, instance
proceeds to the ConfiguringRoles
state and initializes them as
usual with validate_config()
, init()
, and apply_config()
callbacks.
Hot-reload could be forbidden in runtime with forbid_reload
function.
Returns:
(boolean) true
Or
(nil)
(table) Error description
forbid_reload ()¶
Forbid hot-reload of cartridge roles code.
Returns:
(boolean) true
Or
(nil)
(table) Error description
allow_reload ()¶
Allow hot-reload of cartridge roles code.
Returns:
(boolean) true
Or
(nil)
(table) Error description
is_reload_forbidden ()¶
Returns true if hot-reload of cartridge roles code is forbidden.
Returns:
(boolean) true
Or
(nil)
(table) Error description
before_apply_config (table, string)¶
Do additional job before the roles configuration applying.
Parameters:
table: conf
string: state
Returns:
boolean true
on_apply_config (table, string)¶
Do additional job after the roles configuration applying.
Parameters:
table: conf
string: state
Returns:
boolean true
Local Functions¶
cfg (module_names)¶
Load modules and register them as Cartridge Roles.
This function is internal, it’s called as a part of cartridge.cfg.
Parameters:
module_names: ({string,…})
Returns:
(boolean) true
Or
(nil)
(table) Error description
get_all_roles ()¶
List all registered roles.
Hidden and permanent roles are listed too.
Returns:
get_known_roles ()¶
List registered roles names.
Hidden roles are not listed as well as permanent ones.
Returns:
get_enabled_roles_without_deps ()¶
List top-level roles names.
Dependencies of top-level roles of the replicaset, hidden roles are not listed as well as permanent ones.
Returns:
get_enabled_roles (roles)¶
Roles to be enabled on the server. This function returns all roles that will be enabled including their dependencies (both hidden and not) and permanent roles. By default, only permanent roles are returned. When you pass table with the roles names as an argument, This function also checks their dependencies and returns them as well.
Parameters:
roles: ({string,…} or {[string]=boolean,…})
Returns:
get_role_dependencies (role_name)¶
List role dependencies. Including sub-dependencies.
Parameters:
role_name: (string)
Returns:
validate_config (conf_new, conf_old)¶
Validate configuration by all roles.
Parameters:
Returns:
(boolean) true
Or
(nil)
(table) Error description
apply_config (conf, opts, is_master)¶
Apply the role configuration.
Parameters:
Returns:
(boolean) true
Or
(nil)
(table) Error description
stop ()¶
Stop all roles.