home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional Developers Kit 1992 November / Disc01 / Disc01.mdf / cppbeta / ibmcli / ithread.hp_ / ITHREAD.HPP
Encoding:
C/C++ Source or Header  |  1992-10-27  |  14.9 KB  |  482 lines
  1. /*==============================================================================
  2.  Module Name: ithread.hpp
  3.  
  4.  Description: 
  5.    Declaration of the class IThread; objects of this class manage
  6.    OS/2 execution threads.
  7.  
  8.  Copyright: (C) Copyright IBM Corporation 1992
  9.             All Rights Reserved
  10.             Licensed Materials = Property of IBM
  11.  
  12.  Usage:
  13.    This file is #include-d in code requiring access to the IThread
  14.    functions.
  15.  
  16.  Notes:
  17.  
  18.  Related Topics:
  19.  
  20.  History:
  21.    flag yymmdd who description
  22.    ---- ------ --- -----------------------------------------------------------
  23.         920726 law Initial
  24.         920914 law Restructure code
  25. ==============================================================================*/
  26. #if !defined( _ITHREAD_ )
  27. #define _ITHREAD_
  28.  
  29. #if !defined( _IBASETYP_ )
  30.   #include <ibasetyp.hpp>
  31. #endif
  32.  
  33. #if !defined( _IREFCNT_ )
  34.   #include <irefcnt.hpp>
  35. #endif
  36.  
  37. #if !defined( _IHANDLE_ )
  38.   #include <ihandle.hpp>
  39. #endif
  40.  
  41. /*------------------------------------------------------------------------------
  42.  Class Name: IThreadFn
  43.  
  44.  Description:
  45.    Abstract "thread function" class.
  46.  
  47.  Usage:
  48.    Objects of this class are used to represent "functions" to be
  49.    dispatched on secondary threads of execution when an IThread is
  50.    started.  These objects are reference counted to manage their
  51.    destruction (after the thread has terminated); a reference to
  52.    such an IThreadFn is passed to IThread::start().
  53.  
  54.    Typical usage is like:
  55.      class MyFunction : public IThreadFn {
  56.      public:
  57.      virtual void
  58.        run ( ) const
  59.        {
  60.        // Place your code here.
  61.        }
  62.      };
  63.      ...
  64.      IThread newThread( new MyFunction );
  65.  
  66.    See IThread::start for details on usage of this class.
  67. ------------------------------------------------------------------------------*/
  68. class IThreadFn : public IRefCounted {
  69. public:
  70. virtual void
  71.   run ( ) const = 0;
  72. }; // class IThreadFn
  73.  
  74. /*------------------------------------------------------------------------------
  75.  Class Name: IThreadMemberFn
  76.  
  77.  Description:
  78.    Template for IThreadMemberFn class (IThreadFn subclass to dispatch
  79.    C++ member function against an object).
  80.  
  81.  Usage:
  82.    Instances of this class are used to dispatch C++ member functions
  83.    on a separate thread.  The template argument is the class of the
  84.    object for which the function is called.  The constructor for such
  85.    objects requires a reference to the object the member function is
  86.    to be applied to, and, a pointer to the member function.  
  87.  
  88.    The member function returns void and accepts no arguments.  Support
  89.    for other member functions can be added by subclassing this class.
  90.  
  91.    Typical usage:
  92.      class MyClass {
  93.      public:
  94.      void job()
  95.        {
  96.        // Code to run on separate thread.
  97.        }
  98.      };
  99.      ...
  100.      MyClass myObj;
  101.      IThread thread;
  102.      thread.start( new IThreadMemberFn<MyClass>( myObj, MyClass::job ) );
  103. ------------------------------------------------------------------------------*/
  104. template < class T >
  105. class IThreadMemberFn : public IThreadFn {
  106. public:
  107. IThreadMemberFn ( T &obj,
  108.                   void ( T :: *mem )( ) )
  109.   : member( mem ), object( obj )
  110.   {
  111.   }
  112. virtual void
  113.   run ( ) const
  114.   {
  115.   (object.*member)();
  116.   }
  117. protected:
  118. T
  119.   &object;
  120. void ( T ::
  121.  *member )( );
  122. }; // IThreadMemberFn
  123.  
  124. /*------------------------------------------------------------------------------
  125.  Class Name: IPriority
  126.  
  127.  Description:
  128.    Thread "priority" class.
  129.  
  130.  Usage:
  131.    This class defines the input and output of the IThread "priority"
  132.    setting/querying member functions.
  133. ------------------------------------------------------------------------------*/
  134. class IPriority {
  135.  
  136. public:
  137.  
  138. typedef enum
  139.   {
  140.   noChange         = 0,
  141.   idleTime         = 1,
  142.   regular          = 2,
  143.   timeCritical     = 3,
  144.   foregroundServer = 4
  145.   } Class;
  146.  
  147. IPriority ( Class aClass,
  148.             long  aDelta = 0 )
  149.   : c( aClass ), d( aDelta )
  150.   {}
  151.  
  152. IPriority ( long aDelta )
  153.   : c( noChange ), d( aDelta )
  154.   {}
  155.  
  156. Class 
  157.   cls ( ) const
  158.   {
  159.   return this->c;
  160.   }
  161.  
  162. long
  163.   delta ( ) const
  164.   {
  165.   return this->d;
  166.   }
  167.  
  168. protected:
  169.  
  170. Class
  171.   c;
  172.  
  173. long
  174.   d;
  175. }; // IPriority 
  176.  
  177. class IStartedThread;
  178.  
  179. class ICurrentThread;
  180.  
  181. /*------------------------------------------------------------------------------
  182.  Class Name: IThread
  183.  
  184.  Description:
  185.    Objects of this class represent threads of execution within the current
  186.    program.
  187.  
  188.  Usage:
  189.    This class provides support for implementing multi-threaded programs.
  190.    IThread objects pr/ovide access to all the "tasking" APIs of the
  191.    operating system.  In addition, these objects serve as the anchor for
  192.    thread-specific information (for example, the Presentation Manager
  193.    anchor block).
  194.  
  195.    IThread objects are generally used in one of three ways:
  196.  
  197.      1. To apply thread functions to the current thread.  In most cases,
  198.         these functions will be applied to the IThread object reference
  199.         returned by the static member IThread::current.
  200.  
  201.      2. To create additional threads of execution by instantiating new
  202.         IThread objects and "starting" them.
  203.  
  204.      3. To manipulate threads of execution initiated via alternate
  205.         means and of which only the thread's ID is known.
  206.  
  207.  Example:
  208.    // This is typical code appearing in main():
  209.    IThread::current.initializePM(); // Initialize PM environment.
  210.    ...// Create windows.
  211.    IThread::current.processMsgs();  // Process window messages.
  212.    IThread::current.terminatePM();  // Terminate PM environment.
  213.  
  214.    // This is typical code to spawn a new thread to execute
  215.    // member function foo() against the "this" object:
  216.    IThread thread;
  217.    thread.start( IThreadMemberFn< MyClass >( this, foo ) );
  218.  
  219.    // This is typical code that operates on a thread with ID tid:
  220.    IThread thread( tid );
  221.    thread.suspend();
  222.    ...
  223.    thread.resume();
  224. ------------------------------------------------------------------------------*/
  225. class IThread {
  226.  
  227. public:
  228.  
  229. friend class ICurrentThread;
  230.  
  231. typedef void ( _Optlink *OptlinkFnPtr ) ( void * );
  232. typedef void ( _System  *SystemFnPtr  ) ( unsigned long );
  233.  
  234. /*---------------------------- Instance Creation -------------------------------
  235.  
  236.   There are 3 types of IThread constructors:
  237.  
  238.     1. default
  239.  
  240.        The default ctor is used to build an IThread to be subsequently
  241.        started via the start() member function.
  242.  
  243.     2. with specification of code to run
  244.  
  245.        These are used to construct a new IThread and immediately
  246.        dispatch it.  These forms of the ctor are equivalent to
  247.        constructing via the default ctor and then dispatching the
  248.        thread via start().
  249.  
  250.     3. from the thread ID of a previously started thread
  251.  
  252.        This ctor is used to provide IThread functionality to threads
  253.        created via alternate means (either via _beginthread() or via
  254.        DosCreateThread()).
  255.  
  256.   The second type permits specification of whether or not the new
  257.   thread is to be a "PM" thread.  If so, then initializePM is called
  258.   automatically after the thread is started.
  259. ------------------------------------------------------------------------------*/
  260. IThread ( );
  261. IThread ( IThreadID anID );
  262. IThread ( const IReference<IThreadFn> &aFnObjRef,
  263.           Boolean          autoInitPM = IThread::defaultAutoInitPM() );
  264. IThread ( OptlinkFnPtr     pfn,
  265.           void            *anArg,
  266.           Boolean          autoInitPM = IThread::defaultAutoInitPM() );
  267. IThread ( SystemFnPtr      pfn,
  268.           unsigned long    anArg,
  269.           Boolean          autoInitPM = IThread::defaultAutoInitPM() );
  270.  
  271. /*---------------------------- Instance Deletion -------------------------------
  272.  
  273.   IThread has a virtual destructor that takes care of deallocating
  274.   resources.  The destructor does not stop the thread!
  275. ------------------------------------------------------------------------------*/
  276. virtual
  277.   ~IThread ( );
  278.  
  279. /*------------------------------ Current Thread --------------------------------
  280.  
  281.   The static member "current" provides a reference to the object of class
  282.   ICurrentThread that provides access to the current thread, and, provides
  283.   additional functionality that can only be applied to the current thread.
  284. ------------------------------------------------------------------------------*/
  285. static ICurrentThread
  286.  ¤t;
  287.  
  288. /*------------------------------ Starting/Stopping -----------------------------
  289.  
  290.   These functions enable the starting and stopping of threads:
  291.     start    - start an asynchronous thread; threads can be started via
  292.                any of three means:
  293.                  o with an arbitrary IThreadFn
  294.                    The IThreadFn is passed in via an IReference so that
  295.                    the IThreadFn can be deleted (if necessary) when the
  296.                    thread terminates.
  297.                  o with an Optlink function and void* argument
  298.                    This is to provide support for functions otherwise
  299.                    startable via _beginthread().
  300.                  o with a System function and unsigned long argument
  301.                    This is to provide support for functions otherwise
  302.                    startable via DosCreateThread().
  303.     stop     - stop the thread
  304.     suspend  - suspend the thread's execution
  305.     resume   - resume thread execution
  306. ------------------------------------------------------------------------------*/
  307. virtual void
  308.   start   ( const IReference<IThreadFn> &aFnObjRef,
  309.             Boolean        autoInitPM = IThread::defaultAutoInitPM() ),
  310.   start   ( OptlinkFnPtr   pfn,
  311.             void          *anArg,
  312.             Boolean        autoInitPM = IThread::defaultAutoInitPM() ),
  313.   start   ( SystemFnPtr    pfn,
  314.             unsigned long  anArg,
  315.             Boolean        autoInitPM = IThread::defaultAutoInitPM() ),
  316.   stop    ( ),
  317.   suspend ( ),
  318.   resume  ( );
  319.  
  320. /*-------------------------------- Accessing -----------------------------------
  321.  
  322.   These functions provide means of getting and setting the various thread
  323.   attributes:
  324.     id                  - obtain the ID of the thread (0 indicates the 
  325.                           thread is not started)
  326.     anchorBlock         - obtain the anchor block handle for the 
  327.                           thread (0 if not "initialized")
  328.     msgQueue            - obtain the message queue handle for the 
  329.                           thread (0 if not "initialized")
  330.     stackSize           - obtain thread stack size (in bytes)
  331.     setStackSize        - set thread stack size (in bytes); if the thread
  332.                           is started, then this value will take effect
  333.                           only if the thread is stopped and restarted
  334.     defaultStackSize    - obtain the default stack size (the value used
  335.                           by default for new IThreads)
  336.     setDefaultStackSize - set the default stack size
  337.     autoInitPM          - obtain the setting of the "automatically initialize
  338.                           PM" flag for this thread
  339.     setAutoInitPM       - set "automatically initialize PM" flag for this
  340.                           thread
  341.     defaultAutoInitPM   - obtain the default "auto initialize PM" flag 
  342.     setDefaultAutoInitPM- set the default "auto initialize PM" flag
  343.     priority            - obtain the priority of the thread (class/delta)
  344.     setPriority         - set the priority of the thread
  345.     defaultPriority     - obtain the default priority that will be given to
  346.                           new IThreads
  347.     setDefaultPriority  - set the default priority to be used for new
  348.                           IThreads
  349.  
  350.   The functions that get/set the "default" attribute values are all static
  351.   members.
  352. ------------------------------------------------------------------------------*/
  353. virtual IThreadID
  354.   id ( ) const;
  355.  
  356. virtual IAnchorBlockHandle
  357.   anchorBlock ( ) const;
  358.  
  359. virtual IMsgQueueHandle
  360.   msgQueue ( ) const;
  361.  
  362. virtual unsigned long
  363.   stackSize ( ) const;
  364.  
  365. virtual void
  366.   setStackSize ( unsigned long aSize );
  367.  
  368. static unsigned long
  369.   defaultStackSize ( );
  370.  
  371. static void
  372.   setDefaultStackSize ( unsigned long aSize );
  373.  
  374. virtual Boolean
  375.   autoInitPM ( ) const;
  376.  
  377. virtual void
  378.   setAutoInitPM ( Boolean initFlag );
  379.  
  380. static Boolean
  381.   defaultAutoInitPM ( );
  382.  
  383. static void
  384.   setDefaultAutoInitPM ( Boolean initFlag );
  385.  
  386. virtual IPriority
  387.   priority ( ) const;
  388.  
  389. virtual void
  390.   setPriority( IPriority aPriority );
  391.  
  392. static IPriority
  393.   defaultPriority ( );
  394.  
  395. static void
  396.   setDefaultPriority ( IPriority aPriority );
  397.  
  398. protected:
  399.  
  400. // Pointer to thread implementation object:
  401. IStartedThread
  402.  *thread;
  403.  
  404. // Static members (defaults):
  405. static unsigned long
  406.   dfltStackSize;
  407.  
  408. static Boolean
  409.   dfltAutoInitPM;
  410.  
  411. static IPriority
  412.   dfltPriority;
  413. }; // IThread 
  414.  
  415. /*------------------------------------------------------------------------------
  416.  Class Name: ICurrentThread
  417.  
  418.  Description:
  419.    This class provides additional functions that can only be applied to
  420.    the current thread of execution.
  421.  
  422.  Usage:
  423.    A reference to the sole instance of this class is obtained via the 
  424.    static IThread::current member (and cannot be obtained otherwise).
  425.  
  426.    The resulting object is used to invoke the "thread" APIs that can
  427.    only be applied to the current thread of execution.  Essentially, these
  428.    are the APIs that operate on a per-thread basis but do not accept
  429.    a thread id as argument.
  430. ------------------------------------------------------------------------------*/
  431. class ICurrentThread : public IThread {
  432.  
  433. friend class IThread;
  434.  
  435. public:
  436.  
  437. /*-------------------------------- PM Support ----------------------------------
  438.  
  439.   These functions provide support for performing windowing (PM) activities
  440.   on the current thread:
  441.  
  442.   initializePM - set up PM environment (anchor block and msg queue)
  443.   processMsgs  - get and dispatch PM messages till WM_QUIT is received
  444.   terminatePM  - shut down PM environment
  445. ------------------------------------------------------------------------------*/
  446. virtual void
  447.   initializePM ( long queueSize = 0 ),
  448.   processMsgs  ( ),
  449.   terminatePM  ( );
  450.  
  451. /*-------------------------- Current Thread Function ---------------------------
  452.  
  453.   These functions enable thread operations only applicable to the current
  454.   thread:
  455.  
  456.   sleep - suspend thread for given number of milliseconds
  457.   exit  - terminate current thread with given return value
  458. ------------------------------------------------------------------------------*/
  459. virtual void
  460.   sleep ( unsigned long msecs ),
  461.   exit  ( unsigned long rc    );
  462.  
  463. /*--------------------------------- Accessing ----------------------------------
  464.  
  465.   id - return current thread's ID
  466. ------------------------------------------------------------------------------*/
  467. virtual IThreadID
  468.   id ( ) const;
  469.  
  470. protected:
  471.  
  472. // Protected ctor to prevent object creation.
  473. ICurrentThread ( );
  474.  
  475. // Protected static (and only) instance.
  476. static ICurrentThread
  477.   current;
  478.  
  479. }; // ICurrentThread 
  480.  
  481. #endif /* _ITHREAD_ */
  482.