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, the schema_init trigger is called before the server’s configuration and recovery begins, and therefore box.ctl.on_schema_init must be called before box.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 a before_replace trigger function on a system space. Thus, since system spaces are created when the server starts, the before_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 after box.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 with engine='memtx' and a replica that has space_name with engine='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', ...}