home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 May / Pcwk5b98.iso / WEBSERVE / PI3 / PI3WEB.EXE / DEVEL / INCLUDE / PIThread.h < prev    next >
C/C++ Source or Header  |  1997-10-19  |  21KB  |  701 lines
  1. /*____________________________________________________________________________*\
  2.  *
  3.  
  4.  Copyright (c) 1997 John Roy. All rights reserved.
  5.  
  6.  These sources, libraries and applications are
  7.  FREE FOR COMMERCIAL AND NON-COMMERCIAL USE
  8.  as long as the following conditions are adhered to.
  9.  
  10.  Redistribution and use in source and binary forms, with or without
  11.  modification, are permitted provided that the following conditions
  12.  are met:
  13.  
  14.  1. Redistributions of source code must retain the above copyright
  15.     notice, this list of conditions and the following disclaimer. 
  16.  
  17.  2. Redistributions in binary form must reproduce the above copyright
  18.     notice, this list of conditions and the following disclaimer in
  19.     the documentation and/or other materials provided with the
  20.     distribution.
  21.  
  22.  3. Redistributions of any form whatsoever and all advertising materials 
  23.     mentioning features must contain the following
  24.     acknowledgment:
  25.     "This product includes software developed by John Roy
  26.     (http://www.johnroy.com/pi3/)."
  27.  
  28.  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  29.  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  30.  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  31.  IN NO EVENT SHALL THE AUTHORS OR ITS CONTRIBUTORS BE LIABLE FOR ANY
  32.  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  33.  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  34.  GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35.  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  36.  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  37.  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  38.  OF THE POSSIBILITY OF SUCH DAMAGE.
  39.  
  40.  *____________________________________________________________________________*|
  41.  *
  42.  * $Source: PIThread.h$
  43.  * $Date: Sun Aug 10 06:29:38 1997$
  44.  *
  45.  Description:
  46. \*____________________________________________________________________________*/
  47. /* $HeaderTop:$ */
  48.  
  49. #ifndef PITHREAD_H_
  50. #define PITHREAD_H_
  51.  
  52. #include "PiAPI.h"
  53.  
  54. /*____________________________________________________________________________*\
  55.  *
  56.  Typedefs:
  57. \*____________________________________________________________________________*/
  58. typedef struct Thread PIThread;
  59. typedef struct Allocator PIMemoryPool;
  60. typedef unsigned long (* PIThreadFn)( unsigned long);
  61.  
  62. /*____________________________________________________________________________*\
  63.  *
  64.  Name:
  65.     PIThread_new
  66.  
  67.  Synopsis:
  68.     PIThread *PIThread_new( PIMemoryPool *pPool, int iStackSize )
  69.  
  70.  Description:
  71.     Creates and initializes a new thread object. The function PIThread_begin()
  72.     can be used to run the thread.
  73.  
  74.     The parameters pPool and iStackSize are for future use but 
  75.     the values NULL and 0 respectively should be used to ensure
  76.     future compatibility.
  77.  
  78.  Notes:
  79.     If successful a new thread object will be created but will not
  80.     be executed.
  81.     
  82.     The pointer to the thread object remains valid until PIThread_delete() is    
  83.     called.
  84.  
  85.  Return Values:
  86.     On success PIThread_new() returns a pointer to a new
  87.     thread object.
  88.  
  89.  Errors:
  90.     On error PIThread_new() returns NULL.
  91.  
  92.     PIPlatform_getLastError() can be used to obtain more detailed
  93.     error information.
  94.  
  95.  See Also:
  96.     PIThread_delete().
  97. \*____________________________________________________________________________*/
  98. PUBLIC_PIAPI PIThread *PIThread_new( PIMemoryPool *pPool, int iStackSize );
  99.  
  100. /*____________________________________________________________________________*\
  101.  *
  102.  Name:
  103.     PIThread_begin
  104.  
  105.  Synopsis:
  106.     int PIThread_begin( PIThread *pThread, PIThreadFn fnEntry,
  107.         unsigned long ulData, int iPriority, int iFlags )
  108.  
  109.  Description:
  110.     Schedules the thread object pThread to be executed. The entry point
  111.     function fnEntry will invoked with the argument ulData.
  112.  
  113.     The value iPriority can be one of the thread priority values 
  114.     described in PIThread_setPriority() and indicates the initial
  115.     priority at which the thread runs.
  116.  
  117.     The value of iFlags is formed by OR'ing together zero or more of
  118.     the following values:-
  119.  
  120.         PITHREAD_FLAGS_SUSPENDED    The thread not run until PIThread_resume()
  121.  
  122.  Notes:
  123.     The thread object pThread can be a newly created object from 
  124.     PIThread_new() or a previously run thread which has terminated.
  125.     
  126.  Return Values:
  127.     On success PIThread_begin() returns zero (PIAPI_COMPLETED).
  128.  
  129.  Errors:
  130.     PIAPI_ERROR        if an error occurred.
  131.  
  132.     PIPlatform_getLastError() can be used to obtain more detailed error
  133.     information. 
  134.  
  135.  See Also:
  136.     PIThread_terminate(), PIThread_waitForThread().
  137. \*____________________________________________________________________________*/
  138. PUBLIC_PIAPI int PIThread_begin( PIThread *pThread, PIThreadFn fnEntry,
  139.     unsigned long ulData, int iPriority, int iFlags );
  140.  
  141. /*____________________________________________________________________________*\
  142.  *
  143.  Name:
  144.     PIThread_terminate
  145.  
  146.  Synopsis:
  147.     int PIThread_terminate( PIThread *pThread, unsigned long ulExitCode )
  148.  
  149.  Description:
  150.     Schedules the specified thread for termination. The thread will exit
  151.     with the status code ulExitCode.
  152.     
  153.  Notes:
  154.     ** IMPORTANT **
  155.     Use of this function is not recommended as the target thread will
  156.     usually have no opportunity to cleanup critical activity or
  157.     synchronized actions it may be performing. This can cause the state
  158.     of global objects to become unstable. This is true for user context
  159.     threads, and particularly true for some operating system threads 
  160.     implementations.
  161.  
  162.     PIThread_terminate is not guaranteed to wait for the thread to 
  163.     terminate. Use the function PIThread_waitForThread() after
  164.     PIThread_terminate() to poll for the termination of
  165.     another thread.
  166.     
  167.     If pThread is the main thread then the following actions will also
  168.     occur in order:-
  169.     <UL>
  170.         <ITEM>PIProgram_enter() will return PIAPI_COMPLETED, if used.
  171.         <ITEM>All other threads will be terminated, and thread objects
  172.             destroyed with PIThread_delete().
  173.         <ITEM>PIPlatform_enter() will return PIAPI_COMPLETED.
  174.     </UL>
  175.  
  176.  Return Values:
  177.     On success PIThread_terminate returns zero (PIAPI_COMPLETED).
  178.  
  179.  Errors:
  180.     PIAPI_ERROR        an error occurred.
  181.  
  182.     PIPlatform_getLastError() can be used to get more specific
  183.     error information.
  184.  
  185.  See Also:
  186.     PIThread_begin(), PIThread_waitForThread().    
  187. \*____________________________________________________________________________*/
  188. PUBLIC_PIAPI int PIThread_terminate( PIThread *pThread,
  189.     unsigned long ulExitCode );
  190.  
  191. /*____________________________________________________________________________*\
  192.  *
  193.  Name:
  194.     PIThread_delete
  195.  
  196.  Synopsis:
  197.     int PIThread_delete( PIThread *pThread )
  198.  
  199.  Description:
  200.     Destroys a thread object, and invalidates the pointer pThread.
  201.  
  202.  Notes:
  203.     If pThread has not terminated, PIThread_delete() will kill the thread
  204.     and poll for its termination using PIThread_terminate() and 
  205.     PIThread_waitForThread().
  206.  
  207.     PIThread_delete completely invalidates the pointer pThread, the 
  208.     results are undefined if the pointer pThread is used in a thread function
  209.     again. A defensive use of this function would set pThread to NULL after
  210.     PIThread_delete() has been successfully completed.
  211.  
  212.  Return Values:
  213.     On success PIThread_delete() returns zero (PIAPI_COMPLETED). 
  214.  
  215.  Errors:
  216.     PIAPI_ERROR        if an error occurred.
  217.  
  218.     PIPlatform_getLastError() can be used to get more specific error
  219.     information.
  220.  
  221.  See Also:
  222.     PIThread_new().
  223. \*____________________________________________________________________________*/
  224. PUBLIC_PIAPI int PIThread_delete( PIThread *pThread );
  225.  
  226. /*____________________________________________________________________________*\
  227.  *
  228.  Name:
  229.     PIThread_suspend
  230.  
  231.  Synopsis:
  232.     int PIThread_suspend( PIThread *pThread )
  233.  
  234.  Description:
  235.     Suspends execution of the thread pThread.
  236.  
  237.  Notes:
  238.  Return Values:
  239.     PIThread_suspend() return zero (PIAPI_COMPLETED) if the thread was
  240.     succesfully suspended or if the thread had previously been suspended.
  241.  
  242.  Errors:
  243.     PIAPI_ERROR     if an error occurred.
  244.  
  245.     PIPlatform_getLastError() can be used to get more specific error
  246.     information.
  247.  
  248.  See Also:
  249.     PIThread_resume().
  250. \*____________________________________________________________________________*/
  251. PUBLIC_PIAPI int PIThread_suspend( PIThread *pThread );
  252.  
  253. /*____________________________________________________________________________*\
  254.  *
  255.  Name:
  256.     PIThread_resume
  257.     
  258.  Synopsis:
  259.     int PIThread_resume( pThread )
  260.  
  261.  Description:
  262.     Resumes execution of a thread.
  263.  
  264.  Notes:
  265.  Return Values:
  266.     PIThread_resume() returns zero (PIAPI_COMPLETED) if the thread was
  267.     succesfully resumed or if the thread was not suspended.
  268.  
  269.  Errors:
  270.     PIAPI_ERROR        if an error occurred.
  271.  
  272.     PIPlatform_getLastError() can be used to get more specific error
  273.     information.
  274.  
  275.  See Also:
  276.     PIThread_suspend().
  277. \*____________________________________________________________________________*/
  278. PUBLIC_PIAPI int PIThread_resume( PIThread *pThread );
  279.  
  280. /*____________________________________________________________________________*\
  281.  *
  282.  Name:
  283.     PIThread_getSystemHandle
  284.  
  285.  Synopsis:
  286.     void *PIThread_getSystemHandle( PIThread *pThread )
  287.  
  288.  Description:
  289.     Returns the implementation specific handle or pointer of the the 
  290.     thread.
  291.     This value can be used to reference the thread in additional thread
  292.     library functions supplied by the operating system.
  293.  
  294.  Notes:
  295.     The value returned by PIThread_getSystemHandle() must be cast to the 
  296.     appriopriate type e.g. 'thread_t', 'HANDLE'. 
  297.  
  298.  Return Values:
  299.     On success PIThread_getSystemHandle() returns the specific 
  300.     operating system handle of the thread.
  301.  
  302.  Errors:
  303.     The function PIPlatform_getLastError() must be used to determine
  304.     if a handle value of NULL is an error or the valid system
  305.     dependant handle of the current thread.
  306.  
  307.     PIPlatform_getLastError() can be used to get more specific error
  308.     information.
  309.  
  310.  See Also:
  311. \*____________________________________________________________________________*/
  312. PUBLIC_PIAPI void *PIThread_getSystemHandle( PIThread *pThread );
  313.  
  314. /*____________________________________________________________________________*\
  315.  *
  316.  Name:
  317.     PIThread_yield
  318.  
  319.  Synopsis:
  320.     int PIThread_yield()
  321.  
  322.  Description:
  323.     Yield processing to another thread.
  324.  
  325.  Notes:
  326.     PIThread_waitForThread() does not attempt to terminate the thread
  327.     referenced by pThread, the function PIThread_terminate() can be used
  328.     for that.
  329.     When multithreading is implemented using the kernel threads
  330.     implementation of the current operating system with function will
  331.     invoke the appropriate theads system call to cause the current
  332.     thread to yield.
  333.     PIThread_yield() does not guarantee that the current thread will
  334.     yield. This is especially true when no other threads of equal or
  335.     greater priority are runnable.
  336.     
  337.  Return Values:
  338.     On success PIThread_yield() returns zero (PIAPI_COMPLETED).
  339.  
  340.  Errors:
  341.     PIAPI_ERROR     if an error occurred.
  342.  
  343.     PIPlatform_getLastError() can be used to get more specific error
  344.     information.
  345.  
  346.  See Also:
  347.     PIThread_userYield().
  348. \*____________________________________________________________________________*/
  349. PUBLIC_PIAPI int PIThread_yield();
  350.  
  351. /*____________________________________________________________________________*\
  352.  *
  353.  Name:
  354.     PIThread_userYield
  355.  
  356.  Synopsis:
  357.     int PIThread_userYield()
  358.  
  359.  Description:
  360.     Yield processing to another user thread. This function has no
  361.     effect when multi-threading is implemented with operating system
  362.     specific kernel threads.
  363.     When multithreading is implemented with user context threads this
  364.     function will behave like PIThread_Yield().
  365.  
  366.  Notes:
  367.     Unlike kernel supplied threads (operating system specific) 
  368.     user context threads will not context switch until a synchronization    
  369.     function, such as PISync_lock(), PIPlatform_pollNetFD() is invoked. In
  370.     code which does not use these synchronization functions (such as 
  371.     complex mathematical algorithms) one thread would monopolize all the
  372.     processing in the application. PIThread_userYield() can be inserted into
  373.     such code as a portable way to force preemptive thread behaviour
  374.     in a non-preemptive threads environment without added unnecessary 
  375.     PIThread_Yield() calls to kernel multithreading environments.
  376.     
  377.  Return Values:
  378.     On success PIThread_userYield() returns zero (PIAPI_COMPLETED).
  379.  
  380.  Errors:
  381.     PIAPI_ERROR     if an error occurred.
  382.  
  383.     PIPlatform_getLastError() can be used to get more specific error
  384.     information.
  385.  
  386.  See Also:
  387.     PIThread_yield().
  388. \*____________________________________________________________________________*/
  389. PUBLIC_PIAPI int PIThread_userYield();
  390.  
  391. /*____________________________________________________________________________*\
  392.  *
  393.  Name:
  394.     PIThread_waitForThread
  395.  
  396.  Synopsis:
  397.     int PIThread_waitForThread( PIThread *pThread );
  398.  
  399.  Description:
  400.     Suspends execution of the current thread until the thread referenced
  401.     by pThread has terminated.
  402.  
  403.  Notes:
  404.     PIThread_waitForThread() does not attempt to terminate the thread
  405.     referenced by pThread, the function PIThread_terminate() can be used
  406.     for that.
  407.     
  408.  Return Values:
  409.     PIThread_waitForThread() returns zero (PIAPI_COMPLETED) if the 
  410.     thread referenced by pThread has terminated.
  411.  
  412.  Errors:
  413.     PIAPI_ERROR        if an error occurred.
  414.  
  415.     PIPlatform_getLastError() can be used to get more specific error
  416.     information.
  417.  
  418.  See Also:
  419.     PIThread_terminate().
  420. \*____________________________________________________________________________*/
  421. PUBLIC_PIAPI int PIThread_waitForThread( PIThread *pThread );
  422.  
  423. /*____________________________________________________________________________*\
  424.  *
  425.  Name:
  426.     PIThread_initThreadKey
  427.  
  428.  Synopsis:
  429.     int PIThread_initThreadKey()
  430.  
  431.  Description:
  432.     Returns a new key (index) that can be used in PIThread_setData() and
  433.     PIThread_getData() to save and retrieve thread local data.
  434.  
  435.  Notes:
  436.  Return Values:
  437.     On success PIThread_initThreadKey() returns a non-negative thread
  438.     key.
  439.  
  440.  Errors:
  441.     On failure PIThread_initThreadKey() returns a negative number.
  442.  
  443.     PIPlatform_getLastError() can be used to get more specific error
  444.     information.
  445.  
  446.  See Also:
  447.     PIThread_destroyThreadKey().
  448. \*____________________________________________________________________________*/
  449. PUBLIC_PIAPI int PIThread_initThreadKey();
  450.  
  451. /*____________________________________________________________________________*\
  452.  *
  453.  Name:
  454.     PIThread_destroyThreadKey
  455.  
  456.  Synopsis:
  457.     int PIThread_destroyThreadKey( int iKey )
  458.  
  459.  Description:
  460.     Destroy the thread key (index) iKey. This key can subsequently be 
  461.     reassigned by PIThread_initThreadKey().
  462.  
  463.  Notes:
  464.  Return Values:
  465.     On success PIThread_destroyThreadKey() returns zero (PIAPI_COMPLETED).
  466.  
  467.  Errors:
  468.     On failure PIThread_destroyThreadKey() returns PIAPI_ERROR.
  469.  
  470.     PIPlatform_getLastError() can be used to get more specific error
  471.     information.
  472.  
  473.  See Also:
  474.     PIThread_initThreadKey().
  475. \*____________________________________________________________________________*/
  476. PUBLIC_PIAPI int PIThread_destroyThreadKey( int iKey );
  477.  
  478. /*____________________________________________________________________________*\
  479.  *
  480.  Name:
  481.     PIThread_setData
  482.  
  483.  Synopsis:
  484.     int PIThread_setData( PIThread *pThread, int iKey, void *pData )
  485.  
  486.  Description:
  487.     Sets the local data to pData for the thread referenced by pThread 
  488.     at the key iKey.
  489.  
  490.  Notes:
  491.  Return Values:
  492.     On success PIThread_setData() returns zero (PIAPI_COMPLETED).
  493.  
  494.  Errors:
  495.     PIAPI_ERROR        if an error occurred.
  496.  
  497.     PIPlatform_getLastError() can be used to get more specific error
  498.     information.
  499.  
  500.  See Also:
  501.     PIThread_getData().
  502. \*____________________________________________________________________________*/
  503. PUBLIC_PIAPI int PIThread_setData( PIThread *pThread, int iKey, void *pData );
  504.  
  505. /*____________________________________________________________________________*\
  506.  *
  507.  Name:
  508.     PIThread_getData
  509.  
  510.  Synopsis:
  511.     void *PIThread_getData( PIThread *pThread, int iKey )
  512.  
  513.  Description:
  514.     Returns the thread local data for the thread referenced by pThread
  515.     at key iKey. This is the value previously set by PIThread_setData() for
  516.     this thread and key.
  517.  
  518.  Notes:
  519.     All thread local data is zero initialized by PIThread_new(). 
  520.     It is undefined whether using PIThread_terminate() followed by
  521.     PIThread_begin() will modify thread local data when used to reuse a
  522.     thread.
  523.     
  524.  Return Values:
  525.     On success PIThread_getData() returns the thread local data for
  526.     this thread object at the specified key and PIPlatform_getLastError()
  527.     will return PIAPI_COMPLETED.
  528.  
  529.  Errors:
  530.     On error PIThread_getData() will return NULL and PIPlatform_getLastError()
  531.     will return a specific error code.
  532.  
  533.  See Also:
  534.     PIThread_setData().
  535. \*____________________________________________________________________________*/
  536. PUBLIC_PIAPI void *PIThread_getData( PIThread *pThread, int iKey );
  537.  
  538. /*____________________________________________________________________________*\
  539.  *
  540.  Name:
  541.     PIThread_getCurrent
  542.  
  543.  Synopsis:
  544.     PIThread *PIThread_getCurrent()
  545.  
  546.  Description:
  547.     Returns a pointer to the currently executing thread object.
  548.  
  549.  Notes:
  550.  Return Values:
  551.     On success PIThread_getCurrent() returns the non-NULL pointer 
  552.     to the currently executing thread object.
  553.  
  554.  Errors:
  555.     NULL     if an error occurs.
  556.  
  557.     PIPlatform_getLastError() can be used to get more specific error
  558.     information.
  559.  
  560.  See Also:
  561.     PIThread_getMain().
  562. \*____________________________________________________________________________*/
  563. PUBLIC_PIAPI PIThread *PIThread_getCurrent();
  564.  
  565. /*____________________________________________________________________________*\
  566.  *
  567.  Name:
  568.     PIThread_getMain
  569.  
  570.  Synopsis:
  571.     PIThread *PIThread_getMain()
  572.  
  573.  Description:
  574.     Returns a pointer to the main thread for the process.
  575.  
  576.  Notes:
  577.  Return Values:
  578.     On success PIThread_getCurrent() returns the non-NULL pointer 
  579.     to the main thread object.
  580.  
  581.  Errors:
  582.     NULL     if an error occurs.
  583.  
  584.     PIPlatform_getLastError() can be used to get more specific error
  585.     information.
  586.  
  587.  See Also:
  588.     PIThread_getCurrent().
  589. \*____________________________________________________________________________*/
  590. PUBLIC_PIAPI PIThread *PIThread_getMain();
  591.  
  592. /*____________________________________________________________________________*\
  593.  *
  594.  Name:
  595.     PIThread_getPriority
  596.  
  597.  Synopsis:
  598.     int PIThread_getPriority( PIThread *pThread, int *piPriority )
  599.  
  600.  Description:
  601.     Returns the priority of the thread pThread. piPriority points
  602.     to the location where the priority will be written.
  603.  
  604.  Notes:
  605.     See PIThread_setPriority() for a description of thread priorities.
  606.  
  607.  Return Values:
  608.     On success PIThread_getPriority() write the thread priority into
  609.     piPriority and returns zero (PIAPI_COMPLETED).
  610.  
  611.  Errors:
  612.     PIAPI_ERROR        if an error occurs.
  613.  
  614.     PIPlatform_getLastError() can be used to get more specific error
  615.     information.
  616.  
  617.  See Also:
  618.     PIThread_setPriority().
  619. \*____________________________________________________________________________*/
  620. PUBLIC_PIAPI int PIThread_getPriority( PIThread *pThread, int *piPriority );
  621.  
  622. /*____________________________________________________________________________*\
  623.  *
  624.  Name:
  625.     PIThread_setPriority
  626.  
  627.  Synopsis:
  628.     int PIThread_setPriority( PIThread *pThread, int iNewPriority )
  629.  
  630.  Description:
  631.     Set the priority of the thread pThread. The following are valid
  632.     priority values.
  633.  
  634.     <TABLE>
  635.     <TR>    PITHREAD_PRIORITY_LOWEST
  636.     <TR>    PITHREAD_PRIORITY_LOW
  637.     <TR>    PITHREAD_PRIORITY_MED
  638.     <TR>    PITHREAD_PRIORITY_HIGH
  639.     <TR>    PITHREAD_PRIORITY_HIGHEST
  640.     </TABLE>
  641.  
  642.  Notes:
  643.     The precise behaviour of threads and thread priorities varies
  644.     greatly across implementations. In general a higher priority
  645.     thread will be scheduled before and run for longer than a
  646.     lower priority thread. However whether or not a lower priority
  647.     thread with be scheduled AT ALL when higher priority threads
  648.     are runnable is implementation defined. 
  649.  
  650.     The main thread initially runs at priority PITHREAD_PRIORITY_MED.
  651.  
  652.  Return Values:
  653.     On success PIThread_setPriority() returns zero (PIAPI_COMPLETED).
  654.  
  655.  Errors:
  656.     PIAPI_ERROR        if an error occurs.
  657.  
  658.     PIPlatform_getLastError() can be used to get more specific error
  659.     information.
  660.  
  661.  See Also:
  662.     PIThread_getPriority().
  663. \*____________________________________________________________________________*/
  664. PUBLIC_PIAPI int PIThread_setPriority( PIThread *pThread, int iNewPriority );
  665.  
  666. /*____________________________________________________________________________*\
  667.  *
  668.  Name:
  669.     PIThread_dbgDump
  670.  
  671.  Synopsis:
  672.     void PIThread_dbgDump( const char *pDumpFile )
  673.  
  674.  Description:
  675.     Opens the specified file for write append and writes internal
  676.     information on thread status within the program.
  677.     If pDumpFile is NULL, information will be written to the stdout stream.
  678.  
  679.  Notes:
  680.     This function is mainly for getting verbose information on 
  681.     thread scheduling when the internal user thread implementation is
  682.     being used. 
  683.     If operating system kernel threads are used this debugging  
  684.     information will be terse.
  685.  
  686.  Return Values:
  687.     PIThread_dbgDump does not return a value.
  688.  
  689.  Errors:
  690.     PIThread_dbgDump does not return errors.
  691.  
  692.     PIPlatform_getLastError() can be used to get more specific error
  693.     information.
  694.  
  695.  See Also:
  696. \*____________________________________________________________________________*/
  697. PUBLIC_PIAPI void PIThread_dbgDump( const char *pDbgDump );
  698.  
  699. #endif    /* PITHREAD_H_ */
  700.  
  701.