home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / THDPL.ZIP / THRDPOOL.DOC < prev    next >
Text File  |  1992-02-02  |  7KB  |  145 lines
  1.                                                             CoralSoft, Inc.
  2.                                                           305 Judson Dr. E.
  3.                                                      Mobile, AL  36608-3007
  4.                                                              (205) 344-2251
  5. ---------------------------------------------------------------------------
  6.                         ThreadPool Class Documentation
  7.                                    for OS/2
  8.                                   Prerelease
  9. ---------------------------------------------------------------------------
  10.  
  11.    ThreadPool is a C++ class designed to improve performance of multi-
  12. threaded OS/2 applications by starting a 'pool' of threads for execution
  13. of user functions.  Rather than incurring the overhead of starting a new
  14. thread each time one is desired, the class chooses an idle thread from
  15. the pool as a candidate for execution of the user function.  This technique
  16. is recommended by IBM for improving multi-threaded performance.
  17.  
  18.    The ThreadPool class also improves upon the standard _beginthread
  19. function by allowing a C++ function to be started as a thread.  Normally, 
  20. _beginthread and DosCreateThread both take a "C" function address as a
  21. parameter.
  22.  
  23.    The ThreadPool class is destined to become part of a larger C++ class 
  24. library for OS/2, primarily concerned with the base operating system.
  25. CoralSoft, Inc. is also developing another OS/2 class library which
  26. encapsulates Presentation Manager functions into C++ objects.  If you want
  27. to be notified of availability of these class libraries, please contact
  28. Steve Horne by one of the following:
  29.  
  30. - OS/2 Shareware BBS - (703) 385-4325
  31.  
  32. - Compuserve User ID 71316,1603
  33.  
  34. - US Mail:
  35.   CoralSoft, Inc.
  36.   ATTN: Steve Horne
  37.   305 Judson Dr. E.
  38.   Mobile, AL  36608-3007
  39.  
  40.   (205) 344-2251
  41.  
  42. ---------------------------------------------------------------------------
  43.    The files included in this ZIP file are:
  44.  
  45.    THRDPOOL.DOC - Which you are reading now.
  46.    THRDPOOL.OBJ - The ThreadPool class object file.  This may be explicitly
  47.                   linked with your application, or may be added to an
  48.                   object library.
  49.    THRDTEST.CPP - A test program for the ThreadPool class.
  50.    THRDTEST.EXE - A pre-built executable for the test program.
  51.    MAKEFILE     - Makefile for creating THRDTEST.EXE
  52.  
  53.    Note that the THRDPOOL.OBJ file was created with the LARGE model for
  54. Zortech C++ V3.0.  The THRDTEST.CPP program uses the Zortech display package
  55. for screen output.  Release versions of CoralSoft's class libraries will
  56. supply SMALL and LARGE libraries for Zortech C++ and Borland C++.
  57. To compile properly, you must have the Zortech Libraries for
  58. Version 3.0, Release 3, which made multi-tasking actually usable.
  59. If you don't have this latest release, contact Symantec for an upgrade.
  60. ---------------------------------------------------------------------------
  61.    To use the ThreadPool class in your application, you must include the
  62. header file THRDPOOL.HPP.
  63.  
  64.    The user interface to ThreadPool is documented as follows:
  65.  
  66. ---------------------------------------------------------------------------
  67. CONSTRUCTOR:
  68.  
  69. ThreadPool(int count, USHORT stack = 2048);
  70.  
  71.    Parameters:
  72.       int count - This parameter specifies the number of threads to start
  73.                   for the pool.  It should be the maximum number of 
  74.                   simultaneously executing threads your application will
  75.                   need.
  76.       USHORT stack - This parameter specifies the stack size for each thread.
  77.                   The default value is 2048 bytes.  With the current imple-
  78.                   mentation, all threads created must have the same stack
  79.                   size.  Threads will be created with a minimum of 2048 if
  80.                   a smaller value is specified.
  81.  
  82. Note that under normal circumstances, only one instance of the TreadPool
  83. object is needed per application.
  84.  
  85. ---------------------------------------------------------------------------
  86. MEMBER FUNCTIONS:
  87.  
  88. USHORT start(void (*func)(PVOID), PVOID arg = NULL, HSEM notify = NULL);
  89.  
  90.    Parameters:
  91.       void (*func)(PVOID) - This is the C++ function for multi-threaded
  92.                   execution.  This function returns void, and takes a
  93.                   single PVOID argument.  
  94.       PVOID arg - This is a PVOID (pointer to VOID) that specifies the
  95.                   argument to be passed to func.  Typically, applications 
  96.                   pass a pointer to a structure as the argument.  The 
  97.                   structure must contain all the information the thread 
  98.                   needs for proper operation.  If the thread needs no
  99.                   arguments, this parameter may be omitted.
  100.       HSEM notify - This is either a system semaphore handle or the address
  101.                   of a RAM semaphore to be cleared when the thread has
  102.                   terminated execution.  If no termination notification is
  103.                   desired, this parameter may be omitted.
  104.  
  105.    Returns:
  106.       This function will return zero for no error, or a status code as
  107.       documented below.
  108. ---------------------------------------------------------------------------
  109. USHORT error(void);
  110.  
  111.    Parameters:  none
  112.  
  113.    Returns:
  114.       The function returns the status code from the last ThreadPool
  115.       operation, as documented below.
  116.  
  117. ---------------------------------------------------------------------------
  118. void killAll(void);
  119.  
  120.    Parameters:  none
  121.  
  122.    Returns: none
  123.  
  124.       Normally, the object destructor will clean up the thread pool and 
  125.       terminate the threads in an orderly manner.  The ThreadPool destructor
  126.       can only terminate idle threads, that is threads not busy executing
  127.       a user function.  Use the killAll() function to immediately stop all
  128.       threads, even those currently executing user functions.  This function
  129.       uses the DosKillProcess API call.
  130.  
  131. ---------------------------------------------------------------------------
  132. STATUS CODES:
  133.    TP_OK - Normal status code (0)
  134.    TP_NOTHREADS - All threads in the pool are busy.  Either try again later,
  135.       or modify the application to create more threads in the pool.
  136.    TP_NOMEMORY - Insufficient memory for some operation.
  137.  
  138. ---------------------------------------------------------------------------
  139.  
  140.    Please note that this code is supplied as a BETA version of the class
  141. implementation.  You may use it in any manner as you see fit... however,
  142. some feedback on its usefulness, stability, or any other comments are
  143. greatly appreciated.
  144.  
  145.