<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class Thread - Class Thread</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./modules.html"><span>Modules</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./enum.html"><span>Enumerations</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Class Thread<span class="faldoc_belong"><a href="./module_feathers_threading.html">[in Threading]</a></p></h1>
<p class="faldoc_brief">Parallel agent main class. </p>
<p class="faldoc_funcdecl">
<b>class</b> Thread \
<b>from</b> <a href="./class_Waitable.html">Waitable</a>
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#detach">detach()</a></td><td>Disengage this threads from waits and garbage. </td></tr>
<tr><td><a href="#detached">detached()</a></td><td>Returns true if the target thread is detached. </td></tr>
<tr><td><a href="#getError">getError()</a></td><td>Get the error that cause a thread to terminate, if any. </td></tr>
<tr><td><a href="#getName">getName()</a></td><td>Sets the symbolic name of this thread. </td></tr>
<tr><td><a href="#getReturn">getReturn()</a></td><td>Get the return value that was returned by the thread main function. </td></tr>
<tr><td><a href="#getSystemID">getSystemID()</a></td><td>Gets the system low level thread ID for this thread. </td></tr>
<tr><td><a href="#getThreadID">getThreadID()</a></td><td>Gets an unique numeric ID for this thread. </td></tr>
<tr><td><a href="#hadError">hadError()</a></td><td>Returns true if the target thread was terminated because of an uncaught raised item. </td></tr>
<tr><td><a href="#join">join()</a></td><td>Waits for a thread to terminate and returns its return value. </td></tr>
<tr><td><a href="#run">run()</a></td><td>Overloading hook that will hold the thread main function. </td></tr>
<tr><td><a href="#sameThread">sameThread()</a></td><td>Returns true if the givevn thread is running the same thread as this object. </td></tr>
<tr><td><a href="#setName">setName()</a></td><td>Sets the symbolic name of this thread. </td></tr>
<tr><td><a href="#start">start()</a></td><td>Launches the thread in a parallel environment. </td></tr>
<tr><td><a href="#stop">stop()</a></td><td>Interrupts the target thread. </td></tr>
<tr><td><a href="#terminated">terminated()</a></td><td>Returns true if the target thread is terminated. </td></tr>
<tr><td><a href="#toString">toString()</a></td><td>Returns a string representation of this thread. </td></tr>
<tr><td><a href="#vwait">vwait()</a></td><td>Wait for one or more synchronization strucures to become available. </td></tr>
<tr><td><a href="#wait">wait()</a></td><td>Wait for one or more synchronization strucures to become available. </td></tr>
</table>
<h3 class="faldoc_title">Inherited methods</h3>
<table class="faldoc_list">
<tr><td><a href="./class_Waitable.html#release">release</a> from Waitable </td><td>Releases a structure acquired by a waiting function. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> Thread \
<b>from</b> <a href="./class_Waitable.html">Waitable</a>
</p>
<table class="faldoc_function">
</table>
<br/>
<p class="item_brief">Parallel agent main class. </p>
<p class="faldoc_text">The Thread class controls the execution of parallel agents in the Falcon threading model. </p>
<p class="faldoc_text">The applicaiton willing to launch parallel agents should either derive the logical agent from the Thread class, or assign the run method of a Thread instance to a function of choice. </p>
<p class="faldoc_text">In example, both the following methods are valid: </p>
<pre class="faldoc_code">
class MyThread from Thread
function run()
> "Hello from the thread"
end
end
function parallel( param )
> "Parallel called from another thread with ", param
end
// launching a thread using OOP inheritance...
mt = MyThread()
mt.start()
// ... or using functional overload
th = Thread()
th.run = [parallel, "A parameter" ]
th.start()
</pre>
<p class="faldoc_text"> The static method <a href="./class_Threading.html#start">Threading.start</a> can be used to call an arbitrary function without encapsulating it in a Thread instance. The <a href="./class_Threading.html">Threading</a> class provides a set of static methods that can be used both by Thread instances and plain parallel code which has not been encapsulated in a instance of a class derived from Thread. </p>
<p class="faldoc_text"> The <a href="./class_Thread.html#start">Thread.start</a> method will create a new system thread and a new Virtual Machine, configured as the machine in which it was called, but completely empty. The instance that is going to be started will be copied (via serialization) to the new Virtual Machine, and if the operation can be completed, the new Virtual Machine will execute the <a href="./class_Thread.html#run">Thread.run</a> method of the transferred instance. </p>
<p class="faldoc_text">As the new copy of the VM is clean, global objects and results of former elaboration in the calling VM are not available to the newborn thread, unless they are passed as members of the derived class or as parameters of the run deferred call. </p>
<p class="faldoc_text"> This means that any synchronization structure needed for the thread must be set in the thread subclass instance (or in the parameters of the deferred call to <b>run</b>) before the thread is started. If provided with suitable structures that can transfer data to different threads, more data can be exchanged at a later time. </p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="detach">detach()</a></h3>
<p class="item_brief">Disengage this threads from waits and garbage. </p>
<p class="faldoc_funcdecl">Thread.detach( )</p>
<p class="faldoc_text"><p class="faldoc_text">This method sets the thread for which it has been called in "detached" status. This means that the thread will just run in background for the rest of the application life, or for how long it needs, and the main application doesn't want to be notified about the thread termination, nor to control its behavior anymore. </p>
<p class="faldoc_text">The net effect is that the thread is free to run as long as the application is alive. The VM running the thread is not bound anymore to the calling VM, and stopping and destroying the calling VM will have no effect on the thread. </p>
<p class="faldoc_text">Normally, when the thread object is garbage collected, or when the calling VM is destroyed and its garbage freed, the collector joins the system thread before destroying the Falcon thread instance. In other words, the destructor will wait for the target thread to terminate naturally. </p>
<p class="faldoc_text">By detaching the thread, the caller signals that it doesn't want to use this thread object anymore, and that the system thread associated with this instance is free to run beyond the lifetime of this Falcon item. </p>
<p class="faldoc_text"> As a side effect, it is not anymore possible to join this thread; threads eventually waiting for this thread to end will receive a JoinError, as threds trying to wait for its termination after that <b>detach</b> has been called. </p>
<p class="faldoc_text"> The detached state is not reversible. Once detached, a thread is left to its own destiny. However, it's still possible to communicate to it through synchronization structures and through methods in this instance, as i.e. <a href="./class_Thread.html#stop">Thread.stop</a>. </p>
</p>
<h3 class="faldoc_funcname"><a name="detached">detached()</a></h3>
<p class="item_brief">Returns true if the target thread is detached. </p>
<p class="faldoc_funcdecl">Thread.detached( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the thread has been detached, false otherwise. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="getError">getError()</a></h3>
<p class="item_brief">Get the error that cause a thread to terminate, if any. </p>
<p class="faldoc_funcdecl">Thread.getError( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">nil if the thread terminated correctly, the error that caused thread termination otherwise. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_JoinError.html">JoinError</a></td><td class="faldoc_raisedesc">if the thread is not terminated or detached. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method return the item that was raised by a thread and that wasn't caught at thread toplevel. If a thread terminated because of an unhandled error, and not because of a clean exit from the run method, this method will return the raised item, which is usually an item of class Error. </p>
</p>
<h3 class="faldoc_funcname"><a name="getName">getName()</a></h3>
<p class="item_brief">Sets the symbolic name of this thread. </p>
<p class="faldoc_funcdecl">Thread.getName( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A string containing the name of this thread (may be empty if not set). </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="getReturn">getReturn()</a></h3>
<p class="item_brief">Get the return value that was returned by the thread main function. </p>
<p class="faldoc_funcdecl">Thread.getReturn( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The value returned by the thread main fucntion. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_JoinError.html">JoinError</a></td><td class="faldoc_raisedesc">if the thread is not terminated or detached. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method return the item that was returned by the main thread function, wihch is the <a href="./class_Thread.html#run">Thread.run</a> method. If the thread terminated without returning any value, nil will be returned. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> The caller should ascertain that the thread wasn't terminated by an uncaught error with <a href="./class_Thread.html#hadError">Thread.hadError</a> before to call this method. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> The value retreived is actually a local copy of the value returned by the terminated thread. Changing it won't affect other threads willing to read the original value. Also, if the returned value is not serializable, this method will raise a CodeError. </p>
</p>
<h3 class="faldoc_funcname"><a name="getSystemID">getSystemID()</a></h3>
<p class="item_brief">Gets the system low level thread ID for this thread. </p>
<p class="faldoc_funcdecl">Thread.getSystemID( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A numeric thread ID. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">UThis is the system ID for the thread that is being run in the target Falcon object; for those systems that doesn't provide a numeric thread ID, this method returns a pointer to the system resources identifying the thread (as an integer value). It is always granted that two different living threads have different identifiers, but a thread ID may be re-assigned to newly started threads after previous one are dead. </p>
<p class="faldoc_text">If the thread isn't started, the method returns a meaningless number. </p>
</p>
<h3 class="faldoc_funcname"><a name="getThreadID">getThreadID()</a></h3>
<p class="item_brief">Gets an unique numeric ID for this thread. </p>
<p class="faldoc_funcdecl">Thread.getThreadID( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A numeric thread ID. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This is an unique counter assigned to each thread as they are created. </p>
</p>
<h3 class="faldoc_funcname"><a name="hadError">hadError()</a></h3>
<p class="item_brief">Returns true if the target thread was terminated because of an uncaught raised item. </p>
<p class="faldoc_funcdecl">Thread.hadError( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the thread was terminated because of an uncaught raise, false if it terminated correctly. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_JoinError.html">JoinError</a></td><td class="faldoc_raisedesc">if the thread is not terminated or detached. </td></tr>
</table>
</td></tr>
</table>
<h3 class="faldoc_funcname"><a name="join">join()</a></h3>
<p class="item_brief">Waits for a thread to terminate and returns its return value. </p>
<p class="faldoc_funcdecl">Thread.join( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The exit value of the target thread. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_JoinError.html">JoinError</a></td><td class="faldoc_raisedesc">if the thread is detached. </td></tr><tr><td class="faldoc_raiseitem"><a href="./class_ThreadError.html">ThreadError</a></td><td class="faldoc_raisedesc">if the thread didn't terminate correctly (i.e. raised an error). </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method is actually a shortcut for waiting the thread to become acquireable, and then checking for its termination value. Unless it can be proven that this is the only thread interested to the exit value of the thread to be joined, it is preferrable to use the <a href="./class_Thread.html#wait">Thread.wait</a> method, and then checking the return value of the target thread with <a href="./class_Thread.html#getReturn">Thread.getReturn</a>. </p>
<p class="faldoc_text"> If the thread cannot be acquired after termination because it has been detached, this method will raise a <a href="./class_JoinError.html">JoinError</a>. If the target thread exits with error (raises an item at toplevel) this method raises a <a href="./class_ThreadError.html">ThreadError</a>, and the item raised by the target thread is set as "next" error in the raised ThreadError. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This method doesn't use system level "join" call or equivalent. Falcon calls join(), or equivalent means to dispose of the system-level thread resources only at garbage collecting, or in case a thread instance is used to start another thread after termination. In other words, it is NOT necessary to call this <b>join</b> method on threads started through this API. </p>
</p>
<h3 class="faldoc_funcname"><a name="run">run()</a></h3>
<p class="item_brief">Overloading hook that will hold the thread main function. </p>
<p class="faldoc_funcdecl">Thread.run( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A value that will be available for inspection in other threads. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method is called by the new thread when the <a href="./class_Thread.html#start">Thread.start</a> method is called. The new thread executes the function in run(), and when the function returns, the thread is terminated. </p>
<p class="faldoc_text"> Other threads may wait for this thread to terminate through one of the <a href="./group_waiting_funcs.html">Waitings</a></p>
<p class="faldoc_text">The value returned by this method is made available to inspecting threads through serialization. </p>
</p>
<h3 class="faldoc_funcname"><a name="sameThread">sameThread()</a></h3>
<p class="item_brief">Returns true if the givevn thread is running the same thread as this object. </p>
<p class="faldoc_funcdecl">Thread.sameThread( otherThread )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">otherThread</td><td class="faldoc_paramdesc">Another thread to be checked against. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the system thread running in this Falcon objects are the same. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="setName">setName()</a></h3>
<p class="item_brief">Sets the symbolic name of this thread. </p>
<p class="faldoc_funcdecl">Thread.setName( name )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">name</td><td class="faldoc_paramdesc">The new name for this thread. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="start">start()</a></h3>
<p class="item_brief">Launches the thread in a parallel environment. </p>
<p class="faldoc_funcdecl">Thread.start( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_ThreadError.html">ThreadError</a></td><td class="faldoc_raisedesc">if the thread cannot be started. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method checks for this instance to have a runnable <a href="./class_Thread.html#run">Thread.run</a> method, and then for this object to be fully serializable. Once the instance is readied to be transferred to a parallel environment, the method crates a new Virtual Machine, linking all the modules that are linked to the VM where the start method is called. </p>
<p class="faldoc_text">Finally, the instance is transferred to the other VM, de-serialized there and readied for execution. When everything is ready, the new thread is finally started and the run method is executed in the parallel environment. </p>
<p class="faldoc_text">This method represents a single point of discontinuity in the calling application. On failure, an error is raised, reporting the details of the problem. Problems preventing parallel execution may be due to system resources (i.e. limited thread handles or memory limits) or to programming error (i.e. having one of the properties in this instance being a complex object that cannot be serialized). </p>
<p class="faldoc_text">On success, the method return and the other thread is started immediately, or as soon as the system is able to start it. </p>
<p class="faldoc_text">If this object is connected to an already running thread, trying to start it will raise a ThreadError. </p>
<p class="faldoc_text">It is possible to start again the thread after it has terminated and joined, provided this is not a detached thread. </p>
</p>
<h3 class="faldoc_funcname"><a name="stop">stop()</a></h3>
<p class="item_brief">Interrupts the target thread. </p>
<p class="faldoc_funcdecl">Thread.stop( )</p>
<p class="faldoc_text"><p class="faldoc_text">This method sends a kind request for wait interruption to the VM running the target thread. The VM interruption request will stop waiting calls and raise an InterruptedError in the target thread. The thread may either honor the request and terminate as soon as it can or discard the signalation and resume normal execution. </p>
</p>
<h3 class="faldoc_funcname"><a name="terminated">terminated()</a></h3>
<p class="item_brief">Returns true if the target thread is terminated. </p>
<p class="faldoc_funcdecl">Thread.terminated( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the thread is terminated, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The method will return true if the target thread is not running anymore, either because of a correct terminationor because of an error. </p>
</p>
<h3 class="faldoc_funcname"><a name="toString">toString()</a></h3>
<p class="item_brief">Returns a string representation of this thread. </p>
<p class="faldoc_funcdecl">Thread.toString( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A string containing anagraphic data for this thread. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="vwait">vwait()</a></h3>
<p class="item_brief">Wait for one or more synchronization strucures to become available. </p>
<p class="faldoc_funcdecl">Thread.vwait( structArray, [waitTime] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">structArray</td><td class="faldoc_paramdesc">Array of structures to wait for </td></tr>
<tr><td class="faldoc_optparam">waitTime</td><td class="faldoc_optparamdesc">Maximum timeout in seconds and fractions. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> nil if timeout expires, an ID in the <b>structArray</b> or the acquired structure. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><b><i>InterrutpedError</i></b></td><td class="faldoc_raisedesc">in case the thread receives a stop request. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method waits for one of the structures in the given <b>structArray</b> to become acquireable, and acquires it before returning. </p>
<p class="faldoc_text"> This works exactly as <a href="./class_Thread.html#wait">Thread.wait</a>, but, on success, the method returns the ID of the acquired item in <b>structArray</b> rather than the object itself. In this way, it is possible to rotate or change the list of items on which to wait for at each call. </p>
</p>
<h3 class="faldoc_funcname"><a name="wait">wait()</a></h3>
<p class="item_brief">Wait for one or more synchronization strucures to become available. </p>
<p class="faldoc_funcdecl">Thread.wait( ..., [waitTime] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">One or more synchronization structure to wait for. </td></tr>
<tr><td class="faldoc_optparam">waitTime</td><td class="faldoc_optparamdesc">Maximum timeout in seconds and fractions. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">nil if timeout expires, or the acquired item on success. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><b><i>InterrutpedError</i></b></td><td class="faldoc_raisedesc">in case the thread receives a stop request. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method waits for one of the structures in the given parameters to become acquireable, and acquires it before returning. </p>
<p class="faldoc_text">The acquired structure must be released manually after the thread has used the shared resource. </p>
<p class="faldoc_text">Typical usage pattern is that of acquiring the needed structures in the thread main loop, work with the achieved structure and release it. Also, it is useful to test for interruption and eventually honor the interruption request as soon as possibile: </p>
<pre class="faldoc_code">
class MyThread from Thread
...
function run()
loop
try
// wait at max 1 second.
res = self.wait( resA, resB, 1.0 )
catch InterruptedError
// honor the request
return
end
// what are we up to?
switch res
case nil
// timed out; perform some periodic operations
case resA
// do things with resA
resA.release()
case resB
// do things with resB
resB.release()
end
// do extra work with signaled data (*)
end
end
end
</pre>
<p class="faldoc_text">The method tries to acquire the resource in the same order they are passed as paramters. If the first resource is always available when the thread enters the wait, this will actually prevent the thread from acquiring other resources. As some resources can be acquired relatively often, it is necessary to be careful about this aspect. Repeated acquisition and release may cause starving of other threads and of other resources being in need of handling. </p>
<p class="faldoc_text"> It is advisable to release the resources as soon as possible and perform work on the shared data after they have been release, in the code section marked with (*). Also, if the structured waited on may become available at the same time, it is advisable to use <a href="./class_Thread.html#vwait">Thread.vwait</a> instead, to easily rotate the order in which the call tries to acquire the resources. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./modules.html">Modules</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./enum.html">Enumerations</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
