LuaSandbox Class Reference

The LuaSandbox class creates a Lua environment and allows for execution of Lua code. More...

Public Member Functions
	loadString ( $code, $chunkName='')
	Load Lua code into the Lua environment.
	loadBinary ( $binary, $chunkName='')
	Load a precompiled binary chunk into the Lua environment.
	setMemoryLimit ( $limit)
	Set the memory limit for the Lua environment.
	getMemoryUsage ()
	Fetch the current memory usage of the Lua environment.
	getPeakMemoryUsage ()
	Fetch the peak memory usage of the Lua environment.
	setCPULimit ( $limit)
	Set the CPU time limit for the Lua environment.
	getCPUUsage ()
	Fetch the current CPU time usage of the Lua environment.
	pauseUsageTimer ()
	Pause the CPU usage timer.
	unpauseUsageTimer ()
	Unpause the timer paused by LuaSandbox::pauseUsageTimer()
	enableProfiler ( $period=0.002)
	Enable the profiler.
	disableProfiler ()
	Disable the profiler.
	getProfilerFunctionReport ( $units=LuaSandbox::SECONDS)
	Fetch profiler data.
	callFunction ( $name)
	Call a function in a Lua global variable.
	wrapPhpFunction (callable $function)
	Wrap a PHP callable in a LuaSandboxFunction, so it can be passed into Lua as an anonymous function.
	registerLibrary ( $libName, array $functions)
	Register a set of PHP functions as a Lua library, so that Lua can call the relevant PHP code.

Static Public Member Functions
static	getVersionInfo ()
	Return the versions of LuaSandbox and Lua.

Public Attributes
const	SAMPLES = 0
const	SECONDS = 1
const	PERCENT = 2

Detailed Description

The LuaSandbox class creates a Lua environment and allows for execution of Lua code.

Member Function Documentation

callFunction()

LuaSandbox::callFunction

(

$name

)

Call a function in a Lua global variable.

If the name contains "." characters, the function is located via recursive table accesses, as if the name were a Lua expression.

If the variable does not exist, or is not a function, false will be returned and a warning issued.

For more information about calling Lua functions and the return values, see LuaSandboxFunction::call().

Parameters

string	$name	Variable name
mixed	$args,...	Arguments to the function

Returns

array|bool Return values from the function

enableProfiler()

LuaSandbox::enableProfiler

(

$period = 0.002

)

Enable the profiler.

Profiling will begin when Lua code is entered.

The profiler periodically samples the Lua environment to record the running function. Testing indicates that at least on Linux, setting a period less than 1ms will lead to a high overrun count but no performance problems.

Parameters

float

$period

Sampling period in seconds

Returns

bool Whether the profiler is enabled.

getCPUUsage()

LuaSandbox::getCPUUsage

(

)

Fetch the current CPU time usage of the Lua environment.

This includes time spent in PHP callbacks.

Returns

float Current CPU time usage in seconds.

getMemoryUsage()

LuaSandbox::getMemoryUsage

(

)

Fetch the current memory usage of the Lua environment.

Returns

int Current memory usage in bytes.

getPeakMemoryUsage()

LuaSandbox::getPeakMemoryUsage

(

)

Fetch the peak memory usage of the Lua environment.

Returns

int Peak memory usage in bytes.

getProfilerFunctionReport()

LuaSandbox::getProfilerFunctionReport

(

$units = LuaSandbox::SECONDS

)

Fetch profiler data.

For a profiling instance previously started by enableProfiler(), get a report of the cost of each function. The return value will be an associative array mapping the function name (with source file and line defined in angle brackets) to the cost.

The measurement unit used for the cost is determined by the $units parameter:

• LuaSandbox::SAMPLES: Measure in number of samples
• LuaSandbox::SECONDS: Measure in seconds of CPU time
• LuaSandbox::PERCENT: Measure percentage of CPU time

Parameters

int

$units

Measurement unit constant.

Returns

array Profiler measurements, sorted in descending order.

getVersionInfo()

static LuaSandbox::getVersionInfo ( )

static

Return the versions of LuaSandbox and Lua.

Returns

array With two keys

• LuaSandbox: (string) LuaSandbox version
• Lua: (string) Lua version

loadBinary()

LuaSandbox::loadBinary	(		$binary,
			$chunkName = ''
	)

Load a precompiled binary chunk into the Lua environment.

Loads data generated by LuaSandboxFunction::dump().

Parameters

string	$binary	Data from LuaSandboxFunction::dump()
string	$chunkName	Name for the loaded function.

Returns

LuaSandboxFunction

loadString()

LuaSandbox::loadString	(		$code,
			$chunkName = ''
	)

Load Lua code into the Lua environment.

This is the equivalent of standard Lua's loadstring() function.

Parameters

string	$code	Lua code
string	$chunkName	Name for the loaded chunk, for use in error traces

Returns

LuaSandboxFunction The compiled chunk

pauseUsageTimer()

LuaSandbox::pauseUsageTimer

(

)

Pause the CPU usage timer.

This only has effect when called from within a callback from Lua. When execution returns to Lua, the timer will be automatically unpaused. If a new call into Lua is made, the timer will be unpaused for the duration of that call.

If a PHP callback calls into Lua again with timer not paused, and then that Lua function calls into PHP again, the second PHP call will not be able to pause the timer. The logic is that even though the second PHP call would avoid counting the CPU usage against the limit, the first call still counts it.

Returns

bool true if the timer is now paused, false if not.

registerLibrary()

LuaSandbox::registerLibrary	(		$libName,
		array	$functions
	)

Register a set of PHP functions as a Lua library, so that Lua can call the relevant PHP code.

The first parameter is the name of the library. In the Lua state, the global variable of this name will be set to the table of functions. If the table already exists, the new functions will be added to it.

The second parameter is an array, where each key is a function name, and each value is a corresponding PHP callable.

For more information about calling Lua functions and the return values, see LuaSandboxFunction::call() and LuaSandbox::wrapPhpFunction().

Parameters

string	$libName	Library name
array	$functions	As above

setCPULimit()

LuaSandbox::setCPULimit

(

$limit

)

Set the CPU time limit for the Lua environment.

If the total user and system time used by the environment after the call to this method exceeds this limit, a LuaSandboxTimeoutError exception is thrown.

Time used in PHP callbacks is included in the limit.

Setting the time limit from a callback while Lua is running causes the timer to be reset, or started if it was not already running.

Parameters

float | false

$limit

Limit in seconds, or false for no limit

setMemoryLimit()

LuaSandbox::setMemoryLimit

(

$limit

)

Set the memory limit for the Lua environment.

If this limit is exceeded, a LuaSandboxMemoryError exception is thrown.

Parameters

int

$limit

Memory limit in bytes

wrapPhpFunction()

LuaSandbox::wrapPhpFunction

(

callable

$function

)

Wrap a PHP callable in a LuaSandboxFunction, so it can be passed into Lua as an anonymous function.

The function must return either an array of values (which may be empty), or null which is equivalent to returning the empty array.

Exceptions will be raised as errors in Lua, however only LuaSandboxRuntimeError exceptions may be caught inside Lua with pcall() or xpcall().

For more information about calling Lua functions and the return values, see LuaSandboxFunction::call().

Parameters

callable

$function

Returns

LuaSandboxFunction

---

The documentation for this class was generated from the following file:

• stubs/LuaSandbox.php