Global modules

By default modules are per-host in Prosody. This allows for a degree of separation between different services in the same Prosody instance. For example it allows different configuration for each host, and for some hosts to have modules that other hosts don't.

However sometimes it is necessary for a module to be loaded only once in a given Prosody instance. Often this is because it needs to manage or access some shared resource, and multiple host modules would conflict with each other.

To make a module global, simply:

    module:set_global();

This should always be the first thing your module does. It sets module.host to * to indicate that the module is now global and not specific to any host. Attempts to load the same global module twice will fail with "module already loaded" errors.

Shared modules

Prosody supports what are known as 'shared' modules. On the surface these are normal global modules (they still call module:set_global()). The main difference is that they implement a function, module.add_host:

   module:log("debug", "Hello world from the global module!");
 
   function module.add_host(module)
       module:log("debug", "Hello world from host %s!", module.host);
   end

This function is called whenever the module would be loaded onto a new host if it wasn’t global. The module.add_host function receives its very own host-specific module, so it can access the host-specific API as if it was a real module on that host.

This mechanism allows a global module to have per-host aspects (such as hooking per-host events), and allows the user to manage them as if they were real host-specific modules.

There is no module.remove_host. To handle a shared module being unloaded from a module, you simply implement module.unload on the host-specific module as you would normally:

   module:log("debug", "Hello world from the global module!");
   function module.add_host(module)
       module:log("debug", "Hello world from host %s!", module.host);
 
       -- Called on unload from this host:
       function module.unload()
           module:log("debug", "Being unloaded from %s :(", module.host);
       end
   end

Prosody transparently handles load, unload and reload for shared modules.