script-api.rst

lua

Script API

This document describes the API available for use from within the Lua script that can be passed on the command line using the --script option. Such script will be executed by the main thread that controls the client/server network threads.

Typical script can be split into 4 parts:

1. initialize shared variables
2. register hook functions
3. trigger the test run
4. process collected data

Hooks

Hooks are user-provided functions that allow you to "hook up" into well-defined points of the client/server thread logic and execute a custom script.

There are currently two types of hooks: socket-hooks and packet-hooks.

Socket Hooks

Socket hooks are tied to socket events. Hooks are called once per each socket that gets opened or closed by the client/server threads.

They are intended for configuring the socket (e.g. with setsockopt(2)) or collecting the information about the socket (e.g. with getsockopt(2)).

Note

In TCP workloads (tcp_stream or tcp_rr), server-side socket hooks operate on the listening socket, not the connection socket. This might change in the future.

Registers a hook function to be invoked after the client/server thread opens a connection/listening socket with a socket(2) call.

param socket_hook

Hook function invoked after socket(2) call.

type socket_hook

socket_hook_fn

Registers a hook function to be invoked before the client/server thread closes a connection/listening socket with a close(2) call.

param socket_hook

Hook function invoked before close(2) call.

type socket_hook

socket_hook_fn

Packet Hooks

Packet hooks are tied to the socket message queue and socket error queue events. They can be used to implement a custom way to read from or write to a socket within the client/server thread's main loop.

For TCP workloads (tcp_stream and tcp_rr), packet hooks always operate on connection sockets.

Registers a hook function to be invoked when a socket is ready for writting. i.e. on EPOLLOUT epoll(7) event.

param packet_hook

Hook function to write data to the socket.

type packet_hook

packet_hook_fn

Registers a hook function to be invoked when a socket is ready for reading, i.e on EPOLLIN epoll(7) event.

param packet_hook

Hook function to read data from the socket.

type packet_hook

packet_hook_fn

Registers a hook function to be invoked when socket's error queue is ready for reading, i.e. on EPOLLERR epoll(7) event.

param packet_hook

Hook function to read data from the socket error queue.

type packet_hook

packet_hook_fn

Run Control

Data Passing

Add link to an example.

Syscall Wrappers

Lua syscall wrappers are provided by the ljsyscall library. We provide convenience aliases for symbols exported by ljsyscall so that the symbol names are more C-like. That is:

S = require("syscall")
-- Aliases for syscalls
recvmsg = S.recvmsg
-- Aliases for constants
AF_INET = S.c.AF.INET becomes
-- Aliases for data types
sockaddr_in = S.types.t.sockaddr_in

Warning

Only a small set of symbols have aliases at the moment (see script_prelude.lua). This will be resolved in the near future. In the meantime please access any symbol that is missing an alias via the S global variable.