home *** CD-ROM | disk | FTP | other *** search
/ Chip 1997 October / Chip_1997-10_cd.bin / tema / sybase / powerj / hpp.z / WTHREAD.HPP < prev    next >
C/C++ Source or Header  |  1997-01-22  |  16KB  |  509 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 );   // blocks processing
  216.         WBool Wait( WDWord timeout, 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.         // FreeThreadData
  334.         //
  335.         //    Frees any private (per-thread) data that might have been
  336.         //    allocated for this thread by the class library.
  337.  
  338.         static void FreeThreadData();
  339.  
  340.         // InstallFilter
  341.         //
  342.         //    Installs a message filter.  User-installed filters
  343.         //    should have a priority > WFP_SYSTEM.
  344.  
  345.         #define WFP_USER    64
  346.         #define WFP_SYSTEM  32
  347.         #define WFP_DEFAULT  0
  348.  
  349.         static WBool InstallFilter( WObject *object,
  350.                                     WMessageFilter filter,
  351.                                     void *userData=NULL,
  352.                                     WULong priority=WFP_USER,
  353.                                     WBool asHookFilter=TRUE );
  354.         static WBool InstallFilter( WStaticMessageFilter filter,
  355.                                     void *userData=NULL,
  356.                                     WULong priority=WFP_USER,
  357.                                     WBool asHookFilter=TRUE );
  358.  
  359.         // PostMessage
  360.         //
  361.         //    Posts a message for the current thread.  Returns TRUE
  362.         //    if the message was posted.
  363.  
  364.         static WBool PostMessage( const WMessage & message );
  365.  
  366.         // PostQuitMessage
  367.         //
  368.         //    Posts a WM_QUIT message to the current thread,
  369.         //    which will then cause a future FetchMessage
  370.         //    to return 0.
  371.  
  372.         static WBool PostQuitMessage( WInt exitCode=0 );
  373.  
  374.         // ProcessMessages
  375.         //
  376.         //    Enters a loop calling FetchMessage/DispatchMessage
  377.         //    until FetchMessage returns FALSE (WM_QUIT) or an
  378.         //    error occurs.  Returns TRUE if successful, FALSE
  379.         //    otherwise.  Optional WMessage value returns the
  380.         //    last message processed.
  381.  
  382.         static WBool ProcessMessages( WMessage * lastMessage=NULL );
  383.  
  384.         // RemoveFilter
  385.         //
  386.         //    Remove a filter that was installed using InstallFilter.
  387.         ///   Returns TRUE if a filter was found and removed.
  388.  
  389.         static WBool RemoveFilter( WObject *object,
  390.                                    WMessageFilter filter,
  391.                                    WBool fromHook=TRUE );
  392.         static WBool RemoveFilter( WStaticMessageFilter filter,
  393.                                    WBool fromHook=TRUE );
  394.  
  395.         // Sleep
  396.         //
  397.         //    Sleeps for the given number of milliseconds, or
  398.         //    forever if time=0xffffffff.  If time=0 then the
  399.         //    thread merely gives up its time slice.
  400.  
  401.         static WBool Sleep( WDWord time );
  402.  
  403.         // WaitForMessage
  404.         //
  405.         //    Waits until a message arrives in the queue.
  406.  
  407.         static void WaitForMessage();
  408.  
  409.         /***********************************************************
  410.          * Other
  411.          ***********************************************************/
  412.  
  413.         virtual WThreadHandle GetHandle() const;
  414.  
  415.         virtual WDWord GetID() const;
  416. };
  417.  
  418.  
  419. //
  420. // WThread -- Represents an arbitrary thread.
  421. //
  422.  
  423. class WCMCLASS WThread : public WThreadBase {
  424.     WDeclareSubclass( WThread, WThreadBase );
  425.  
  426.     public:
  427.  
  428.         /***********************************************************
  429.          * Constructors
  430.          ***********************************************************/
  431.  
  432.         WThread();
  433.         WThread( WThreadHandle handle, WDWord threadId,
  434.                  WBool closeIt=TRUE, WBool makeCopy=FALSE );
  435.         WThread( const WThread & thd );
  436.         WThread( const WCurrentThread & curr );
  437.  
  438.         ~WThread(); // does not terminate thread!
  439.  
  440.         /***********************************************************
  441.          * Operators
  442.          ***********************************************************/
  443.  
  444.         WThread& operator=( const WThread & thd );
  445.         WThread& operator=( const WCurrentThread & thd );
  446.  
  447.         /***********************************************************
  448.          * Properties
  449.          ***********************************************************/
  450.  
  451.         /***********************************************************
  452.          * Methods
  453.          ***********************************************************/
  454.  
  455.         // Clear
  456.         //
  457.         //    Resets the object, closing the low-level kernel
  458.         //    handle if no one else is referencing the thread.
  459.  
  460.         void Clear();
  461.  
  462.         // Create
  463.         //
  464.         //    Resets the object, then creates a new thread.
  465.  
  466.         WBool Create( WObject *object, WThreadRoutine handler,
  467.                       void *userData=NULL,
  468.                       WBool createSuspended=FALSE,
  469.                       WULong stackSize=0 );
  470.  
  471.         WBool Create( WStaticThreadRoutine handler,
  472.                       void *userData=NULL,
  473.                       WBool createSuspended=FALSE,
  474.                       WULong stackSize=0 );
  475.  
  476.         // PostMessage
  477.         //
  478.         //    Posts a message for the current thread.  Returns TRUE
  479.         //    if the message was posted.
  480.  
  481.         WBool PostMessage( const WMessage & message ) const;
  482.  
  483.         // PostQuitMessage
  484.         //
  485.         //    Posts a WM_QUIT message to the given thread,
  486.         //    which will then cause a future FetchMessage
  487.         //    to return 0.
  488.  
  489.         WBool PostQuitMessage( WInt exitCode=0 ) const;
  490.  
  491.         /***********************************************************
  492.          * Other
  493.          ***********************************************************/
  494.  
  495.         virtual WThreadHandle GetHandle() const;
  496.  
  497.         virtual WDWord GetID() const;
  498.  
  499.     private:
  500.         WThreadReference *_threadRef;
  501. };
  502.  
  503. #ifndef _WNO_PRAGMA_PUSH
  504. #pragma enum pop;
  505. #pragma pack(pop);
  506. #endif
  507.  
  508. #endif // _WTHREAD_HPP_INCLUDED
  509.