How to use native libraries in Splay

This tutorial guides through the usage of the support for native libraries in SPLAY. By default the support for native libraries is disabled for security reasons. These features are available as of version 1.3 of the controller, 1.2 of the splayd and 1.4 of the command line tools. You can download the required packages from the download page.

N.B For security reasons, this feature will not be available through our public SPLAY demo.

Once your controller is properly installed, you need to enable the support for native libraries. To proceed, you first need to make sure that your controller and all the splayds are not running.

A. Splayd

To make sure your splayd is ready to accept jobs that require a native library, you need to ensure that the following line in the settings.lua file is uncommented:

splayd.settings.protocol = "grid"

B. Controller

To enable your SPLAY users to submit their libraries and to submit jobs requiring them, uncomment the following line in the file lib/config.rb:
AllowNativeLibs = true

C. Submitting a native library to the controller

Currently, every user can submit a library to the controller. To do that, a single call to a script is sufficient:

./splay-submit-lib.lua -l hello.so -lv 1.0 -a i386 -o Linux
The scripts requires four mandatory parameters: -l for the name of the library, -lv as the version number, -a as the architecture and -o as the OS the library has been compiled for. If everything works, the following output corresponds to a successful insertion executed with the previous command:
LIB_NAME= hello.so	OS= Linux	ARCH= x86_64	version= 1.0	SHA1= 632861aa6e8d1337e5f4126139396c1f43e8cf7e
NEW NATIVE LIBRARY INSTALLED

Note: There is no validation that takes place with regard to the information provided by the user. It is her responsibility to ensure its validity.

D. Submitting a jobs with a native library

Once a library is available on the controller, we are ready to use it with a job (provided that there are splayds that match its platform).

./splay-submit-job.lua -l hello.so -lv 1.0 sample.lua

As shown in the example, both -l and -lv need to be specified. If there are enough splayds, the job will be deployed.

E. Updating a lib

Sometimes it is required to update a library (to correct bugs or for improvements) after its successful deployment. It is possible to use same script as in A) to do that. We have the following policy: we allow only one version of a lib per platform (architecture + os). It implies that if a library A is available for platforms X an Y at version 1.0, updating A to vresion 2.0 for platform X will leave the one available for platform Y at 1.0. Also note that the library version numbers are a matter of convention: therefore, the system won't check for increasing versions (infact, It is perfectly possible to replace a library from version 2.0 to version 1.1).

./splay-submit-lib.lua -l hello.so -lv 2.0 -a i386 -o Linux

The following output shows the message a user receives when successfully updating a library.

LIB_NAME= hello.so	OS= Linux	ARCH= x86_64	version= 2.0	SHA1= 3de50b680d5e2d5b8ad3903c6ddc89ffe25d015d
EXISTING NATIVE LIBRARY UPDATED

F. Other administration tasks

For administrative purposes we provide two more scripts to list the available libraries and remove the deprecated ones.

Listing libraries is done with splay-list-libs.lua. It supports only one option -l LIB_NAME to filter the libraries you want to list to a given name.

./splay-list-libs.lua -l hello.so
That will give the following output provided that we only have the libraries uploaded in the previous examples.

N.B for the sake of this example, we added a second library by repeating the submission process at A.

SESSION_ID     = 13586bc3a682749aa623f81b3f82f338b78901c9
CLI SERVER URL = http://127.0.0.1:2222/splay-ctrl-api
LIB NAME = 

Sending command to http://127.0.0.1:2222/splay-ctrl-api...

Libs list : number of items 2
Lib name =hello.so Version=1.0 Arch=x86_64 OS=Linux SHA1=632861aa6e8d1337e5f4126139396c1f43e8cf7e
Lib name =hello.so Version=1.0 Arch=i386 OS=Linux SHA1=7cda17cbb957de2219f98e64ad5194187c3b8beb

Removing libraries is also important in order to clean the controller without having an access to the controller database.

Its only mandatory parameter is the name of the library to remove, specified by the -l parameter. It supports several (but optional) parameters: -lv will remove all instances of a given version, -o will remove all instances for a given operating system and -a will remove all instances for the given architecture. All the optional parameters can be combined to narrow down the number of libraries to remove.
./splay-remove-lib.lua -l hello.so
As a result we obtain this output:
SESSION_ID     = e85eb3ae5d82db0289db3137687f99bf5f06959f
CLI SERVER URL = http://127.0.0.1:2222/splay-ctrl-api
LIB NAME = hello.so

Sending command to http://127.0.0.1:2222/splay-ctrl-api...

Controller :
Lib deleted
And by listing again all the libraries, we can see that the controller is empty.
./splay-list-libs.lua -l hello.so
SESSION_ID     = e85eb3ae5d82db0289db3137687f99bf5f06959f
CLI SERVER URL = http://127.0.0.1:2222/splay-ctrl-api
LIB NAME = hello.so

Sending command to http://127.0.0.1:2222/splay-ctrl-api...

Libs list : number of items 0