The oil Module
OiL is provided as a Lua module that can be required by the following command (for further information about Lua modules, see the Lua's manual):
require "oil"
The application must first load this module to use OiL. It provides a set of helper functions that are used to create brokers, control multithreading and other miscellaneous helper operations that provides features of the underlying operating system, as described below:
Fields
oil.tasks- Internal coroutine scheduler used by OiL.
Functions
oil.init([config])- Initialize a broker.
oil.main(function)- Function executes the main function of the application.
oil.newthread(function, ...)- Creates and starts the execution of a new the thread.
oil.pcall(function, ...)- Function that must be used to perform protected calls in applications.
oil.readfrom(filename)- Read the contents of a file.
oil.sleep(delay)- Suspends the execution of the current thread for some time.
oil.time()- Get the current system time.
oil.writeto(filename, text)- Writes a text into file.
Definitions
oil.tasks
Internal coroutine scheduler used by OiL.
This scheduler implements the API described in loop.thread.Scheduler.
Usage:
oil.tasks:register(coroutine.create(function() return broker:run() end))
oil.tasks:run()
oil.main(func)
Executes the main function of the application.
The application's main function is executed in a new thread if the current assembly provides thread support.
This function only returns when the application terminates.
Parameters:
func |
function | Application's main function. |
Usage:
oil.main(function() oil.init():run() end)
oil.newthread(func, ...)
Creates and starts the execution of a new the thread.
Creates a new thread to execute the function func with the extra parameters provided.
This function immediately starts the execution of the new thread.
The original thread will be resumed again accordingly to the the scheduler's internal policy.
This function can only be invoked from others threads, including the one executing the application's main function (see main).
Parameters:
func |
function | Function that the new thread will execute. | |
... |
any | Additional parameters passed to the func function. |
Usage:
oil.newthread(broker.run, broker) -- runs in another thread
See also: oil.main
oil.sleep(time)
Suspends the execution of the current thread for at least time seconds.
Parameters:
time |
number | Time in seconds that the current thread must be suspended. |
Usage:
oil.sleep(5.5)
oil.time()Get the current time of the system.
Return values:
timestamp |
number | Number of seconds since a fixed point in the past. |
Usage:
local start = oil.time(); oil.sleep(3); print("I slept for", oil.time() - start)
oil.pcall(func, ...)
A "coroutine-safe" version of the pcall function of the Lua standard library.
Parameters:
func |
function | Function to be executed in protected mode. | |
... |
any | Additional parameters passed to protected function. |
Return values:
success |
boolean | true if function execution did not raised any errors or false otherwise. |
|
... |
any | Values returned by the function or an the error raised by the function. |
oil.writeto(filepath, text)
Writes a text into file.
Utility function for writing stringfied IORs into a file.
Parameters:
filepath |
string | Path of the file that should be create with the text provided. | |
text |
string | Text that shall be written into the file. |
Return values:
success |
file handler | If the file was properly created with the provided content then the closed file handler is returned or nil is returned if some error was found. |
|
error |
string | [occasional] | Error message returned by function 'io.open' of Lua IO library if the file could not be opened for write. |
Usage:
oil.readfrom(filepath)
Read the contents of a file.
Utility function for reading stringfied IORs from a file.
Parameters:
success |
file handler | Path of the file to be read. |
Return values:
contents |
string | Contents of the file read or nil if some error was found. |
|
error |
string | [occasional] | Error message returned by function 'io.open' of Lua IO library if the file could not be opened for read. |
oil.init([config])
Initialize a broker.
Initialize an ORB instance with the provided configuration.
The actual configuration options varies accordingly to the ORB flavor.
For more information about broker initialization, see section Initializing Brokers.
If the parameter config is not provided, the same ORB is returned, which is initialized with a default configuration.
To create other ORBs with the default configuration, use an empty table as parameter config.
Parameters
config |
table | [optional] | Configuration used to initialize the ORB. |
Return values
broker |
table | ORB instance properly initialized. |
Usage:
oil.init{ host = "middleware.inf.puc-rio.br" }
oil.init{ host = "10.223.10.56", port = 8080 }
print("ORB port:", oil.init().port)