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 span.virtual_style 22 { 23 font-size : 8pt; 24 color : white; 25 font-weight : bold; 26 background : #0a0; 27 border-left : solid 1px #0f0; 28 border-top : solid 1px #0f0; 29 border-right : solid 1px #060; 30 border-bottom : solid 1px #060; 31 padding-left : 2px; 32 padding-right : 2px; 33 } 34 span.protected_style 35 { 36 font-size : 8pt; 37 color : white; 38 font-weight : bold; 39 background : #444; 40 border-left : solid 1px #ccc; 41 border-top : solid 1px #ccc; 42 border-right : solid 1px #222; 43 border-bottom : solid 1px #222; 44 padding-left : 2px; 45 padding-right : 2px; 46 } 47 --></style> 48<title>nn::os::Thread</title> 49 </head> 50 <body> 51<h1><CODE>nn::os::Thread</CODE> Class</h1> 52 <div class="section"> 53<b>Header file: </b>nn/os.h</div> 54<h2>Syntax</h2> 55 <div class="section"> 56 <pre class="definition">class Thread : public <a href="../../../nn/os/WaitObject/Overview.html">nn::os::WaitObject</a></pre> 57 </div> 58<h2>Description</h2> 59 <div class="section"> 60<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><p>You can create up to 32 <a href="../../../nn/os/Thread/Overview.html"><CODE>Thread</CODE></a> objects. Note also that different functions might use up resources that count against this limit.</p><!-- write here --></div> 61 <a name="function" id="function"> 62<h2>Member Functions</h2> 63 <div class="section"> 64 <table class="members"> 65 <tr> 66 <td width="100"> </td> 67 <th> 68<a href="../../../nn/os/Thread/Thread.html"><CODE>Thread</CODE></a> 69 </th> 70<td>Constructor.</td> 71 </tr> 72 <tr> 73 <td width="100"> </td> 74 <th> 75<a href="../../../nn/os/Thread/~Thread.html"><CODE>~Thread</CODE></a> 76 </th> 77<td>Destructor.</td> 78 </tr> 79 <tr> 80 <td width="100"> </td> 81 <th> 82<a href="../../../nn/os/Thread/Start.html"><CODE>Start</CODE></a> 83 </th> 84<td>Initializes and runs a thread.</td> 85 </tr> 86 <tr> 87 <td width="100"> </td> 88 <th> 89<a href="../../../nn/os/Thread/TryStart.html"><CODE>TryStart</CODE></a> 90 </th> 91<td>Tries to initialize and run a thread.</td> 92 </tr> 93 <tr> 94 <td width="100"> </td> 95 <th> 96<a href="../../../nn/os/Thread/StartUsingAutoStack.html"><CODE>StartUsingAutoStack</CODE></a> 97 </th> 98<td>Initializes and runs a thread.</td> 99 </tr> 100 <tr> 101 <td width="100"> </td> 102 <th> 103<a href="../../../nn/os/Thread/TryStartUsingAutoStack.html"><CODE>TryStartUsingAutoStack</CODE></a> 104 </th> 105<td>Tries to initialize and run a thread.</td> 106 </tr> 107 <tr> 108 <td width="100"> </td> 109 <th> 110<a href="../../../nn/os/Thread/Finalize.html"><CODE>Finalize</CODE></a> 111 </th> 112<td>Destroys a thread object.</td> 113 </tr> 114 <tr> 115 <td width="100"> </td> 116 <th> 117<a href="../../../nn/os/Thread/Join.html"><CODE>Join</CODE></a> 118 </th> 119<td>Waits for a thread to exit.</td> 120 </tr> 121 <tr> 122 <td width="100"> </td> 123 <th> 124<a href="../../../nn/os/Thread/Detach.html"><CODE>Detach</CODE></a> 125 </th> 126<td>Detaches a thread.</td> 127 </tr> 128 <tr> 129 <td width="100"> </td> 130 <th> 131<a href="../../../nn/os/Thread/IsAlive.html"><CODE>IsAlive</CODE></a> 132 </th> 133<td>Gets whether a thread is alive.</td> 134 </tr> 135 <tr> 136 <td width="100"> </td> 137 <th> 138<a href="../../../nn/os/Thread/GetId.html"><CODE>GetId</CODE></a> 139 </th> 140<td>Gets the thread ID of an instance.</td> 141 </tr> 142 <tr> 143 <td width="100"> </td> 144 <th> 145<a href="../../../nn/os/Thread/GetPriority.html"><CODE>GetPriority</CODE></a> 146 </th> 147<td>Gets the thread priority of an instance.</td> 148 </tr> 149 <tr> 150 <td width="100"> </td> 151 <th> 152<a href="../../../nn/os/Thread/ChangePriority.html"><CODE>ChangePriority</CODE></a> 153 </th> 154<td>Sets the thread priority of an instance.</td> 155 </tr> 156 <tr> 157 <td width="100"> </td> 158 <th> 159<a href="../../../nn/os/Thread/GetAffinityMask.html"><CODE>GetAffinityMask</CODE></a> 160 </th> 161<td>Gets the affinity mask of an instance.</td> 162 </tr> 163 <tr> 164 <td width="100"> </td> 165 <th> 166<a href="../../../nn/os/Thread/ChangeAffinityMask.html"><CODE>ChangeAffinityMask</CODE></a> 167 </th> 168<td>Sets the affinity mask of an instance.</td> 169 </tr> 170 <tr> 171 <td width="100"> </td> 172 <th> 173<a href="../../../nn/os/Thread/GetIdealProcessor.html"><CODE>GetIdealProcessor</CODE></a> 174 </th> 175<td>Gets the preferred processor number of an instance.</td> 176 </tr> 177 <tr> 178 <td width="100"> </td> 179 <th> 180<a href="../../../nn/os/Thread/ChangeIdealProcessor.html"><CODE>ChangeIdealProcessor</CODE></a> 181 </th> 182<td>Sets the preferred processor number of an instance.</td> 183 </tr> 184 <tr> 185 <td width="100"> 186<span class="static_style" title="static">S</span> </td> 187 <th> 188<a href="../../../nn/os/Thread/Sleep.html"><CODE>Sleep</CODE></a> 189 </th> 190<td>Puts the current thread to sleep for the time specified.</td> 191 </tr> 192 <tr> 193 <td width="100"> 194<span class="static_style" title="static">S</span> </td> 195 <th> 196<a href="../../../nn/os/Thread/Yield.html"><CODE>Yield</CODE></a> 197 </th> 198<td>Gives threads with the same priority level as the current thread a chance to run.</td> 199 </tr> 200 <tr> 201 <td width="100"> 202<span class="static_style" title="static">S</span> </td> 203 <th> 204<a href="../../../nn/os/Thread/GetCurrentId.html"><CODE>GetCurrentId</CODE></a> 205 </th> 206<td>Gets the thread ID of the current thread.</td> 207 </tr> 208 <tr> 209 <td width="100"> 210<span class="static_style" title="static">S</span> </td> 211 <th> 212<a href="../../../nn/os/Thread/GetCurrentPriority.html"><CODE>GetCurrentPriority</CODE></a> 213 </th> 214<td>Gets the priority of the current thread.</td> 215 </tr> 216 <tr> 217 <td width="100"> 218<span class="static_style" title="static">S</span> </td> 219 <th> 220<a href="../../../nn/os/Thread/ChangeCurrentPriority.html"><CODE>ChangeCurrentPriority</CODE></a> 221 </th> 222<td>Sets the priority of the current thread.</td> 223 </tr> 224 <tr> 225 <td width="100"> 226<span class="static_style" title="static">S</span> </td> 227 <th> 228<a href="../../../nn/os/Thread/GetCurrentAffinityMask.html"><CODE>GetCurrentAffinityMask</CODE></a> 229 </th> 230<td>Gets the affinity mask of the current thread.</td> 231 </tr> 232 <tr> 233 <td width="100"> 234<span class="static_style" title="static">S</span> </td> 235 <th> 236<a href="../../../nn/os/Thread/GetDefaultAffinityMask.html"><CODE>GetDefaultAffinityMask</CODE></a> 237 </th> 238<td>Gets the affinity mask of threads created using <CODE>coreNo = CORE_NO_USE_PROCESS_VALUE</CODE>.</td> 239 </tr> 240 <tr> 241 <td width="100"> 242<span class="static_style" title="static">S</span> </td> 243 <th> 244<a href="../../../nn/os/Thread/ChangeCurrentAffinityMask.html"><CODE>ChangeCurrentAffinityMask</CODE></a> 245 </th> 246<td>Sets the affinity mask of the current thread.</td> 247 </tr> 248 <tr> 249 <td width="100"> 250<span class="static_style" title="static">S</span> </td> 251 <th> 252<a href="../../../nn/os/Thread/SetDefaultAffinityMask.html"><CODE>SetDefaultAffinityMask</CODE></a> 253 </th> 254<td>Sets the affinity mask of threads created using <CODE>coreNo = CORE_NO_USE_PROCESS_VALUE</CODE>.</td> 255 </tr> 256 <tr> 257 <td width="100"> 258<span class="static_style" title="static">S</span> </td> 259 <th> 260<a href="../../../nn/os/Thread/GetCurrentIdealProcessor.html"><CODE>GetCurrentIdealProcessor</CODE></a> 261 </th> 262<td>Gets the preferred processor number of the current thread.</td> 263 </tr> 264 <tr> 265 <td width="100"> 266<span class="static_style" title="static">S</span> </td> 267 <th> 268<a href="../../../nn/os/Thread/GetDefaultIdealProcessor.html"><CODE>GetDefaultIdealProcessor</CODE></a> 269 </th> 270<td>Gets the preferred processor number of threads that are created using <CODE>coreNo = CORE_NO_USE_PROCESS_VALUE</CODE>.</td> 271 </tr> 272 <tr> 273 <td width="100"> 274<span class="static_style" title="static">S</span> </td> 275 <th> 276<a href="../../../nn/os/Thread/ChangeCurrentIdealProcessor.html"><CODE>ChangeCurrentIdealProcessor</CODE></a> 277 </th> 278<td>Sets the preferred processor number of the current thread.</td> 279 </tr> 280 <tr> 281 <td width="100"> 282<span class="static_style" title="static">S</span> </td> 283 <th> 284<a href="../../../nn/os/Thread/SetDefaultIdealProcessor.html"><CODE>SetDefaultIdealProcessor</CODE></a> 285 </th> 286<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> 287 </tr> 288 <tr> 289 <td width="100"> 290<span class="static_style" title="static">S</span> </td> 291 <th> 292<a href="../../../nn/os/Thread/GetCurrentProcessorNumber.html"><CODE>GetCurrentProcessorNumber</CODE></a> 293 </th> 294<td>Gets the number of the processor that the current thread is running on.</td> 295 </tr> 296 <tr> 297 <td width="100"> 298<span class="static_style" title="static">S</span> </td> 299 <th> 300<a href="../../../nn/os/Thread/GetMainThread.html"><CODE>GetMainThread</CODE></a> 301 </th> 302<td>Gets the object that represents the main thread.</td> 303 </tr> </table> 304 </div> 305 </a> 306<h2>Class Hierarchy</h2> 307 <div class="section"> 308<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> 309 </p> 310 </div> 311<h2>Revision History</h2> 312 <div class="section"> 313 <dl class="history"> 314 <dt>2010/01/07</dt> 315<dd>Initial version.<br /> 316 </dd> 317 </dl> 318 </div> 319 <hr><p>CONFIDENTIAL</p></body> 320</html> 321