Allow hotswapping with lua require.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bench
rockspec
src/hotswap
test Remove useless debug prints. Jan 6, 2016
.travis.yml
LICENSE
README.md Add gitter badge. Jan 22, 2016

README.md

Build Status Coverage Status Join the chat at https://gitter.im/saucisson/lua-hotswap

Require with hotswapping

Sometimes, we would like to reload automatically an updated module within a long-running program. The hotswap module provides such functionality, using various backends for change detection.

See Wikipedia

Install

This module is available in luarocks:

    luarocks install hotswap

Example

The easiest way to use this library is as below:

    local hotswap  = require "hotswap".new ()
    local mymodule = hotswap.require "mymodule"
    ...

Note that this is useless, as there is not hotswapping in the default behavior. Note also that the .new () can be omitted if you need only one instance of the hotswap module.

An easy way to use hotswapping is to require the updated module within a loop. The following code reloads the module only when its file hash hash changed:

    local hotswap = require "hotswap.hash"
    while true do
      local mymodule = hotswap.require "mymodule"
      ...
    end

The same applies with file modification date given by lfs:

    local hotswap = require "hotswap.lfs"
    while true do
      local mymodule = hotswap.require "mymodule"
      ...
    end

A more advanced use is for instance with lua-ev in a idle loop:

    local ev      = require "ev"
    local hotswap = require "hotswap.ev"
    ev.Idle.new (function ()
      local mymodule = hotswap.require "mymodule"
      ...
    end):start (ev.Loop.default)
    ev.Loop.default:loop ()

The hotswap can even replace the require function easily:

    require = require "hotswap.xxx".require

Backends

Currently, the following backends are supported:

  • hotswap: the default backend does not perform any change detection, see this example;
  • hotswap.ev: this backend detects module changes using lua-ev, see this example;
  • hotswap.hash: this backend detects module changes by checking file hashes using xxhah, see this example;
  • hotswap.http: this backend loads modules from a HTTP server, and avoids useless downloads, see this example;
  • hotswap.lfs: this backend detects module changes by observing file modification date using luafilesystem, see this example.

Notice that the dependencies for each backend are not listed in the rockspec. Make sure to install them!

Compatibility

This module makes use of package.searchers, available from Lua 5.2. If you are running under Lua 5.1 or LuaJIT, a fake package.searchers will be automatically created.

Benchmarks

The bench directory contains benchmarks for the backends. They can be run using:

    cd bench/
    for bench in bench-*.lua
    do
      echo ${bench}
      luajit ${bench}
    done
    cd ..

Test

Tests are written for busted.

  busted test/*.lua