1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>FreeMat: THREADSTART Start a New Thread Computation</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">FreeMat
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
</ul>
</div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('thread_threadstart.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">THREADSTART Start a New Thread Computation </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Section: <a class="el" href="sec_thread.html">FreeMat Threads</a> </p>
<h1><a class="anchor" id="Usage"></a>
Usage</h1>
<p>The <code>threadstart</code> function starts a new computation on a FreeMat thread, and you must provide a function (no scripts are allowed) to run inside the thread, pass any parameters that the thread function requires, as well as the number of output arguments expected. The general syntax for the <code>threadstart</code> function is </p>
<pre class="fragment"> threadstart(threadid,function,nargout,arg1,arg2,...)
</pre><p> where <code>threadid</code> is a thread handle (returned by <code>threadnew</code>), where <code>function</code> is a valid function name (it can be a built-in imported or M-function), <code>nargout</code> is the number of output arguments expected from the function, and <code>arg1</code> is the first argument that is passed to the function. Because the function runs in its own thread, the return values of the function are not available imediately. Instead, execution of that function will continue in parallel with the current thread. To retrieve the output of the thread function, you must wait for the thread to complete using the <code>threadwait</code> function, and then call <code>threadvalue</code> to retrieve the result. You can also stop the running thread prematurely by using the <code>threadkill</code> function. It is important to call <code>threadfree</code> on the handle you get from <code>threadnew</code> when you are finished with the thread to ensure that the resoures are properly freed.</p>
<p>It is also perfectly reasonable to use a single thread multiple times, calling <code>threadstart</code> and <code>threadreturn</code> multiple times on a single thread. The context is preserved between threads. When calling <code>threadstart</code> on a pre-existing thread, FreeMat will attempt to wait on the thread. If the wait fails, then an error will occur.</p>
<p>Some additional important information. Thread functions operate in their own context or workspace, which means that data cannot be shared between threads. The exception is <code>global</code> variables, which provide a thread-safe way for multiple threads to share data. Accesses to global variables are serialized so that they can be used to share data. Threads and FreeMat are a new feature, so there is room for improvement in the API and behavior. The best way to improve threads is to experiment with them, and send feedback.</p>
<h1><a class="anchor" id="Example"></a>
Example</h1>
<p>Here we do something very simple. We want to obtain a listing of all files on the system, but do not want the results to stop our computation. So we run the <code>system</code> call in a thread.</p>
<pre class="fragment">--> a = threadnew; % Create the thread
--> threadstart(a,'system',1,'ls -lrt /'); % Start the thread
--> b = rand(100)\rand(100,1); % Solve some equations simultaneously
--> c = threadvalue(a); % Retrieve the file list
--> size(c) % It is large!
ans =
1 28
--> threadfree(a);
</pre><p>The possibilities for threads are significant. For example, we can solve equations in parallel, or take Fast Fourier Transforms on multiple threads. On multi-processor machines or multicore CPUs, these threaded calculations will execute in parallel. Neat.</p>
<p>The reason for the <code>nargout</code> argument is best illustrated with an example. Suppose we want to compute the Singular Value Decomposition <code>svd</code> of a matrix <code>A</code> in a thread. The documentation for the <code>svd</code> function tells us that the behavior depends on the number of output arguments we request. For example, if we want a full decomposition, including the left and right singular vectors, and a diagonal singular matrix, we need to use the three-output syntax, instead of the single output syntax (which returns only the singular values in a column vector):</p>
<pre class="fragment">--> A = float(rand(4))
A =
0.4011 0.4747 0.9193 0.8655
0.8633 0.0123 0.0599 0.5917
0.4939 0.5458 0.9481 0.4566
0.9335 0.8614 0.7993 0.6394
--> [u,s,v] = svd(A) % Compute the full decomposition
u =
-0.5290 0.2711 0.7178 0.3626
-0.3004 -0.8911 0.2379 -0.2431
-0.4868 0.3556 -0.0927 -0.7925
-0.6269 -0.0778 -0.6478 0.4259
s =
2.5579 0 0 0
0 0.7905 0 0
0 0 0.4392 0
0 0 0 0.1705
v =
-0.5071 -0.7054 -0.3579 -0.3422
-0.4146 0.3096 -0.6032 0.6070
-0.5735 0.5955 0.1558 -0.5406
-0.4921 -0.2279 0.6955 0.4713
--> sigmas = svd(A) % Only want the singular values
sigmas =
2.5579
0.7905
0.4392
0.1705
</pre><p>Normally, FreeMat uses the left hand side of an assignment to calculate the number of outputs for the function. When running a function in a thread, we separate the assignment of the output from the invokation of the function. Hence, we have to provide the number of arguments at the time we invoke the function. For example, to compute a full decomposition in a thread, we specify that we want 3 output arguments:</p>
<pre class="fragment">--> a = threadnew; % Create the thread
--> threadstart(a,'svd',3,A); % Start a full decomposition
--> [u1,s1,v1] = threadvalue(a); % Retrieve the function values
--> threadfree(a);
</pre><p>If we want to compute just the singular values, we start the thread function with only one output argument:</p>
<pre class="fragment">--> a = threadnew;
--> threadstart(a,'svd',1,A);
--> sigmas = threadvalue(a);
--> threadfree(a)
</pre> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="index.html">FreeMat Documentation</a></li><li class="navelem"><a class="el" href="sec_thread.html">FreeMat Threads</a></li>
<li class="footer">Generated on Thu Jul 25 2013 17:18:29 for FreeMat by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.1.1 </li>
</ul>
</div>
</body>
</html>
|
