Reloading a module

Reloading a module in Lua

Here’s an example that illustrates the most typical case – “update and reload”.

1. Update the application file.

   For example, a module in /usr/share/tarantool/app.lua:

   local function start()
     -- initial version
     box.once("myapp:v1.0", function()
       box.schema.space.create("somedata")
       box.space.somedata:create_index("primary")
       ...
     end)
   
     -- migration code from 1.0 to 1.1
     box.once("myapp:v1.1", function()
       box.space.somedata.index.primary:alter(...)
       ...
     end)
   
     -- migration code from 1.1 to 1.2
     box.once("myapp:v1.2", function()
       box.space.somedata.index.primary:alter(...)
       box.space.somedata:insert(...)
       ...
     end)
   end
   
   -- start some background fibers if you need
   
   local function stop()
     -- stop all background fibers and clean up resources
   end
   
   local function api_for_call(xxx)
     -- do some business
   end
   
   return {
     start = start,
     stop = stop,
     api_for_call = api_for_call
   }
   

2. Update the instance file.

   For example, /etc/tarantool/instances.enabled/my_app.lua:

   #!/usr/bin/env tarantool
   --
   -- hot code reload example
   --
   
   box.cfg({listen = 3302})
   
   -- ATTENTION: unload it all properly!
   local app = package.loaded['app']
   if app ~= nil then
     -- stop the old application version
     app.stop()
     -- unload the application
     package.loaded['app'] = nil
     -- unload all dependencies
     package.loaded['somedep'] = nil
   end
   
   -- load the application
   log.info('require app')
   app = require('app')
   
   -- start the application
   app.start({some app options controlled by sysadmins})
   

   The important thing here is to properly unload the application and its dependencies.

3. Manually reload the application file.

   For example, using tarantoolctl:

   $ tarantoolctl eval my_app /etc/tarantool/instances.enabled/my_app.lua
   

Reloading a module in C

After you have compiled a new version of a C module (*.so shared library), call box.schema.func.reload(‘module-name’) from your Lua script to reload the module.

Starting in Tarantool version 2.3, reload() will create a temporary file to store the module if any of its functions is still running. The directory for this file is what is specified in the TMPDIR environment variable, or it is /tmp if the TMPDIR environment variable is blank.