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