home *** CD-ROM | disk | FTP | other *** search
/ PC Pro 1998 September / dppcpro0998.iso / Rwc / Sybase / Install.exe / hpp.z / WTHREAD.HPP < prev    next >
Encoding:
C/C++ Source or Header  |  1997-11-25  |  15.3 KB  |  511 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. //
  221. // WCurrentThread -- Represents the currently-running thread.
  222. //
  223.  
  224. class WCMCLASS WCurrentThread : public WThreadBase {
  225.     WDeclareSubclass( WCurrentThread, WThreadBase );
  226.  
  227.     public:
  228.  
  229.         /***********************************************************
  230.          * Constructors and Destructors
  231.          ***********************************************************/
  232.  
  233.         WCurrentThread();
  234.         WCurrentThread( const WCurrentThread & thd );
  235.  
  236.         ~WCurrentThread(); // does not terminate thread!
  237.  
  238.         /***********************************************************
  239.          * Operators
  240.          ***********************************************************/
  241.  
  242.         WCurrentThread& operator=( const WCurrentThread & thd );
  243.  
  244.         /***********************************************************
  245.          * Properties
  246.          ***********************************************************/
  247.  
  248.         // ErrorCode
  249.         //
  250.         //    Per-thread error code.
  251.  
  252.         static WDWord GetErrorCode();
  253.         static WBool  SetErrorCode( WDWord errCode );
  254.  
  255.         // ErrorMessage
  256.         //
  257.         //    Per-thread error message.  If the give error code is 0,
  258.         //    uses the value of the ErrorCode property.  If no error,
  259.         //    an empty string is returned.
  260.  
  261.         static WString GetErrorMessage( WDWord errCode=0 );
  262.         static WBool   GetErrorMessage( WString & str, WDWord errCode=0 );
  263.  
  264.         // Name
  265.         //
  266.         //    Per-thread user-settable name (for debugging).
  267.  
  268.         static WString GetName();
  269.         static WBool   SetName( const WString & name );
  270.  
  271.         // UserData
  272.         //
  273.         //    Per-thread userdata.
  274.  
  275.         static void *GetUserData();
  276.         static WBool SetUserData( void *userData );
  277.  
  278.         /***********************************************************
  279.          * Methods
  280.          ***********************************************************/
  281.  
  282.         // CallFilter
  283.         //
  284.         //    Calls the chain of message filters.  Returns TRUE
  285.         //    if the message was processed and should not be
  286.         //    dispatched.  This function can also be used within
  287.         //    a filter to call the next filter in the chain by
  288.         //    passing in a non-NULL data value.
  289.  
  290.         #define WFILTER_REMOVE 0
  291.         #define WFILTER_PEEK   1
  292.  
  293.         static WBool CallFilter( WMessage & message,
  294.                                  WULong filterCode=WFILTER_REMOVE,
  295.                                  WMessageFilterData *data=NULL,
  296.                                  WBool callHookFilters=TRUE );
  297.  
  298.         // Create
  299.         //
  300.         //    Creates a new thread and returns the thread object.
  301.  
  302.         static WThread Create( WObject *object, WThreadRoutine handler,
  303.                                void *userData=NULL,
  304.                                WBool createSuspended=FALSE,
  305.                                WULong stackSize=0 );
  306.  
  307.         static WThread Create( WStaticThreadRoutine handler,
  308.                                void *userData=NULL,
  309.                                WBool createSuspended=FALSE,
  310.                                WULong stackSize=0 );
  311.  
  312.         // DispatchMessage
  313.         //
  314.         //    Translates and dispatches a low-level window message.
  315.  
  316.         static void DispatchMessage( const WMessage & message );
  317.  
  318.         // FetchMessage
  319.         //
  320.         //    Returns the next message from the queue.  Returns 1
  321.         //    if a message was retrieved and the message was not
  322.         //    a WM_QUIT, 0 if a message was retrieved and it was
  323.         //    a WM_QUIT, and -1 if an error occurred.  
  324.  
  325.         static WInt FetchMessage( WMessage & message,
  326.                                   WBool waitForMessage=TRUE,
  327.                                   WBool removeMessage=TRUE,
  328.                                   WWindowHandle rootWindow=NULLHWND,
  329.                                   WULong firstMessage=0,
  330.                                   WULong lastMessage=0,
  331.                                   WBool filter=TRUE,
  332.                                   WBool * dispatch=NULL );
  333.  
  334.         // FreeThreadData
  335.         //
  336.         //    Frees any private (per-thread) data that might have been
  337.         //    allocated for this thread by the class library.
  338.  
  339.         static void FreeThreadData();
  340.  
  341.         // InstallFilter
  342.         //
  343.         //    Installs a message filter.  User-installed filters
  344.         //    should have a priority > WFP_SYSTEM.
  345.  
  346.         #define WFP_USER    64
  347.         #define WFP_SYSTEM  32
  348.         #define WFP_DEFAULT  0
  349.  
  350.         static WBool InstallFilter( WObject *object,
  351.                                     WMessageFilter filter,
  352.                                     void *userData=NULL,
  353.                                     WULong priority=WFP_USER,
  354.                                     WBool asHookFilter=TRUE );
  355.         static WBool InstallFilter( WStaticMessageFilter filter,
  356.                                     void *userData=NULL,
  357.                                     WULong priority=WFP_USER,
  358.                                     WBool asHookFilter=TRUE );
  359.  
  360.         // PostMessage
  361.         //
  362.         //    Posts a message for the current thread.  Returns TRUE
  363.         //    if the message was posted.
  364.  
  365.         static WBool PostMessage( const WMessage & message );
  366.  
  367.         // PostQuitMessage
  368.         //
  369.         //    Posts a WM_QUIT message to the current thread,
  370.         //    which will then cause a future FetchMessage
  371.         //    to return 0.
  372.  
  373.         static WBool PostQuitMessage( WInt exitCode=0 );
  374.  
  375.         // ProcessMessages
  376.         //
  377.         //    Enters a loop calling FetchMessage/DispatchMessage
  378.         //    until FetchMessage returns FALSE (WM_QUIT) or an
  379.         //    error occurs.  Returns TRUE if successful, FALSE
  380.         //    otherwise.  Optional WMessage value returns the
  381.         //    last message processed.
  382.  
  383.         static WBool ProcessMessages( WMessage * lastMessage=NULL );
  384.  
  385.         // RemoveFilter
  386.         //
  387.         //    Remove a filter that was installed using InstallFilter.
  388.         ///   Returns TRUE if a filter was found and removed.
  389.  
  390.         static WBool RemoveFilter( WObject *object,
  391.                                    WMessageFilter filter,
  392.                                    WBool fromHook=TRUE );
  393.         static WBool RemoveFilter( WStaticMessageFilter filter,
  394.                                    WBool fromHook=TRUE );
  395.  
  396.         // Sleep
  397.         //
  398.         //    Sleeps for the given number of milliseconds, or
  399.         //    forever if time=0xffffffff.  If time=0 then the
  400.         //    thread merely gives up its time slice.
  401.  
  402.         static WBool Sleep( WDWord time );
  403.  
  404.         // WaitForMessage
  405.         //
  406.         //    Waits until a message arrives in the queue.
  407.  
  408.         static void WaitForMessage();
  409.  
  410.         /***********************************************************
  411.          * Other
  412.          ***********************************************************/
  413.  
  414.         virtual WThreadHandle GetHandle() const;
  415.  
  416.         virtual WDWord GetID() const;
  417. };
  418.  
  419.  
  420. //
  421. // WThread -- Represents an arbitrary thread.
  422. //
  423.  
  424. class WCMCLASS WThread : public WThreadBase {
  425.     WDeclareSubclass( WThread, WThreadBase );
  426.  
  427.     public:
  428.  
  429.         /***********************************************************
  430.          * Constructors
  431.          ***********************************************************/
  432.  
  433.         WThread();
  434.         WThread( WThreadHandle handle, WDWord threadId,
  435.                  WBool closeIt=TRUE, WBool makeCopy=FALSE );
  436.         WThread( const WThread & thd );
  437.         WThread( const WCurrentThread & curr );
  438.  
  439.         ~WThread(); // does not terminate thread!
  440.  
  441.         /***********************************************************
  442.          * Operators
  443.          ***********************************************************/
  444.  
  445.         WThread& operator=( const WThread & thd );
  446.         WThread& operator=( const WCurrentThread & thd );
  447.  
  448.         /***********************************************************
  449.          * Properties
  450.          ***********************************************************/
  451.  
  452.         /***********************************************************
  453.          * Methods
  454.          ***********************************************************/
  455.  
  456.         // Clear
  457.         //
  458.         //    Resets the object, closing the low-level kernel
  459.         //    handle if no one else is referencing the thread.
  460.  
  461.         void Clear();
  462.  
  463.         // Create
  464.         //
  465.         //    Resets the object, then creates a new thread.
  466.  
  467.         WBool Create( WObject *object, WThreadRoutine handler,
  468.                       void *userData=NULL,
  469.                       WBool createSuspended=FALSE,
  470.                       WULong stackSize=0 );
  471.  
  472.         WBool Create( WStaticThreadRoutine handler,
  473.                       void *userData=NULL,
  474.                       WBool createSuspended=FALSE,
  475.                       WULong stackSize=0 );
  476.  
  477.         // PostMessage
  478.         //
  479.         //    Posts a message for the current thread.  Returns TRUE
  480.         //    if the message was posted.
  481.  
  482.         WBool PostMessage( const WMessage & message ) const;
  483.  
  484.         // PostQuitMessage
  485.         //
  486.         //    Posts a WM_QUIT message to the given thread,
  487.         //    which will then cause a future FetchMessage
  488.         //    to return 0.
  489.  
  490.         WBool PostQuitMessage( WInt exitCode=0 ) const;
  491.  
  492.  
  493.         /***********************************************************
  494.          * Other
  495.          ***********************************************************/
  496.  
  497.         virtual WThreadHandle GetHandle() const;
  498.  
  499.         virtual WDWord GetID() const;
  500.  
  501.     private:
  502.         WThreadReference *_threadRef;
  503. };
  504.  
  505. #ifndef _WNO_PRAGMA_PUSH
  506. #pragma enum pop;
  507. #pragma pack(pop);
  508. #endif
  509.  
  510. #endif // _WTHREAD_HPP_INCLUDED
  511.