Using Lua/WSAPI with uWSGI

Updated for uWSGI 2.0

Building the plugin

The lua plugin is part of the official uWSGI distribution (official modifier 6) and it is availale in the plugins/lua directory.

The plugin support lua 5.1, lua 5.2 and luajit.

By default lua 5.1 is assumed

As always there are various ways to build and install Lua support:

from sources directory:

  1. make lua

with the installer (the resulting binary will be in /tmp/uwsgi)

  1. curl http://uwsgi.it/install | bash -s lua /tmp/uwsgi

or you can build it as a plugin

  1. python uwsgiconfig.py --plugin plugins/lua

or (if you already have a uwsgi binary)

  1. uwsgi --build-plugin plugins/lua

The build system (check uwsgiplugin.py in plugins/lua directory for more details) uses pkg-config to find headers and libraries.

You can specify the pkg-config module to use with the UWSGICONFIG_LUAPC environment variable.

As an example

  1. UWSGICONFIG_LUAPC=lua5.2 make lua

will build a uwsgi binary for lua 5.2

as well as

  1. UWSGICONFIG_LUAPC=luajit make lua

will build a binary with luajit

If you do not want to rely on the pkg-config tool you can manually specify the includes and library directories as well as the lib name with the following environment vars:

  1. UWSGICONFIG_LUAINC=<directory>
  2. UWSGICONFIG_LUALIBPATH=<directory>
  3. UWSGICONFIG_LUALIB=<name>

Why Lua ?

If you came from other object oriented languages, you may find lua for web development a strange choice.

Well, you have to consider one thing when exploring Lua: it is fast, really fast and consume very few resources.

The uWSGI plugin allows you to write web applications in lua, but another purpose (if not the main one) is using Lua toextend the uWSGI server (and your application) using the signals framework, the rpc subsystem or the simple hooks engine.

If you have slow-area in your code (independently by the language used) consider rewriting them in Lua (before dealing with C)and use uWSGI to safely call them.

Your first WSAPI application

We will use the official WSAPI example, let’s call it pippo.lua:

  1. function hello(wsapi_env)
  2.   local headers = { ["Content-type"] = "text/html" }
  3.   local function hello_text()
  4.     coroutine.yield("<html><body>")
  5.     coroutine.yield("<p>Hello Wsapi!</p>")
  6.     coroutine.yield("<p>PATH_INFO: " .. wsapi_env.PATH_INFO .. "</p>")
  7.     coroutine.yield("<p>SCRIPT_NAME: " .. wsapi_env.SCRIPT_NAME .. "</p>")
  8.     coroutine.yield("</body></html>")
  9.   end
  10.   return 200, headers, coroutine.wrap(hello_text)
  11. end
  12.  
  13. return hello

Now run uWSGI with the lua option (remember to add —plugins lua as thefirst command line option if you are using it as a plugin)

  1. ./uwsgi --http :8080 --http-modifier1 6 --lua pippo.lua

This command line starts an http router that forward requests to a single worker in which pippo.lua is loaded.

As you can see the modifier 6 is enforced.

Obviously you can directly attach uWSGI to your frontline webserver (like nginx) and bind it to a uwsgi socket:

  1. ./uwsgi --socket 127.0.0.1:3031 --lua pippo.lua

(remember to set modifier1 to 6 in your webserver of choice)

Concurrency

Basically Lua is available in all of the supported uWSGI concurrency models

you can go multiprocess:

  1. ./uwsgi --socket 127.0.0.1:3031 --lua pippo.lua --processes 8 --master

or multithread:

  1. ./uwsgi --socket 127.0.0.1:3031 --lua pippo.lua --threads 8 --master

or both

  1. ./uwsgi --socket 127.0.0.1:3031 --lua pippo.lua --processes 4 --threads 8 --master

you can run it in coroutine mode (see below) using uGreen – uWSGI Green Threads as the suspend engine

  1. ./uwsgi --socket 127.0.0.1:3031 --lua pippo.lua --async 1000 --ugreen

Both threading and async modes will initialize a lua state each (you can see it as a whole independent lua VM)

Abusing coroutines

One of the most exciting feature of Lua are coroutines (cooperativemultithreading) support. uWSGI can benefit from this using its async engine. TheLua plugin will initialize a lua_State for every async core. We will use aCPU-bound version of our pippo.lua to test it:

  1. function hello(wsapi_env)
  2.   local headers = { ["Content-type"] = "text/html" }
  3.  
  4.   local function hello_text()
  5.     coroutine.yield("<html><body>")
  6.     coroutine.yield("<p>Hello Wsapi!</p>")
  7.     coroutine.yield("<p>PATH_INFO: " .. wsapi_env.PATH_INFO .. "</p>")
  8.     coroutine.yield("<p>SCRIPT_NAME: " .. wsapi_env.SCRIPT_NAME .. "</p>")
  9.     for i=0, 10000, 1 do
  10.         coroutine.yield(i .. "<br/>")
  11.     end
  12.     coroutine.yield("</body></html>")
  13.   end
  14.  
  15.   return 200, headers, coroutine.wrap(hello_text)
  16. end
  17.  
  18. return hello

and run uWSGI with 8 async cores…

  1. ./uwsgi --socket :3031 --lua pippo.lua --async 8

And just like that, you can manage 8 concurrent requests within a single worker!

Lua coroutines do not work over C stacks (meaning you cannot manage them with your C code), but thanks to uGreen – uWSGI Green Threads (the uWSGI official coroutine/greenthread engine)you can bypass this limit.

Thanks to uGreen you can use the uWSGI async API in your Lua apps and gain a very high level of concurrency.

  1. uwsgi.async_connect
  2. uwsgi.wait_fd_read
  3. uwsgi.wait_fd_write
  4. uwsgi.is_connected
  5. uwsgi.send
  6. uwsgi.recv
  7. uwsgi.close
  8. uwsgi.ready_fd

Threading example

The Lua plugin is “thread-safe” as uWSGI maps a lua_State to each internalpthread. For example you can run the Sputnik wiki engine very easily. UseLuaRocks to install Sputnik and versium-sqlite3. A database-backed storageis required as the default filesystem storage does not support being accessedby multiple interpreters concurrently. Create a wsapi compliant file:

  1. require('sputnik')
  2. return sputnik.wsapi_app.new{
  3.   VERSIUM_STORAGE_MODULE = "versium.sqlite3",
  4.   VERSIUM_PARAMS = {'/tmp/sputnik.db'},
  5.   SHOW_STACK_TRACE = true,
  6.   TOKEN_SALT = 'xxx',
  7.   BASE_URL       = '/',
  8. }

And run your threaded uWSGI server

  1. ./uwsgi --plugins lua --lua sputnik.ws --threads 20 --socket :3031

A note on memory

As we all know, uWSGI is parsimonious with memory. Memory is a preciousresource. Do not trust software that does not care for your memory! The Luagarbage collector is automatically called (by default) after each request.

You can tune the frequency of the GC call with the —lua-gc-freq <n> option, where nis the number of requests after the GC will be called:

  1. [uwsgi]
  2. plugins = lua
  3. socket = 127.0.0.1:3031
  4. processes = 4
  5. master = true
  6. lua = foobar.lua
  7. ; run the gc every 10 requests
  8. lua-gc-freq = 10

RPC and signals

The Lua shell

Using Lua as ‘configurator’

uWSGI api status