Submodule box.ctl
The box.ctl
submodule contains two functions: wait_ro
(wait until read-only)
and wait_rw
(wait until read-write).
The functions are useful during initialization of a server.
A particular use is for box_once().
For example, when a replica is initializing, it may call
a box.once()
function while the server is still in
read-only mode, and fail to make changes that are necessary
only once before the replica is fully initialized.
This could cause conflicts between a master and a replica
if the master is in read-write mode and the replica is in
read-only mode.
Waiting until “read only mode = false” solves this problem.
To see whether a function is already in read-only or read-write mode, check box.info.ro.
-
box.ctl.
wait_ro
([timeout]) Wait until
box.info.ro
is true.Parameters: - timeout (number) – maximum number of seconds to wait
Return: nil, or error may be thrown due to timeout or fiber cancellation
Example:
tarantool> box.info().ro --- - false ... tarantool> n = box.ctl.wait_ro(0.1) --- - error: timed out ...
-
box.ctl.
wait_rw
([timeout]) Wait until box.info.ro is false.
Parameters: - timeout (number) – maximum number of seconds to wait
Return: nil, or error may be thrown due to timeout or fiber cancellation
Example:
tarantool> box.ctl.wait_rw(0.1) --- ...
The box.ctl
submodule also contains two functions for the two
server trigger definitions: on_shutdown
and on_schema_init
.
Please, familiarize yourself with the mechanism of trigger functions before using them.
-
box.ctl.
on_shutdown
(trigger-function[, old-trigger-function]) Create a “shutdown trigger”. The
trigger-function
will be executed whenever os.exit() happens, or when the server is shut down after receiving a SIGTERM or SIGINT or SIGHUP signal (but not after SIGSEGV or SIGABORT or any signal that causes immediate program termination).Parameters: - trigger-function (function) – function which will become the trigger function
- old-trigger-function (function) – existing trigger function which will be replaced by trigger-function
Return: nil or function pointer
If the parameters are (nil, old-trigger-function), then the old trigger is deleted.
Details about trigger characteristics are in the triggers section.
-
box.ctl.
on_schema_init
(trigger-function[, old-trigger-function]) Create a “schema_init trigger”. The
trigger-function
will be executed when box.cfg{} happens for the first time. That is, theschema_init
trigger is called before the server’s configuration and recovery begins, and thereforebox.ctl.on_schema_init
must be called beforebox.cfg
is called.Parameters: - trigger-function (function) – function which will become the trigger function
- old-trigger-function (function) – existing trigger function which will be replaced by trigger-function
Return: nil or function pointer
If the parameters are (nil, old-trigger-function), then the old trigger is deleted.
A common use is: make a
schema_init
trigger function which creates abefore_replace
trigger function on a system space. Thus, since system spaces are created when the server starts, thebefore_replace
triggers will be activated for each tuple in each system space. For example, such a trigger could change the storage engine of a given space, or make a given space replica-local while a replica is being bootstrapped. Making such a change afterbox.cfg
is not reliable because other connections might use the database before the change is made.Details about trigger characteristics are in the triggers section.
Example:
Suppose that, before the server is fully up and ready for connections, you want to make sure that the engine of space
space_name
is vinyl. So you want to make a trigger that will be activated when a tuple is inserted in the_space
system space. In this case you could end up with a master that has space-name withengine='memtx'
and a replica that has space_name withengine='vinyl'
, with the same contents.function function_for_before_replace(old, new) if old == nil and new ~= nil and new[3] == 'space_name' and new[4] ~= 'vinyl' then return new:update{{'=', 4, 'vinyl'}} end end box.ctl.on_schema_init(function() box.space._space:before_replace(function_for_before_replace) end) box.cfg{replication='master_uri', ...}