361 lines
12 KiB
HTML
361 lines
12 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
|
|
<head>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<title>OiL: The oil Module</title>
|
|
<style type="text/css" media="all"><!--
|
|
@import "../../oil.css";
|
|
@import "../../layout1.css";
|
|
;
|
|
--></style>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<div id="Header">An Object Request Broker in Lua </div>
|
|
<div id="Logo"><img alt="small (1K)" src="../../small.gif" height="49" width="80"></div>
|
|
|
|
<div id="Menu">
|
|
<div class="outside"><div class="inside"><ul>
|
|
<li><a href="../../index.html", title="">Home</a></li>
|
|
<li><a href="../../release/index.html", title="Installation">Install</a></li>
|
|
<li><a href="../index.html", title="User Manual">Manual</a>
|
|
<div class="outside"><div class="inside"><ul>
|
|
<li><a href="index.html", title="Basic Concepts">Basics</a>
|
|
<div class="outside"><div class="inside"><ul>
|
|
<li><strong>Module</strong></li>
|
|
<li><a href="brokers.html", title="Initializing Brokers">Brokers</a></li>
|
|
<li><a href="servants.html", title="Registering Servants">Servants</a></li>
|
|
<li><a href="proxies.html", title="Using Remote Servants">Proxies</a></li>
|
|
<li><a href="threads.html", title="Cooperative Multithreading">Threads</a></li>
|
|
</ul></div></div>
|
|
</li>
|
|
<li><a href="../corba/index.html", title="CORBA Support">CORBA</a></li>
|
|
<li><a href="../ludo.html", title="LuDO Support">LuDO</a></li>
|
|
<li><a href="../arch/index.html", title="Internal Architecture">Arch</a></li>
|
|
</ul></div></div>
|
|
</li>
|
|
<li><a href="../../about/papers.html", title="Conference Papers">Papers</a></li>
|
|
<li><a href="../../contact.html", title="Contact People">Contact</a></li>
|
|
<li><a href="http://luaforge.net/projects/oil/", title="Project at LuaForge">LuaForge</a></li>
|
|
</ul></div></div>
|
|
|
|
</div>
|
|
|
|
<div class="content">
|
|
<h1>The oil Module</h1>
|
|
<p>OiL is provided as a Lua module that can be required by the following command (for further information about Lua modules, see the <a href="http://www.lua.org/manual/5.1/manual.html#pdf-require">Lua's manual</a>):</p>
|
|
|
|
<pre> require "oil"</pre>
|
|
|
|
<p>The application must first load this module to use OiL.
|
|
It provides a set of helper functions that are used to <a href="brokers.html">create brokers</a>, <a href="threads.html">control multithreading</a> and other miscellaneous helper operations that provides features of the underlying operating system, as described below:</p>
|
|
|
|
<h3>Fields</h3>
|
|
<dl>
|
|
<dt><a href="#tasks"><b><code>oil.tasks</code></b></a></dt>
|
|
<dd>Internal coroutine scheduler used by OiL.</dd>
|
|
</dl>
|
|
|
|
<h3>Functions</h3>
|
|
<dl>
|
|
<dt><a href="#init"><b><code>oil.init</code></b></a><code>([config])</code></dt>
|
|
<dd>Initialize a broker.</dd>
|
|
<dt><a href="#main"><b><code>oil.main</code></b></a><code>(function)</code></dt>
|
|
<dd>Function executes the main function of the application.</dd>
|
|
<dt><a href="#newthread"><b><code>oil.newthread</code></b></a><code>(function, ...)</code></dt>
|
|
<dd>Creates and starts the execution of a new the thread.</dd>
|
|
<dt><a href="#pcall"><b><code>oil.pcall</code></b></a><code>(function, ...)</code></dt>
|
|
<dd>Function that must be used to perform protected calls in applications.</dd>
|
|
<dt><a href="#readfrom"><b><code>oil.readfrom</code></b></a><code>(filename)</code></dt>
|
|
<dd>Read the contents of a file.</dd>
|
|
<dt><a href="#sleep"><b><code>oil.sleep</code></b></a><code>(delay)</code></dt>
|
|
<dd>Suspends the execution of the current thread for some time.</dd>
|
|
<dt><a href="#time"><b><code>oil.time</code></b></a><code>()</code></dt>
|
|
<dd>Get the current system time.</dd>
|
|
<dt><a href="#writeto"><b><code>oil.writeto</code></b></a><code>(filename, text)</code></dt>
|
|
<dd>Writes a text into file.</dd>
|
|
</dl>
|
|
|
|
<h3>Definitions</h3>
|
|
|
|
<dt><a name="tasks"><b><code>oil.tasks</code></b></a></dt>
|
|
<dd>
|
|
<p>
|
|
<b>Internal coroutine scheduler used by OiL.</b>
|
|
This field holds a reference to the object that implement the API described in <a href="http://loop.luaforge.net/library/thread/Scheduler.html">loop.thread.Scheduler</a>.<br>
|
|
<p>
|
|
<i>Usage:</i>
|
|
<pre>
|
|
oil.tasks:register(coroutine.create(function() return broker:run() end))
|
|
oil.tasks:run()
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt><a name="main"><b><code>oil.main</code></b></a><code>(func)</code></dt>
|
|
<dd>
|
|
<p>
|
|
<b>Executes the main function of the application.</b>
|
|
The application's main function is executed in a new thread if the current assembly provides thread support.
|
|
This may only return when the application terminates.<br>
|
|
<p>
|
|
<i>Parameters:</i>
|
|
<table>
|
|
<tr>
|
|
<td valign="top"><code>func</code></td>
|
|
<td valign="top"><b>function</b></td>
|
|
<td valign="top"></td>
|
|
<td>Application's main function.</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
<i>Usage:</i>
|
|
<pre>
|
|
oil.main(function() oil.init():run() end)
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt><a name="newthread"><b><code>oil.newthread</code></b></a><code>(func, ...)</code></dt>
|
|
<dd>
|
|
<p>
|
|
<b>Creates and starts the execution of a new the thread.</b>
|
|
Creates a new thread to execute the function <code>func</code> with the extra parameters provided.
|
|
This function imediately starts the execution of the new thread and the original thread is only resumed again acordingly to the the scheduler's internal policy.
|
|
This function can only be invocated from others threads, including the one executing the application's main function (see <code>main</code>).<br>
|
|
<p>
|
|
<i>Parameters:</i>
|
|
<table>
|
|
<tr>
|
|
<td valign="top"><code>func</code></td>
|
|
<td valign="top"><b>function</b></td>
|
|
<td valign="top"></td>
|
|
<td>Function that the new thread will execute.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><code>...</code></td>
|
|
<td valign="top"><b>any</b></td>
|
|
<td valign="top"></td>
|
|
<td>Additional parameters passed to the <code>func</code> function.</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
<i>Usage:</i>
|
|
<pre>
|
|
oil.newthread(broker.run, broker) -- runs in another thread
|
|
</pre>
|
|
<p>
|
|
<i>See also:</i> <a href="#main"><b><code>oil.main</code></b></a>
|
|
</dd>
|
|
|
|
<dt><a name="sleep"><b><code>oil.sleep</code></b></a><code>(time)</code></dt>
|
|
<dd>
|
|
<p>
|
|
<b>Suspends the execution of the current thread for some time.</b>
|
|
<p>
|
|
<i>Parameters:</i>
|
|
<table>
|
|
<tr>
|
|
<td valign="top"><code>time</code></td>
|
|
<td valign="top"><b>number</b></td>
|
|
<td valign="top"></td>
|
|
<td>Delay in seconds that the execution must be resumed.</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
<i>Usage:</i>
|
|
<pre>
|
|
oil.sleep(5.5)
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt><a name="time"><b><code>oil.time</code></b></a><code>()</code></dt>
|
|
<dd>
|
|
<p>
|
|
<b>Get the current system time.</b>
|
|
<p>
|
|
<i>Return values:</i>
|
|
<table>
|
|
<tr>
|
|
<td valign="top"><code>timestamp</code></td>
|
|
<td valign="top"><b>number</b></td>
|
|
<td valign="top"></td>
|
|
<td>Number of seconds since a fixed point in the past.</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
<i>Usage:</i>
|
|
<pre>
|
|
local start = oil.time(); oil.sleep(3); print("I slept for", oil.time() - start)
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt><a name="pcall"><b><code>oil.pcall</code></b></a><code>(func, ...)</code></dt>
|
|
<dd>
|
|
<p>
|
|
<b>Function that must be used to perform protected calls in applications.</b>
|
|
It is a "coroutine-safe" version of the <code>pcall</code> function of the Lua standard library.<br>
|
|
<p>
|
|
<i>Parameters:</i>
|
|
<table>
|
|
<tr>
|
|
<td valign="top"><code>func</code></td>
|
|
<td valign="top"><b>function</b></td>
|
|
<td valign="top"></td>
|
|
<td>Function to be executed in protected mode.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><code>...</code></td>
|
|
<td valign="top"><b>any</b></td>
|
|
<td valign="top"></td>
|
|
<td>Additional parameters passed to protected function.</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
<i>Return values:</i>
|
|
<table>
|
|
<tr>
|
|
<td valign="top"><code>success</code></td>
|
|
<td valign="top"><b>boolean</b></td>
|
|
<td valign="top"></td>
|
|
<td><code>true</code> if function execution did not raised any errors or <code>false</code> otherwise.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><code>...</code></td>
|
|
<td valign="top"><b>any</b></td>
|
|
<td valign="top"></td>
|
|
<td>Values returned by the function or an the error raised by the function.</td>
|
|
</tr>
|
|
</table>
|
|
</dd>
|
|
|
|
<dt><a name="writeto"><b><code>oil.writeto</code></b></a><code>(filepath, text)</code></dt>
|
|
<dd>
|
|
<p>
|
|
<b>Writes a text into file.</b>
|
|
Utility function for writing stringfied IORs into a file.<br>
|
|
<p>
|
|
<i>Parameters:</i>
|
|
<table>
|
|
<tr>
|
|
<td valign="top"><code>filepath</code></td>
|
|
<td valign="top"><b>string</b></td>
|
|
<td valign="top"></td>
|
|
<td>Path of the file that should be create with the text provided.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><code>text</code></td>
|
|
<td valign="top"><b>string</b></td>
|
|
<td valign="top"></td>
|
|
<td>Text that shall be written into the file.</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
<i>Return values:</i>
|
|
<table>
|
|
<tr>
|
|
<td valign="top"><code>success</code></td>
|
|
<td valign="top"><b>file handler</b></td>
|
|
<td valign="top"></td>
|
|
<td>If the file was properly created with the provided content then the closed file handler is returned or <code>nil</code> is returned if some error was found.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><code>error</code></td>
|
|
<td valign="top"><b>string</b></td>
|
|
<td valign="top">[occasional]</td>
|
|
<td>Error message returned by function 'io.open' of Lua IO library if the file could not be opened for write.</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
<i>Usage:</i>
|
|
<pre>
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt><a name="readfrom"><b><code>oil.readfrom</code></b></a><code>(filepath)</code></dt>
|
|
<dd>
|
|
<p>
|
|
<b>Read the contents of a file.</b>
|
|
Utility function for reading stringfied IORs from a file.<br>
|
|
<p>
|
|
<i>Parameters:</i>
|
|
<table>
|
|
<tr>
|
|
<td valign="top"><code>success</code></td>
|
|
<td valign="top"><b>file handler</b></td>
|
|
<td valign="top"></td>
|
|
<td>Path of the file to be read.</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
<i>Return values:</i>
|
|
<table>
|
|
<tr>
|
|
<td valign="top"><code>contents</code></td>
|
|
<td valign="top"><b>string</b></td>
|
|
<td valign="top"></td>
|
|
<td>Contents of the file read or <code>nil</code> if some error was found.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><code>error</code></td>
|
|
<td valign="top"><b>string</b></td>
|
|
<td valign="top">[occasional]</td>
|
|
<td>Error message returned by function 'io.open' of Lua IO library if the file could not be opened for read.</td>
|
|
</tr>
|
|
</table>
|
|
</dd>
|
|
|
|
<dt><a name="init"><b><code>oil.init</code></b></a><code>([config])</code></dt>
|
|
<dd>
|
|
<p>
|
|
<b>Initialize a broker.</b>
|
|
Initialize an ORB instance with the provided configurations.
|
|
The actual configuration options varies accordingly to the <a href="../arch/flavors.html">ORB flavor</a>.
|
|
For more information about broker initialization, see section <a href="brokers.html">Initializing Brokers</a>.
|
|
If the parameter <code>config</code> is not provide, the same ORB is returned, which is initialized with default configurations.
|
|
To create other ORBs with the default configurations, use an empty table as parameter <code>config</code>.<br>
|
|
<p>
|
|
<i>Parameters</i>
|
|
<table>
|
|
<tr>
|
|
<td valign="top"><code>config</code></td>
|
|
<td valign="top"><b>table</b></td>
|
|
<td valign="top">[optional]</td>
|
|
<td>Configuration used to initialize the ORB.</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
<i>Return values</i>
|
|
<table>
|
|
<tr>
|
|
<td valign="top"><code>broker</code></td>
|
|
<td valign="top"><b>table</b></td>
|
|
<td valign="top"></td>
|
|
<td>ORB instance properly initialized.</td>
|
|
</tr>
|
|
</table>
|
|
<p>
|
|
<i>Usage:</i>
|
|
<pre>
|
|
oil.init{ host = "middleware.inf.puc-rio.br" }
|
|
oil.init{ host = "10.223.10.56", port = 8080 }
|
|
print("ORB post:", oil.init().port)
|
|
</pre>
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
</div>
|
|
|
|
<div class="content">
|
|
<p><small><strong>Copyright (C) 2004-2008 Tecgraf, PUC-Rio</strong></small></p>
|
|
<small>This project is currently being maintained by <a href="http://www.tecgraf.puc-rio.br">Tecgraf</a> at <a href="http://www.puc-rio.br">PUC-Rio</a> with grants from <a href="http://www.capes.gov.br">CAPES</a> and <a href="http://www.cnpq.br">CNPq</a>.</small>
|
|
</div>
|
|
|
|
|
|
|
|
</body>
|
|
|
|
</html>
|