This tutorial will introduce you to uWSGI hacking. A bit of C knowledge and UNIX theory is required.
The simplified (and safe) build system used in the tutorial has been added in uWSGI 1.9.21, on older versions you need the raw procedure (described at the end of the tutorial)
a uWSGI plugins is a standard shared library (with the classic .so extension) exposing a specific C structure named “uwsgi_plugin”.
This structure exposes a bunch of handy informations (like the name of the plugin) and “hooks”.
Hooks are simple functions registered to be run at specific server phases
The minimal plugin you can write it is something like that (the ‘foobar’ plugin)
#include <uwsgi.h>
struct uwsgi_plugin foobar_plugin = {
.name ="foobar",
};
it announces itself as ‘foobar’ and exposes no hooks (yes, it is the most useless plugin out there).
Plugins are not required to define hooks, they can simply expose functions that can be called using uWSGI advanced facilities (read: Hooks)
Albeit uWSGI is able to directly load shared libraries (with –dlopen) and call their functions as hooks, sometimes you want to interface with uWSGI internal structures.
Our first plugin will be a simple hello world one:
#include <uwsgi.h>
static int foo_init() {
uwsgi_log("Hello World\n");
return 0;
}
struct uwsgi_plugin foobar_plugin = {
.name = "foobar",
.init = foo_init,
};
save it as foobar.c
build it:
uwsgi --build-plugin foobar.c
you will end with a foobar_plugin.so you can load in your uwsgi binary:
uwsgi --plugin ./foobar_plugin.so
if all goes well, you should see “Hello World” on your terminal before uWSGI exiting with an error (as no socket is defined)
As you have seen, the uwsgi binary by itself is able to build plugins without forcing the user/developer to care about build profiles, #ifdef or platform-specific configurations.
This is possibile because the uwsgi binary contains the raw ‘uwsgi.h’ file as well as the ‘uwsgiconfig.py’ script.
In addition to this the CFLAGS used when buildign the binary are stored too.
With this 3 components you have all you need to safely build a uWSGI plugin tuned for your uwsgi binary.
Whenever you make I/O operations on socket you have to be sure to not-block the currently running thread/core/worker.
The uwsgi api exposes the following functions to ensure safety when dealing with I/O