Mercurial > flash_v2

comparison packages/kernel/current/doc/kernel.sgml @ 460:a65a4055f146

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* src/common/kapi.cxx: * include/kapi.h: Added function cyg_thread_get_next(), cyg_thread_find() and cyg_thread_get_info() to allow the current set of threads to be enumerated, and per-thread information to be retrieved safely. * doc/kernel.sgml: Documented new KAPI calls. * src/common/thread.cxx: Zero unique_id in thread destructor so that a stale thread pointer can be checked for validity. * include/instrmnt.h: Added cyg_instrument_state() to report the current state of an instrumentation flag. Moved ifdef for CYGDBG_KERNEL_INSTRUMENT_MSGS out of within FLAGS ifdef. We can have messages without flags. * src/instrmnt/meminst.cxx: Added cyg_instrument_state() to report the current state of an instrumentation flag. Modified cyg_instrument_msg() in line with header and table changes. * host/instr/dump_instr.c: * host/instr/instrument.sh: * include/instrument_desc.h: Added a final NULL element to the generated table in instrument_desc.h to mark its end. Otherwise code that does not have access to the table definition cannot find its end. Also added ifdefs to allow instrument_desc.h to be used to acquire the structure definition and table pointer.
author nickg
date Thu, 12 Dec 2002 18:31:34 +0000
parents b77e86276ec3
children 1061ceceb720
comparison
equal deleted inserted replaced
459:a6cede66ea36 460:a65a4055f146
1274 <refname>cyg_thread_self</refname> 1274 <refname>cyg_thread_self</refname>
1275 <refname>cyg_thread_idle_thread</refname> 1275 <refname>cyg_thread_idle_thread</refname>
1276 <refname>cyg_thread_get_stack_base</refname> 1276 <refname>cyg_thread_get_stack_base</refname>
1277 <refname>cyg_thread_get_stack_size</refname> 1277 <refname>cyg_thread_get_stack_size</refname>
1278 <refname>cyg_thread_measure_stack_usage</refname> 1278 <refname>cyg_thread_measure_stack_usage</refname>
1279 <refname>cyg_thread_get_next</refname>
1280 <refname>cyg_thread_get_info</refname>
1281 <refname>cyg_thread_find</refname>
1279 <refpurpose>Get basic thread information</refpurpose> 1282 <refpurpose>Get basic thread information</refpurpose>
1280 </refnamediv> 1283 </refnamediv>
1281 1284
1282 <refsynopsisdiv> 1285 <refsynopsisdiv>
1283 <funcsynopsis> 1286 <funcsynopsis>
1301 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef> 1304 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
1302 </funcprototype> 1305 </funcprototype>
1303 <funcprototype> 1306 <funcprototype>
1304 <funcdef>cyg_uint32 <function>cyg_thread_measure_stack_usage</function></funcdef> 1307 <funcdef>cyg_uint32 <function>cyg_thread_measure_stack_usage</function></funcdef>
1305 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef> 1308 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
1309 </funcprototype>
1310 <funcprototype>
1311 <funcdef>cyg_bool <function>cyg_thread_get_next</function></funcdef>
1312 <paramdef>cyg_handle_t *<parameter>thread</parameter></paramdef>
1313 <paramdef>cyg_uint16 *<parameter>id</parameter></paramdef>
1314 </funcprototype>
1315 <funcprototype>
1316 <funcdef>cyg_bool <function>cyg_thread_get_info</function></funcdef>
1317 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
1318 <paramdef>cyg_uint16 <parameter>id</parameter></paramdef>
1319 <paramdef>cyg_thread_info *<parameter>info</parameter></paramdef>
1320 </funcprototype>
1321 <funcprototype>
1322 <funcdef>cyg_handle_t <function>cyg_thread_find</function></funcdef>
1323 <paramdef>cyg_uint16 <parameter>id</parameter></paramdef>
1306 </funcprototype> 1324 </funcprototype>
1307 </funcsynopsis> 1325 </funcsynopsis>
1308 </refsynopsisdiv> 1326 </refsynopsisdiv>
1309 1327
1310 <refsect1 id="kernel-thread-info-description"><title>Description</title> 1328 <refsect1 id="kernel-thread-info-description"><title>Description</title>
1342 true upper bound, for example it is possible that in the current test 1360 true upper bound, for example it is possible that in the current test
1343 run the specified thread has not yet been interrupted at the deepest 1361 run the specified thread has not yet been interrupted at the deepest
1344 point in the function call graph. Never the less the value returned 1362 point in the function call graph. Never the less the value returned
1345 can give some useful indication of the thread's stack requirements. 1363 can give some useful indication of the thread's stack requirements.
1346 </para> 1364 </para>
1365 <para>
1366 <function>cyg_thread_get_next</function> is used to enumerate all the
1367 current threads in the system. It should be called intially with the
1368 locations pointed to by <parameter>thread</parameter> and
1369 <parameter>id</parameter> set to zero. On return these will be set to
1370 the handle and ID of the first thread. On subsequent calls, these
1371 parameters should be left set to the values returned by the previous
1372 call. The handle and ID of the next thread in the system will be
1373 installed each time, until a <literal>false</literal> return value
1374 indicates the end of the list.
1375 </para>
1376 <para>
1377 <function>cyg_thread_get_info</function> fills in the
1378 <type>cyg_thread_info</type> structure with information about the
1379 thread described by the <parameter>thread</parameter> and
1380 <parameter>id</parameter> arguments. The information returned includes
1381 the thread's handle and id, its state and name, priorities and stack
1382 parameters. If the thread does not exist the function returns
1383 <literal>false</literal>.
1384 </para>
1385 <para>
1386 <function>cyg_thread_find</function> returns a handle for the thread
1387 whose ID is <parameter>id</parameter>. If no such thread exists, a
1388 zero handle is returned.
1389 </para>
1347 </refsect1> 1390 </refsect1>
1348 1391
1349 <refsect1 id="kernel-thread-info-context"><title>Valid contexts</title> 1392 <refsect1 id="kernel-thread-info-context"><title>Valid contexts</title>
1350 <para> 1393 <para>
1351 <function>cyg_thread_self</function> may only be called from thread 1394 <function>cyg_thread_self</function> may only be called from thread
1357 any time after the specified thread has been created, but measuring 1400 any time after the specified thread has been created, but measuring
1358 stack usage involves looping over at least part of the thread's stack 1401 stack usage involves looping over at least part of the thread's stack
1359 so this should normally only be done from thread context. 1402 so this should normally only be done from thread context.
1360 </para> 1403 </para>
1361 </refsect1> 1404 </refsect1>
1405
1406 <refsect1 id="kernel-thread-info-examples"><title>Examples</title>
1407 <para>
1408 A simple example of the use of the
1409 <function>cyg_thread_get_next</function> and
1410 <function>cyg_thread_get_info</function> follows:
1411 </para>
1412 <programlisting width=72>
1413
1414 #include &lt;cyg/kernel/kapi.h&gt;
1415 #include &lt;stdio.h&gt;
1416
1417 void show_threads(void)
1418 {
1419 cyg_handle_t thread = 0;
1420 cyg_uint16 id = 0;
1421
1422 while( cyg_thread_get_next( &amp;thread, &amp;id ) )
1423 {
1424 cyg_thread_info info;
1425
1426 if( !cyg_thread_get_info( thread, id, &amp;info ) )
1427 break;
1428
1429 printf("ID: %04x name: %10s pri: %d\n",
1430 info.id, info.name?info.name:"----", info.set_pri );
1431 }
1432 }
1433
1434 </programlisting>
1435 </refsect1>
1436
1362 </refentry> 1437 </refentry>
1363 1438
1364 <!-- }}} --> 1439 <!-- }}} -->
1365 <!-- {{{ Thread control --> 1440 <!-- {{{ Thread control -->
1366 1441