Triggers

Triggers, also known as callbacks, are functions which the server executes when certain events happen.

To associate an event with a callback, pass the callback to the corresponding on_event function:

• box.session.on_connect() or box.session.on_disconnect(),
• box.session.on_auth(),
• space_object:on_replace() or space_object:before_replace(),
• box.on_commit() or box.on_rollback(),
• net.box.on_connect() or net.box.on_disconnect(),
• net.box.on_schema_reload(),
• box.ctl.on_schema_init() or box.ctl.on_shutdown(),
• swim_object:on_member_event(),
• box.session.on_access_denied().

Then the server will store the callback function and call it when the corresponding event happens.

All triggers have the following characteristics:

• Triggers are defined only by the ‘admin’ user.
• Triggers are stored in the Tarantool instance’s memory, not in the database. Therefore triggers disappear when the instance is shut down. To make them permanent, put function definitions and trigger settings into Tarantool’s initialization script.
• Triggers have low overhead. If a trigger is not defined, then the overhead is minimal: merely a pointer dereference and check. If a trigger is defined, then its overhead is equivalent to the overhead of calling a function.
• There can be multiple triggers for one event. In this case, triggers are executed in the reverse order that they were defined in.
• Triggers must work within the event context, that is, operate variables passed as the trigger function arguments. Triggers should not affect the global state of the program or change things unrelated to the event. If a trigger performs such calls as, for example, os.exit() or box.rollback(), the result of its execution is undefined.
• Triggers are replaceable. The request to “redefine a trigger” implies passing a new trigger function and an old trigger function to one of the on_event functions.
• The on_event functions all have parameters which are function pointers, and they all return function pointers. Remember that a Lua function definition such as function f() x = x + 1 end is the same as f = function () x = x + 1 end - in both cases f gets a function pointer. And trigger = box.session.on_connect(f) is the same as trigger = box.session.on_connect(function () x = x + 1 end) - in both cases trigger gets the function pointer which was passed.
• You can call any on_event function with no arguments to get a list of its triggers. For example, use box.session.on_connect() to return a table of all connect-trigger functions.
• Triggers can be useful in solving problems with replication. See details in Resolving replication conflicts.

Example:

Here we log connect and disconnect events into Tarantool server log.

log = require('log')

function on_connect_impl()
 log.info("connected "..box.session.peer()..", sid "..box.session.id())
end

function on_disconnect_impl()
 log.info("disconnected, sid "..box.session.id())
end

function on_auth_impl(user)
 log.info("authenticated sid "..box.session.id().." as "..user)
end

function on_connect() pcall(on_connect_impl) end
function on_disconnect() pcall(on_disconnect_impl) end
function on_auth(user) pcall(on_auth_impl, user) end

box.session.on_connect(on_connect)
box.session.on_disconnect(on_disconnect)
box.session.on_auth(on_auth)