home *** CD-ROM | disk | FTP | other *** search
/ io Programmo 10 / ioProg_10.iso / soft / optima / hpp.z / WTHREAD.HPP < prev    next >
Encoding:
C/C++ Source or Header  |  1996-04-09  |  14.7 KB  |  494 lines
  1.  
  2. /********************************************************************
  3.  *
  4.  * Threads
  5.  *
  6.  *    Two classes are available:
  7.  *
  8.  *       WCurrentThread -- Always refers to the current thread.
  9.  *
  10.  *       WThread -- Refers to a specific thread in the process.
  11.  *
  12.  *    If you want to do something related to the current thread,
  13.  *    use an object of type WCurrentThread.  Otherwise you need
  14.  *    an object of class WThread, which can only be had in the
  15.  *    following manner:
  16.  *
  17.  *      1) Call the Create method.
  18.  *
  19.  *      2) Assignment from another WThread.
  20.  *
  21.  *      3) Assignment from a WCurrentThread.  (This makes a WThread
  22.  *         object which can then be used in other threads to refer
  23.  *         to the current thread.)
  24.  *
  25.  ********************************************************************/
  26.  
  27. #ifndef _WTHREAD_HPP_INCLUDED
  28. #define _WTHREAD_HPP_INCLUDED
  29.  
  30. #ifndef _WNO_PRAGMA_PUSH
  31. #pragma pack(push,4);
  32. #pragma enum int;
  33. #endif
  34.  
  35. #ifndef _WDEF_HPP_INCLUDED
  36. #  include "wdef.hpp"
  37. #endif
  38. #ifndef _WOBJECT_HPP_INCLUDED
  39. #  include "wobject.hpp"
  40. #endif
  41. #ifndef _WSEMAPHORE_HPP_INCLUDED
  42. #  include "wsemaphr.hpp"
  43. #endif
  44. #ifndef _WMESSAGE_HPP_INCLUDED
  45. #  include "wmessage.hpp"
  46. #endif
  47.  
  48. #undef PostMessage
  49. #undef DispatchMessage
  50. #if defined( _UNICODE )
  51.     #define PostMessage         PostMessageW
  52.     #define DispatchMessage     DispatchMessageW
  53. #else
  54.     #define PostMessage         PostMessageA
  55.     #define DispatchMessage     DispatchMessageA
  56. #endif
  57.  
  58. class WThread;
  59. class WProcess;
  60. class WThreadReference;
  61. class WFilterEntry;
  62.  
  63. enum WThreadHandle { NULLHTHREAD = 0, LASTHTHREAD = LAST_16TO32BIT };
  64.  
  65. //
  66. // Thread callback functions.  You can call back to either a
  67. // static function or a member function.
  68. //
  69.  
  70. typedef WDWord WCMDEF (*WStaticThreadRoutine)( void *userData );
  71. typedef WDWord WCMDEF (WObject::*WThreadRoutine)( void *userData );
  72.  
  73. //
  74. // Message filter callback functions.
  75. //
  76.  
  77. struct WMessageFilterData {
  78.     WMessage      message;
  79.     WULong        filterCode;
  80.     void         *userData;
  81.     void         *reserved1;     // Reserved for internal use
  82.     void         *reserved2;     // Reserved for internal use
  83. };
  84.  
  85. typedef WBool WCMDEF (*WStaticMessageFilter)( WMessageFilterData *data );
  86. typedef WBool WCMDEF (WObject::*WMessageFilter)( WMessageFilterData *data );
  87.  
  88. // Thread priority...
  89.  
  90. enum WThreadPriority {
  91.  
  92.     WThreadPriorityFirst,
  93.  
  94.     WThreadPriorityLowest = WThreadPriorityFirst,
  95.     WThreadPriorityIdle,
  96.     WThreadPriorityBelowNormal,
  97.     WThreadPriorityNormal,
  98.     WThreadPriorityAboveNormal,
  99.     WThreadPriorityTimeCritical,
  100.     WThreadPriorityHighest,
  101.  
  102.     WThreadPriorityLast = WThreadPriorityHighest,
  103.     WThreadPriorityError
  104. };
  105.  
  106. //
  107. // WThreadBase -- An abstract base class.
  108. //
  109.  
  110. class WCMCLASS WThreadBase : public WObject {
  111.     WDeclareSubclass( WThreadBase, WObject );
  112.  
  113.         /***********************************************************
  114.          * Constructors
  115.          ***********************************************************/
  116.  
  117.     private:
  118.         WThreadBase& operator=( const WThreadBase & );
  119.         WThreadBase( const WThreadBase & );
  120.  
  121.     protected:
  122.         WThreadBase();
  123.  
  124.     public:
  125.         ~WThreadBase();
  126.  
  127.         /***********************************************************
  128.          * Properties
  129.          ***********************************************************/
  130.  
  131.     public:
  132.  
  133.         // Active
  134.         //
  135.         //    TRUE if the thread is still running.
  136.  
  137.         WBool GetActive() const;
  138.  
  139.         // ExitCode
  140.         //
  141.         //    Returns the exit code for the thread.  If the thread
  142.         //    is still active the result is undefined.
  143.  
  144.         WDWord GetExitCode() const;
  145.  
  146.         // Handle
  147.         //
  148.         //    Returns the thread handle.
  149.  
  150.         virtual WThreadHandle GetHandle() const = 0;
  151.  
  152.         // ID
  153.         //
  154.         //    Returns the thread ID.
  155.  
  156.         virtual WDWord GetID() const = 0;
  157.  
  158.         // Priority
  159.         //
  160.         //    Set/get the thread priority.
  161.  
  162.         WThreadPriority GetPriority() const;
  163.         WBool           SetPriority( WThreadPriority priority );
  164.  
  165.         // Valid
  166.         //
  167.         //    TRUE if the thread represents (or represented)
  168.         //    a valid thread.
  169.  
  170.         WBool GetValid() const;
  171.  
  172.         /***********************************************************
  173.          * Methods
  174.          ***********************************************************/
  175.  
  176.         // AttachInputTo
  177.         //
  178.         //    Synchronizes the thread's input status with another
  179.         //    thread.
  180.  
  181.         WBool AttachInputTo( WDWord threadID );
  182.  
  183.         // DetachInputFrom
  184.         //
  185.         //    Detaches the thread from another thread.
  186.  
  187.         WBool DetachInputFrom( WDWord threadID );
  188.  
  189.         // Resume
  190.         //
  191.         //    Let a thread resume after it has been suspended.
  192.  
  193.         WBool Resume();
  194.  
  195.         // Suspend
  196.         //
  197.         //    Suspend a thread.
  198.  
  199.         WBool Suspend();
  200.  
  201.         // Terminate
  202.  
  203.         WBool Terminate( WDWord exitCode=0 );
  204.  
  205.         // Wait
  206.         //
  207.         //    Wait for the thread to terminate, with a timeout in
  208.         //    milliseconds.  By default the timeout is infinite.
  209.         //    If blockMessageProcessing is TRUE, then no messages will be
  210.         //    responded to by this thread until the call to Wait() finishes.
  211.  
  212.         WBool Wait();  // 0xFFFFFFFF, TRUE
  213.         WBool Wait( WDWord timeout,
  214.                     WBool blockMessageProcessing );
  215. };
  216.  
  217. //
  218. // WCurrentThread -- Represents the currently-running thread.
  219. //
  220.  
  221. class WCMCLASS WCurrentThread : public WThreadBase {
  222.     WDeclareSubclass( WCurrentThread, WThreadBase );
  223.  
  224.     public:
  225.  
  226.         /***********************************************************
  227.          * Constructors and Destructors
  228.          ***********************************************************/
  229.  
  230.         WCurrentThread();
  231.         WCurrentThread( const WCurrentThread & thd );
  232.  
  233.         ~WCurrentThread(); // does not terminate thread!
  234.  
  235.         /***********************************************************
  236.          * Operators
  237.          ***********************************************************/
  238.  
  239.         WCurrentThread& operator=( const WCurrentThread & thd );
  240.  
  241.         /***********************************************************
  242.          * Properties
  243.          ***********************************************************/
  244.  
  245.         // ErrorCode
  246.         //
  247.         //    Per-thread error code.
  248.  
  249.         static WDWord GetErrorCode();
  250.         static WBool  SetErrorCode( WDWord errCode );
  251.  
  252.         // ErrorMessage
  253.         //
  254.         //    Per-thread error message.  If the give error code is 0,
  255.         //    uses the value of the ErrorCode property.  If no error,
  256.         //    an empty string is returned.
  257.  
  258.         static WString GetErrorMessage( WDWord errCode=0 );
  259.         static WBool   GetErrorMessage( WString & str, WDWord errCode=0 );
  260.  
  261.         // Name
  262.         //
  263.         //    Per-thread user-settable name (for debugging).
  264.  
  265.         static WString GetName();
  266.         static WBool   SetName( const WString & name );
  267.  
  268.         // UserData
  269.         //
  270.         //    Per-thread userdata.
  271.  
  272.         static void *GetUserData();
  273.         static WBool SetUserData( void *userData );
  274.  
  275.         /***********************************************************
  276.          * Methods
  277.          ***********************************************************/
  278.  
  279.         // CallFilter
  280.         //
  281.         //    Calls the chain of message filters.  Returns TRUE
  282.         //    if the message was processed and should not be
  283.         //    dispatched.  This function can also be used within
  284.         //    a filter to call the next filter in the chain by
  285.         //    passing in a non-NULL data value.
  286.  
  287.         #define WFILTER_REMOVE 0
  288.         #define WFILTER_PEEK   1
  289.  
  290.         static WBool CallFilter( WMessage & message,
  291.                                  WULong filterCode=WFILTER_REMOVE,
  292.                                  WMessageFilterData *data=NULL );
  293.  
  294.         // Create
  295.         //
  296.         //    Creates a new thread and returns the thread object.
  297.  
  298.         static WThread Create( WObject *object, WThreadRoutine handler,
  299.                                void *userData=NULL,
  300.                                WBool createSuspended=FALSE,
  301.                                WULong stackSize=0 );
  302.  
  303.         static WThread Create( WStaticThreadRoutine handler,
  304.                                void *userData=NULL,
  305.                                WBool createSuspended=FALSE,
  306.                                WULong stackSize=0 );
  307.  
  308.         // DispatchMessage
  309.         //
  310.         //    Translates and dispatches a low-level window message.
  311.  
  312.         static void DispatchMessage( const WMessage & message );
  313.  
  314.         // FetchMessage
  315.         //
  316.         //    Returns the next message from the queue.  Returns 1
  317.         //    if a message was retrieved and the message was not
  318.         //    a WM_QUIT, 0 if a message was retrieved and it was
  319.         //    a WM_QUIT, and -1 if an error occurred.  
  320.  
  321.         static WInt FetchMessage( WMessage & message,
  322.                                   WBool waitForMessage=TRUE,
  323.                                   WBool removeMessage=TRUE,
  324.                                   WWindowHandle rootWindow=NULLHWND,
  325.                                   WULong firstMessage=0,
  326.                                   WULong lastMessage=0,
  327.                                   WBool filter=TRUE );
  328.  
  329.         // InstallFilter
  330.         //
  331.         //    Installs a message filter.  User-installed filters
  332.         //    should have a priority > WFP_SYSTEM.
  333.  
  334.         #define WFP_USER    64
  335.         #define WFP_SYSTEM  32
  336.         #define WFP_DEFAULT  0
  337.  
  338.         static WBool InstallFilter( WObject *object,
  339.                                     WMessageFilter filter,
  340.                                     void *userData=NULL,
  341.                                     WULong priority=WFP_USER );
  342.         static WBool InstallFilter( WStaticMessageFilter filter,
  343.                                     void *userData=NULL,
  344.                                     WULong priority=WFP_USER );
  345.  
  346.         // PostMessage
  347.         //
  348.         //    Posts a message for the current thread.  Returns TRUE
  349.         //    if the message was posted.
  350.  
  351.         static WBool PostMessage( const WMessage & message );
  352.  
  353.         // PostQuitMessage
  354.         //
  355.         //    Posts a WM_QUIT message to the current thread,
  356.         //    which will then cause a future FetchMessage
  357.         //    to return 0.
  358.  
  359.         static WBool PostQuitMessage( WInt exitCode=0 );
  360.  
  361.         // ProcessMessages
  362.         //
  363.         //    Enters a loop calling FetchMessage/DispatchMessage
  364.         //    until FetchMessage returns FALSE (WM_QUIT) or an
  365.         //    error occurs.  Returns TRUE if successful, FALSE
  366.         //    otherwise.  Optional WMessage value returns the
  367.         //    last message processed.
  368.  
  369.         static WBool ProcessMessages( WMessage * lastMessage=NULL );
  370.  
  371.         // RemoveFilter
  372.         //
  373.         //    Remove a filter that was installed using InstallFilter.
  374.         ///   Returns TRUE if a filter was found and removed.
  375.  
  376.         static WBool RemoveFilter( WObject *object,
  377.                                    WMessageFilter filter );
  378.         static WBool RemoveFilter( WStaticMessageFilter filter );
  379.  
  380.         // Sleep
  381.         //
  382.         //    Sleeps for the given number of milliseconds, or
  383.         //    forever if time=0xffffffff.  If time=0 then the
  384.         //    thread merely gives up its time slice.
  385.  
  386.         static WBool Sleep( WDWord time );
  387.  
  388.         // WaitForMessage
  389.         //
  390.         //    Waits until a message arrives in the queue.
  391.  
  392.         static void WaitForMessage();
  393.  
  394.         /***********************************************************
  395.          * Other
  396.          ***********************************************************/
  397.  
  398.         virtual WThreadHandle GetHandle() const;
  399.  
  400.         virtual WDWord GetID() const;
  401. };
  402.  
  403.  
  404. //
  405. // WThread -- Represents an arbitrary thread.
  406. //
  407.  
  408. class WCMCLASS WThread : public WThreadBase {
  409.     WDeclareSubclass( WThread, WThreadBase );
  410.  
  411.     public:
  412.  
  413.         /***********************************************************
  414.          * Constructors
  415.          ***********************************************************/
  416.  
  417.         WThread();
  418.         WThread( WThreadHandle handle, WDWord threadId,
  419.                  WBool closeIt=TRUE, WBool makeCopy=FALSE );
  420.         WThread( const WThread & thd );
  421.         WThread( const WCurrentThread & curr );
  422.  
  423.         ~WThread(); // does not terminate thread!
  424.  
  425.         /***********************************************************
  426.          * Operators
  427.          ***********************************************************/
  428.  
  429.         WThread& operator=( const WThread & thd );
  430.         WThread& operator=( const WCurrentThread & thd );
  431.  
  432.         /***********************************************************
  433.          * Properties
  434.          ***********************************************************/
  435.  
  436.         /***********************************************************
  437.          * Methods
  438.          ***********************************************************/
  439.  
  440.         // Clear
  441.         //
  442.         //    Resets the object, closing the low-level kernel
  443.         //    handle if no one else is referencing the thread.
  444.  
  445.         void Clear();
  446.  
  447.         // Create
  448.         //
  449.         //    Resets the object, then creates a new thread.
  450.  
  451.         WBool Create( WObject *object, WThreadRoutine handler,
  452.                       void *userData=NULL,
  453.                       WBool createSuspended=FALSE,
  454.                       WULong stackSize=0 );
  455.  
  456.         WBool Create( WStaticThreadRoutine handler,
  457.                       void *userData=NULL,
  458.                       WBool createSuspended=FALSE,
  459.                       WULong stackSize=0 );
  460.  
  461.         // PostMessage
  462.         //
  463.         //    Posts a message for the current thread.  Returns TRUE
  464.         //    if the message was posted.
  465.  
  466.         WBool PostMessage( const WMessage & message ) const;
  467.  
  468.         // PostQuitMessage
  469.         //
  470.         //    Posts a WM_QUIT message to the given thread,
  471.         //    which will then cause a future FetchMessage
  472.         //    to return 0.
  473.  
  474.         WBool PostQuitMessage( WInt exitCode=0 ) const;
  475.  
  476.         /***********************************************************
  477.          * Other
  478.          ***********************************************************/
  479.  
  480.         virtual WThreadHandle GetHandle() const;
  481.  
  482.         virtual WDWord GetID() const;
  483.  
  484.     private:
  485.         WThreadReference *_threadRef;
  486. };
  487.  
  488. #ifndef _WNO_PRAGMA_PUSH
  489. #pragma enum pop;
  490. #pragma pack(pop);
  491. #endif
  492.  
  493. #endif // _WTHREAD_HPP_INCLUDED
  494.