<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<Title>Phoronix Test Suite - Module Writing</Title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link href="includes/pts-documentation.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="pts_doc_header"><div class="pts_doc_fixed"><a href="http://www.phoronix-test-suite.com/"><div id="pts_doc_logo"></div></a></div></div>
<div class="pts_doc_fixed">
<div class="pts_doc_notice"><div style="float: left"><a href="index.html"><< Documentation Home</a></div><div style="float: right;">Module Writing</div></div>
<div class="pts_doc_main">
<!-- PTS AREA -->
<h1>Phoronix Test Suite Modules</h1>
<div style="width: 1px; height: 20px;"></div>
<p>Writing a module for the Phoronix Test Suite allows new functionality to be added
without having to extensively learn how pts-core functions. The module framework
for the Phoronix Test Suite allows modules to be written as a PHP object. Example PTS modules could include a module to shutdown the
screensaver when the Phoronix Test Suite starts up and re-enabling it when the
test is over, using sendmail to forward the results to an e-mail address when
testing is completed, or writing the current test status to a LCDproc-enabled
VFD display.</p>
<p>Modules are stored in <em>pts-core/modules/</em>. Loading a
module is done by either setting the <em>PTS_MODULES</em> environmental variable
with the name of the module (excluding the <em>.php</em> file
extension) or by associating a module with a separate environmental variable. The default list of modules to be loaded is stored in <em>~/.phoronix-test-suite/user-config.xml</em>.</p>
<p>Note: To run through all of the function calls for a module without needing to run a test,
run <em>phoronix-test-suite test-module MODULE_NAME</em>. Additionally, running
<em>phoronix-test-suite debug-module MODULE_NAME</em> will yield additional debugging details while
executing the same process.</p>
<h1>Module</h1>
<p>To see all of the functions supported for modules written in PHP, look at <em>pts-core/modules/dummy_module.php</em>
and additionally the other .php modules that ship with the Phoronix Test Suite.
Additionally, there are several functions written specifically for Phoronix Test
Suite modules that make it easier to save files, read files, and provided multi-threading
support for modules. The <em>pts_timed_function()</em> makes it possible (and
very easy) to thread functions within a module so that at a set interval the defined
functions will be called. For example, this support is used heavily within the
<em>system_monitor</em> module to poll sensors every X seconds even while there
are tests running. These functions can be found within <em>pts-core/objects/pts_module.php</em>.</p>
<p>Below is a sample module that times how long it takes to run the Phoronix Test
Suite. It would be saved as <em>pts-core/modules/time_me.php</em>.</p>
<blockquote><?php<br />
class time_me extends pts_module_interface<br />
{<br />
const module_name = "Time Me!";<br />
const module_version = "1.0.0";<br />
const module_description = "This is a module that times how long the Phoronix Test Suite runs.";<br />
const module_author = "Phoronix Media";<br />
<br />
static $start_time = NULL;<br />
static $end_time = NULL;<br />
<br />
public static function __startup()<br />
{<br />
self::$start_time = time();<br />
}<br />
public static function __shutdown()<br />
{<br />
self::$end_time = time();<br />
<br />
$time_elapsed = self::$end_time - self::$start_time;<br />
<br />
echo "\nThe Phoronix Test Suite Ran For " . $time_elapsed . " Seconds.\n";<br />
}<br />
}<br />
?></blockquote>
<p>Then by running <em>PTS_MODULES=time_me phoronix-test-suite benchmark video-extensions</em>,
at the end of the test it would print a string similar to: "The Phoronix
Test Suite Ran For 52 Seconds."</p>
<!-- END OF PTS AREA -->
</div></div><div class="pts_doc_fixed"><div class="pts_doc_bottom"><div style="float: left;"><a href="http://www.phoronix-test-suite.com/">Phoronix-Test-Suite.com</a></div><div style="float: right;">Copyright © 2008 by <a href="http://www.phoronix-media.com/">Phoronix Media</a>.</div></div></div>
</body>
</html>
