1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2<html xml:lang="en-US" lang="en-US" xmlns="http://www.w3.org/1999/xhtml"> 3 <head> 4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 5 <meta http-equiv="Content-Style-Type" content="text/css" /> 6 <link rel="stylesheet" href="../../../css/manpage.css" type="text/css" /> 7 <style type="text/css"><!-- 8 span.static_style 9 { 10 font-size : 8pt; 11 color : white; 12 font-weight : bold; 13 background : #44f; 14 border-left : solid 1px #aaf; 15 border-top : solid 1px #aaf; 16 border-right : solid 1px #00c; 17 border-bottom : solid 1px #00c; 18 padding-left : 2px; 19 padding-right : 2px; 20 } 21 22 span.virtual_style 23 { 24 font-size : 8pt; 25 color : white; 26 font-weight : bold; 27 background : #0a0; 28 border-left : solid 1px #0f0; 29 border-top : solid 1px #0f0; 30 border-right : solid 1px #060; 31 border-bottom : solid 1px #060; 32 padding-left : 2px; 33 padding-right : 2px; 34 } 35 36 span.protected_style 37 { 38 font-size : 8pt; 39 color : white; 40 font-weight : bold; 41 background : #444; 42 border-left : solid 1px #ccc; 43 border-top : solid 1px #ccc; 44 border-right : solid 1px #222; 45 border-bottom : solid 1px #222; 46 padding-left : 2px; 47 padding-right : 2px; 48 } 49 --></style> 50<title>nn::os::Thread</title> 51 </head> 52 <body> 53<h1><CODE>nn::os::Thread</CODE> Class</h1> 54 <div class="section"> 55<b>Header file: </b>nn/os.h</div> 56<h2>Syntax</h2> 57 <div class="section"> 58 <pre class="definition">class Thread : public <a href="../../../nn/os/WaitObject/Overview.html">nn::os::WaitObject</a></pre> 59 </div> 60<h2>Description</h2> 61 <div class="section"> 62<p>Class for representing threads.</p><p><STRONG>Bug:</STRONG>The current implementation does not allow you to set the preferred processor or affinity mask.</p><p>Threads have priorities. The thread priority is specified as an integer from 0 to 31, with 0 indicating the highest priority. Standard threads specify the <CODE>DEFAULT_THREAD_PRIORITY</CODE> of <CODE>16</CODE>.</p><p>Threads require a stack region to run. The management of the stack region can either be handled by the programmer, or you can leave it to be handled by the library.</p><p>When managing the stack region yourself, pass the stack region to the <CODE><a href="../../../nn/os/Thread/Start.html">Start</a></CODE> function and start the thread. Pass a stack region that is an instance of a class that has a function similar to <CODE>uptr GetStackBottom()</CODE>. The <CODE><a href="../../../nn/os/StackMemoryBlock/Overview.html">StackMemoryBlock</a></CODE> and <CODE><a href="../../../nn/os/StackBuffer/Overview.html">StackBuffer</a></CODE> classes meet these requirements, so they can pass the stack region directly. <BR><B>Note:</B> When managing the stack region yourself, note that the stack region is never disabled (freed or otherwise invalidated) before the thread exits.</p><p>When letting the library manage the stack region, pass the stack size to the <CODE><a href="../../../nn/os/Thread/StartUsingAutoStack.html">StartUsingAutoStack</a></CODE> function and start the thread. The library allocates the stack region in 4096-byte chunks.</p><p>Thread objects become valid once <CODE>Start</CODE>-series functions have been left. Note that it is not at the point when a thread starts running. The <CODE>IsValid</CODE> function can be used to check whether an object is valid.</p><p>You must always call <CODE><a href="../../../nn/os/Thread/Join.html">Join</a></CODE> explicitly before destroying <CODE><a href="../../../nn/os/Thread/Overview.html">Thread</a></CODE> objects that were started using the <CODE><a href="../../../nn/os/Thread/Start.html">Start</a></CODE> function. You cannot call <CODE><a href="../../../nn/os/Thread/Detach.html">Detach</a></CODE>.</p><p>You must always call either <CODE><a href="../../../nn/os/Thread/Join.html">Join</a></CODE> or <CODE><a href="../../../nn/os/Thread/Detach.html">Detach</a></CODE> explicitly before destroying <CODE><a href="../../../nn/os/Thread/Overview.html">Thread</a></CODE> objects that were started using the <CODE><a href="../../../nn/os/Thread/StartUsingAutoStack.html">StartUsingAutoStack</a></CODE> function.</p><p><CODE><a href="../../../nn/os/Thread/Overview.html">Thread</a></CODE> objects inherit <CODE><a href="../../../nn/os/WaitObject/Overview.html">WaitObject</a></CODE> objects; when a thread is released from waiting, it means that the thread has exited. When it's necessary to perform non-blocking <CODE><a href="../../../nn/os/Thread/Join.html">Join</a></CODE> operations, call a function like <CODE><a href="../../../nn/os/WaitObject/WaitOne.html">WaitOne</a></CODE> or <CODE><a href="../../../nn/os/WaitObject/WaitAny.html">WaitObject::WaitAny</a></CODE> first to verify that the thread has been released from waiting.</p><p><B>Note:</B> In the current implementation, preferred processors and affinity masks can only be specified when starting a thread.</p><p>You can specify a preferred processor and affinity mask for threads. The preferred processor is specified with a value ranging from <CODE>0</CODE> to <CODE>c-1</CODE>, where <CODE>c</CODE> represents the number of cores. Alternately, specifying <CODE>CORE_NO_ALL</CODE> gives all processors equal priority as the preferred processor and uses an affinity mask that includes all processors. Specifying <CODE>CORE_NO_USE_PROCESS_VALUE</CODE> uses the default value of the associated application. Specifying a preferred processor will make the thread give priority to running on the specified processor, but it doesn't guarantee that the thread will run on the processor you specify.</p><p>Affinity masks specify which possible processors a thread prefers to run on. An affinity mask is expressed as an <CODE>bit8</CODE> array. In each element, the least-significant bit indicates the first processor. Setting a particular bit to <CODE>1</CODE> gives permission for the thread to run on the corresponding processor. It's necessary to specify at least one processor; specifying masks with every bit set to zero is not allowed.</p><p>Using a processor number to specify the preferred processor when a thread is started creates an affinity mask in which the only bit that is set is that of the specified processor.</p><!-- write here --></div> 63 <a name="function" id="function"> 64<h2>Member Functions</h2> 65 <div class="section"> 66 <table class="members"> 67 <tr> 68 <td width="100"> </td> 69 <th> 70<a href="../../../nn/os/Thread/Thread.html"><CODE>Thread</CODE></a> 71 </th> 72<td>Constructor.</td> 73 </tr> 74 <tr> 75 <td width="100"> </td> 76 <th> 77<a href="../../../nn/os/Thread/~Thread.html"><CODE>~Thread</CODE></a> 78 </th> 79<td>Destructor.</td> 80 </tr> 81 <tr> 82 <td width="100"> </td> 83 <th> 84<a href="../../../nn/os/Thread/Start.html"><CODE>Start</CODE></a> 85 </th> 86<td>Initializes and runs a thread.</td> 87 </tr> 88 <tr> 89 <td width="100"> </td> 90 <th> 91<a href="../../../nn/os/Thread/TryStart.html"><CODE>TryStart</CODE></a> 92 </th> 93<td>Tries to initialize and run a thread.</td> 94 </tr> 95 <tr> 96 <td width="100"> </td> 97 <th> 98<a href="../../../nn/os/Thread/StartUsingAutoStack.html"><CODE>StartUsingAutoStack</CODE></a> 99 </th> 100<td>Initializes and runs a thread.</td> 101 </tr> 102 <tr> 103 <td width="100"> </td> 104 <th> 105<a href="../../../nn/os/Thread/TryStartUsingAutoStack.html"><CODE>TryStartUsingAutoStack</CODE></a> 106 </th> 107<td>Tries to initialize and run a thread.</td> 108 </tr> 109 <tr> 110 <td width="100"> </td> 111 <th> 112<a href="../../../nn/os/Thread/Finalize.html"><CODE>Finalize</CODE></a> 113 </th> 114<td>Destroys a thread object.</td> 115 </tr> 116 <tr> 117 <td width="100"> </td> 118 <th> 119<a href="../../../nn/os/Thread/Join.html"><CODE>Join</CODE></a> 120 </th> 121<td>Waits for a thread to exit.</td> 122 </tr> 123 <tr> 124 <td width="100"> </td> 125 <th> 126<a href="../../../nn/os/Thread/Detach.html"><CODE>Detach</CODE></a> 127 </th> 128<td>Detaches a thread.</td> 129 </tr> 130 <tr> 131 <td width="100"> </td> 132 <th> 133<a href="../../../nn/os/Thread/IsAlive.html"><CODE>IsAlive</CODE></a> 134 </th> 135<td>Gets whether a thread is alive.</td> 136 </tr> 137 <tr> 138 <td width="100"> </td> 139 <th> 140<a href="../../../nn/os/Thread/GetId.html"><CODE>GetId</CODE></a> 141 </th> 142<td>Gets the thread ID of an instance.</td> 143 </tr> 144 <tr> 145 <td width="100"> </td> 146 <th> 147<a href="../../../nn/os/Thread/GetPriority.html"><CODE>GetPriority</CODE></a> 148 </th> 149<td>Gets the thread priority of an instance.</td> 150 </tr> 151 <tr> 152 <td width="100"> </td> 153 <th> 154<a href="../../../nn/os/Thread/ChangePriority.html"><CODE>ChangePriority</CODE></a> 155 </th> 156<td>Sets the thread priority of an instance.</td> 157 </tr> 158 <tr> 159 <td width="100"> </td> 160 <th> 161<a href="../../../nn/os/Thread/GetAffinityMask.html"><CODE>GetAffinityMask</CODE></a> 162 </th> 163<td>Gets the affinity mask of an instance.</td> 164 </tr> 165 <tr> 166 <td width="100"> </td> 167 <th> 168<a href="../../../nn/os/Thread/ChangeAffinityMask.html"><CODE>ChangeAffinityMask</CODE></a> 169 </th> 170<td>Sets the affinity mask of an instance.</td> 171 </tr> 172 <tr> 173 <td width="100"> </td> 174 <th> 175<a href="../../../nn/os/Thread/GetIdealProcessor.html"><CODE>GetIdealProcessor</CODE></a> 176 </th> 177<td>Gets the preferred processor number of an instance.</td> 178 </tr> 179 <tr> 180 <td width="100"> </td> 181 <th> 182<a href="../../../nn/os/Thread/ChangeIdealProcessor.html"><CODE>ChangeIdealProcessor</CODE></a> 183 </th> 184<td>Sets the preferred processor number of an instance.</td> 185 </tr> 186 <tr> 187 <td width="100"> 188<span class="static_style" title="static">S</span> </td> 189 <th> 190<a href="../../../nn/os/Thread/Sleep.html"><CODE>Sleep</CODE></a> 191 </th> 192<td>Puts the current thread to sleep for the time specified.</td> 193 </tr> 194 <tr> 195 <td width="100"> 196<span class="static_style" title="static">S</span> </td> 197 <th> 198<a href="../../../nn/os/Thread/Yield.html"><CODE>Yield</CODE></a> 199 </th> 200<td>Gives threads with the same priority level as the current thread a chance to run.</td> 201 </tr> 202 <tr> 203 <td width="100"> 204<span class="static_style" title="static">S</span> </td> 205 <th> 206<a href="../../../nn/os/Thread/GetCurrentId.html"><CODE>GetCurrentId</CODE></a> 207 </th> 208<td>Gets the thread ID of the current thread.</td> 209 </tr> 210 <tr> 211 <td width="100"> 212<span class="static_style" title="static">S</span> </td> 213 <th> 214<a href="../../../nn/os/Thread/GetCurrentPriority.html"><CODE>GetCurrentPriority</CODE></a> 215 </th> 216<td>Gets the priority of the current thread.</td> 217 </tr> 218 <tr> 219 <td width="100"> 220<span class="static_style" title="static">S</span> </td> 221 <th> 222<a href="../../../nn/os/Thread/ChangeCurrentPriority.html"><CODE>ChangeCurrentPriority</CODE></a> 223 </th> 224<td>Sets the priority of the current thread.</td> 225 </tr> 226 <tr> 227 <td width="100"> 228<span class="static_style" title="static">S</span> </td> 229 <th> 230<a href="../../../nn/os/Thread/GetCurrentAffinityMask.html"><CODE>GetCurrentAffinityMask</CODE></a> 231 </th> 232<td>Gets the affinity mask of the current thread.</td> 233 </tr> 234 <tr> 235 <td width="100"> 236<span class="static_style" title="static">S</span> </td> 237 <th> 238<a href="../../../nn/os/Thread/GetDefaultAffinityMask.html"><CODE>GetDefaultAffinityMask</CODE></a> 239 </th> 240<td>Gets the affinity mask of threads created using <CODE>coreNo = CORE_NO_USE_PROCESS_VALUE</CODE>.</td> 241 </tr> 242 <tr> 243 <td width="100"> 244<span class="static_style" title="static">S</span> </td> 245 <th> 246<a href="../../../nn/os/Thread/ChangeCurrentAffinityMask.html"><CODE>ChangeCurrentAffinityMask</CODE></a> 247 </th> 248<td>Sets the affinity mask of the current thread.</td> 249 </tr> 250 <tr> 251 <td width="100"> 252<span class="static_style" title="static">S</span> </td> 253 <th> 254<a href="../../../nn/os/Thread/SetDefaultAffinityMask.html"><CODE>SetDefaultAffinityMask</CODE></a> 255 </th> 256<td>Sets the affinity mask of threads created using <CODE>coreNo = CORE_NO_USE_PROCESS_VALUE</CODE>.</td> 257 </tr> 258 <tr> 259 <td width="100"> 260<span class="static_style" title="static">S</span> </td> 261 <th> 262<a href="../../../nn/os/Thread/GetCurrentIdealProcessor.html"><CODE>GetCurrentIdealProcessor</CODE></a> 263 </th> 264<td>Gets the preferred processor number of the current thread.</td> 265 </tr> 266 <tr> 267 <td width="100"> 268<span class="static_style" title="static">S</span> </td> 269 <th> 270<a href="../../../nn/os/Thread/GetDefaultIdealProcessor.html"><CODE>GetDefaultIdealProcessor</CODE></a> 271 </th> 272<td>Gets the preferred processor number of threads that are created using <CODE>coreNo = CORE_NO_USE_PROCESS_VALUE</CODE>.</td> 273 </tr> 274 <tr> 275 <td width="100"> 276<span class="static_style" title="static">S</span> </td> 277 <th> 278<a href="../../../nn/os/Thread/ChangeCurrentIdealProcessor.html"><CODE>ChangeCurrentIdealProcessor</CODE></a> 279 </th> 280<td>Sets the preferred processor number of the current thread.</td> 281 </tr> 282 <tr> 283 <td width="100"> 284<span class="static_style" title="static">S</span> </td> 285 <th> 286<a href="../../../nn/os/Thread/SetDefaultIdealProcessor.html"><CODE>SetDefaultIdealProcessor</CODE></a> 287 </th> 288<td>Sets the <SPAN class="argument">IdealProcessor</SPAN> value to use for threads that are created using <CODE>coreNo = CORE_NO_USE_PROCESS_VALUE</CODE>.</td> 289 </tr> 290 <tr> 291 <td width="100"> 292<span class="static_style" title="static">S</span> </td> 293 <th> 294<a href="../../../nn/os/Thread/GetCurrentProcessorNumber.html"><CODE>GetCurrentProcessorNumber</CODE></a> 295 </th> 296<td>Gets the number of the processor that the current thread is running on.</td> 297 </tr> 298 <tr> 299 <td width="100"> 300<span class="static_style" title="static">S</span> </td> 301 <th> 302<a href="../../../nn/os/Thread/GetMainThread.html"><CODE>GetMainThread</CODE></a> 303 </th> 304<td>Gets the object that represents the main thread.</td> 305 </tr> </table> 306 </div> 307 </a> 308<h2>Class Hierarchy</h2> 309 <div class="section"> 310<p class="hierarchy"><span>ADLFireWall::NonCopyable</span><br /> <a href="../../../nn/os/HandleObject/Overview.html">nn::os::HandleObject</a><br /> <a href="../../../nn/os/WaitObject/Overview.html">nn::os::WaitObject</a><br /> <b>nn::os::Thread</b> 311 </p> 312 </div> 313<h2>Revision History</h2> 314 <div class="section"> 315 <dl class="history"> 316 <dt>2010/01/07</dt> 317<dd>Initial version.<br /> 318 </dd> 319 </dl> 320 </div> 321 <hr><p>CONFIDENTIAL</p></body> 322</html>