home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / MONTE.ZIP / PMTHREAD / README < prev    next >
Text File  |  1993-03-05  |  7KB  |  185 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6. TWO-THREADED PM APPLICATION ARCHITECTURE -- Monte Copeland
  7.  
  8. The Presentation Manager has been part of OS/2 versions since 1.1.  It is the
  9. part of OS/2 that provides the graphical, message-based, windowing
  10. environment known as the desktop.  OS/2 applications that utilize the
  11. windowing features of OS/2 are called Presentation Manager applications or PM
  12. apps.
  13.  
  14. PM apps, like all OS/2 applications, may call into the operating system for
  15. services via the OS/2 API's.  However, PM apps are required to provide some
  16. services to the Presentation Manager which makes the relationship between
  17. application and operating system a two-way street -- very cooperative.
  18.  
  19. PM sends messages to an application by calling window procedures in the
  20. application.  The window procedure will process messages like menu
  21. selections, client window painting, window resizing, mouse clicks, mouse
  22. movements, and termination.
  23.  
  24. In order for the Presentation Manager to stay in synch with all the
  25. applications on the desktop, it delivers messages one at a time.  These are
  26. "sent" messages.  Stated differently, when the Presentation Manager sends a
  27. message to your window procedure, it stops sending messages elsewhere until
  28. your procedure returns.
  29.  
  30. Therefore, PM apps must return from their window procedures in a timely
  31. manner; one-tenth second is recommended.  It is known as the one-tenth-second
  32. rule.  When an application takes too long, the symptoms include:
  33.  
  34. ■   user unable to minimize the application
  35. ■   user unable to switch to another application
  36. ■   hourglass pointer over entire desktop
  37. ■   the system dialog: "Application is not responding to system requests.
  38.     Press Enter to end it."
  39.  
  40.  
  41. Use a second thread in PM apps to bust the 1/10th second rule and perform
  42. tasks that take time:  diskcopy, upload/download, file input/output, SQL
  43. queries.  This article describes a robust two-threaded PM application
  44. architechure.  Applications coded in this style obey the 1/10th second rule,
  45. and they can perform lengthy tasks.
  46.  
  47.  
  48. THREAD DUTIES
  49.  
  50. Thread one is responsible for presentation.  Thread one will execute the
  51. normal window procedures of the application.  Its duty is to present the
  52. client window, dialogs and message boxes.  It reacts to command messages from
  53. its menus.  It processes messages generated by the frame window controls.
  54. Thread one is devoted to the operation of all the application's visible
  55. windows on the desktop.
  56.  
  57. Thread two will execute an object window procedure.  Object windows do not
  58. appear on the desktop; they are not bound by the 1/10th-of-a-second rule; PM
  59. sends them very few messages.  When object windows procedures execute on
  60.  
  61.  
  62.                                                                       Page  1
  63.  
  64.  
  65.  
  66. thread two, they are perfect for doing time-consuming tasks required by the
  67. application.
  68.  
  69. For the application to perform a task on thread two, the client window
  70. procedure calls WinPostMsg to post user-defined messages to the object
  71. window.  The object window procedure gets the message and performs the
  72. lengthy task on thread two.
  73.  
  74. client/dialog                         object window
  75. window on thread 1                    on thread 2
  76. ---------------                       ---------------
  77. |-------------|                       | waiting in  |
  78. | user        | WinPostMsg(           | WinGetMsg   |
  79. | requests    |     hwndObject,       |             |
  80. | a lengthy   |     WM_USER_WORKITEM, |             |
  81. | workitem    |     hwndToAck,        |             |
  82. |             |     null )            |             |
  83. |             | --------------------> |             |
  84. | window      |                       | perform     |
  85. | disabled    |                       | lengthy     |
  86. | while       |                       | task        |
  87. | busy        |                       |             |
  88. |             | WinPostMsg(           |             |
  89. |             |    hwndToAck,         |             |
  90. |             |    WM_USER_ACK,       |             |
  91. |             |    WM_USER_WORKITEM,  | task        |
  92. |             |    result code )      | complete    |
  93. |             | <-------------------- |             |
  94. | enable      |                       |             |
  95. | again       |                       |             |
  96. ---------------                       ---------------
  97.  
  98.  
  99. CLIENT DISABLED WHILE OBJECT BUSY
  100.  
  101. In the sample code below, the application disables its client and menu
  102. windows then posts a message to the object window to perform the lengthy
  103. task.  Disabling the menu and client windows permits only one outstanding
  104. task at a time.  Disabling these windows prevents the user from originating
  105. more tasks. Even though they are disabled from the user's point of view, they
  106. will continue to get and dispatch messages sent by PM.
  107.  
  108. The frame window is not disabled; therefore, the user can minimize the frame
  109. window and/or switch to another application while your application is busy.
  110.  
  111.  
  112.  
  113. OBJECT ACKS WHEN FINISHED
  114.  
  115. Upon completion of the lengthy task, the object window posts a user
  116. acknowledgement message to the client window. This informs the client that
  117. the task is complete. The client window procedure can re-enable the menu bar
  118. and the client window, or chain to other tasks as required.
  119.  
  120.  
  121.  
  122.  
  123.                                                                       Page  2
  124.  
  125.  
  126.  
  127.  
  128. COMMON DATA
  129.  
  130. Both threads share a common data space.  This space is defined by the GLOBALS
  131. structure in app.h.  WM_CREATE processing allocates this space and passes the
  132. pointer to thread two on the call to _beginthread.
  133.  
  134. The client and object window procedures keep a pointer to this memory in
  135. their window words.  The number of extra words per window is set by the
  136. WinRegisterClass calls. Both the client and object windows have four extra
  137. bytes of window words.
  138.  
  139. Dialog box procedures must obtain the pointer to shared memory and store it
  140. in their window words when they initialize.  By default, dialog boxes have
  141. enough window words to hold a 32-bits-long pointer.
  142.  
  143.  
  144.  
  145. PMASSERT
  146.  
  147. The pmassert macro is a debugging tool.  It works much like the C language
  148. assert macro.  Anywhere in the source code, the programmer can assert that a
  149. Boolean expression is true.  At runtime, nothing happens if the expression is
  150. true.  If false, the macro displays the failed assertion in a message box
  151. along with the line number and the C source file name where the assertion
  152. failed.
  153.  
  154. Because pmassert is a macro, it is easy to redefine the macro to be a "no
  155. operation" once the application is debugged.  In the C language tradition,
  156. this is accomplished by defining the symbol NDEBUG.  This approach to program
  157. building yields "debug" and "retail" versions of your program.  See
  158. pmassert.h below.
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.                                                                       Page  3
  185.