home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / power.zip / POWER.DOC < prev    next >
Text File  |  1994-11-09  |  12KB  |  293 lines
  1.                       PowerThreads V1.10
  2.  
  3.                         32 Bit Version
  4.  
  5.                   Copyright 1994, Greg Ratajik.
  6.  
  7.                CompuServe          : 74555,542
  8.                Internet            : 74555.542@compuserve.com
  9.                Voice               : (305)/340-7985
  10.                OS/2 ShareWare BBS  : (703)/385-4325
  11.                                       (CompuServe is where I provide
  12.                                        primary support)
  13.  
  14.   You may use this code in your programs under the
  15.   following conditions:
  16.  
  17.   o  That you keep the information banners/copyright notices intact
  18.      in the source code.
  19.  
  20.  
  21.   You may distribute it freely, as long as this documention is included
  22.   with it.
  23.  
  24.   Beyond that, go for it!  You're free to hack this up
  25.   in any way that you need.  I'm not asking for any return
  26.   on this code, except (maybe?) to provide a quick and
  27.   easy way for fellow OS/2 developers to thread their
  28.   programs.  If you make improvements, please get post it
  29.   to either CompuServe or the OS2 Shareware BBS.
  30.  
  31.    ---------------------------------------------------
  32.   | Special Thanks to Ron Finlayson, for part of the  |
  33.   | initial concept work on this.  It really helps to |
  34.   | have someone to brain storm with! :)              |
  35.    ---------------------------------------------------
  36.  
  37.   *****************************************************************
  38.   *DISCLAIMER OF WARRANTIES.  The following  code is              *
  39.   *sample code created by Greg Ratajik.  The code is provided     *
  40.   *"AS IS", without warranty of any kind.  Greg Ratatjik shall not*
  41.   *be liable for any damages arising out of your use of the sample*
  42.   *code.                                                          *
  43.   *****************************************************************
  44.  
  45.   I've heavily documented the code, so that's the best place to go
  46.   for information, BUT, if you don't want to do that, I've included
  47.   this little write up for basic information.
  48.   ---------------------------------------------------------------------------
  49.  
  50.   WHAT'S NEW IN VERSION 1.10
  51.  
  52.   o  Addition of PowerCall2 - See section VI for more information.
  53.  
  54.   o  Version 1.00 allowed multiple "Running... Wait" DLG's up at the same
  55.      time, but you couldn't see them.  This version allows you to see them.
  56.  
  57.   o  PowerCalls added tohe TaskList.
  58.  
  59.   ---------------------------------------------------------------------------
  60.  
  61. I.  Description
  62.  
  63.   This module has two main functions in it, PowerCall and
  64.   PowerHABCall.  Both of them let an application call a
  65.   function, while processing a PM message, without locking
  66.   up PM. The function calls can be treated like a normal
  67.   function that runs consecutively to other function calls
  68.   (instead of posting messages back to the parent, or
  69.   having a worker thread processing requests)
  70.  
  71.   The basic flow of this program is:
  72.  
  73.   PowerHABCall():
  74.  
  75.      Get PM Message
  76.            |
  77.           \|/
  78.       Start Thread --------------
  79.            |                    |
  80.            |                    |
  81.           \|/                  \|/
  82.       Process Queue         Call Function
  83.            |                    |
  84.            |                    |
  85.           \|/                  \|/
  86.          Return <---------- Notify Function Done
  87.            |
  88.            |
  89.           \|/
  90.    Continue Processing
  91.         Message
  92.  
  93.   =======================================================
  94.  
  95.   PowerCall():
  96.  
  97.      Get PM Message
  98.            |
  99.           \|/
  100.       Start Thread --------------
  101.            |                    |
  102.            |                    |
  103.           \|/                  \|/
  104.       Start DLG             Call Function
  105. (Will process messages)         |
  106.            |                    |
  107.            |                    |
  108.           \|/                  \|/
  109.          Return <---------- Post Message To DLG
  110.            |
  111.            |
  112.           \|/
  113.    Continue Processing
  114.         Message
  115.  
  116.  
  117.   PowerHABCall is the most straight forward way, but you
  118.   have to pass the HAB.  PowerCall is a little more
  119.   complex, but if you want to display something to the user
  120.   while the thread is running (i.e. do a timer, and animate
  121.   the pointer while the thread is running...) or if you
  122.   don't want to worry about getting the HAB, use
  123.   it.
  124.  
  125. II.  Limitations
  126.  
  127.   While this works very well, it should be noted that
  128.   starting and stopping a thread has a fair amount of
  129.   overhead.  If you are going to be making many of these
  130.   calls, I suggest starting a worker thread, as your
  131.   program will perform much better.
  132.  
  133. III. Uses
  134.  
  135.   This threading technique has two primary uses:
  136.  
  137.   o  An easy way to thread an existing program, without
  138.      changing the architecture of that program.
  139.  
  140.   o  A quick and easy way to add threads in new PM programs,
  141.      for "one-time" function calls (very much like the example.)
  142.  
  143. IV.  To add to your program...
  144.  
  145.   1.  Choose which function to use.  If you've got a lot of functions
  146.       to convert, or you want to do some special displays to the user,
  147.       you might want to use PowerCall.  Otherwise, use PowerHABCall, as
  148.       there is less overhead.
  149.  
  150.   2.  The example only uses one parm to the function that gets called.
  151.       (ProcessTest)  If you want to use more, you need to add a parm
  152.       to PowerCall and PowerHABCall, add the code to copy that parm
  153.       to the correct field in the structure THREAD_CALL_INFO, and
  154.       modify the functions CallFunction and CallHABFunction to use the
  155.       parms.  While this a little bit of work, I've documented the code
  156.       heavily, so it shouldn't be to bad.  If you have trouble doing this,
  157.       feel free to get in touch with me.  I'll help as much as I can
  158.       (time allowing)  See Section IV "Enhancements" for thoughts on how
  159.       to get rid of this type of modification all together.
  160.       NOTE:  If you don't want to modify the structures/code, you CAN
  161.       just use globals for everything.
  162.  
  163.   3.  Change the code to call your function to PowerCall/PowerHABCall.
  164.       For example, if you had:
  165.  
  166.       GetDate(&pdaInfo, &key1, "Test");
  167.  
  168.       You would now have:
  169.  
  170.       PowerCall(GetDate, &pdaInfo, &key1, "Test");
  171.  
  172.  
  173. IV.  Enhancements.
  174.  
  175.      I originally was going to make a DLL out of these two calls, and
  176.      sell the library.  The main reason that I didn't was the amount
  177.      of code it would take to make this thing 100% generic.  While
  178.      I've got some ideas of how to do this, I just don't have the time
  179.      right now to implement them.  The best way (from what I can see)
  180.      to make this generic would be to use varargs, and somehow
  181.      generically copy the args off of the stack in PowerCall (without
  182.      knowing sizes), moving them to the comm structure, and then
  183.      copying back onto the stack in CallFunction().
  184.  
  185.         If you want to try and do this, go for it.  BUT, if you do,
  186.      PLEASE send me a copy!  I would love to get away from modifying
  187.      this code for each Function I want to call.  (It's not tooooo bad...
  188.      but it's still to much more, and it adds a fair amount of code if
  189.      you've got more than one function to call.)
  190.  
  191. V.  Return Values.
  192.  
  193.     So far, I've used globals to handle return values (Yeah, it's lame,
  194.     but it works.)  If you want to pass return values, you can use
  195.     the comm structure to communicate the information around.  If you
  196.     have trouble doing it, let me know, and I (for a price! :) might
  197.     be able to give you an example.
  198.  
  199. VI. PowerCall2
  200.  
  201.     I've added a function called PowerCall2 to this example.  It's
  202.     just like PowerCall, except the thread is started in the dialog.
  203.     The advantange of this is that is is impossible for the thread to
  204.     end before the dialog has started.  The disadvantage of this is that
  205.     it takes a little longer for the thread to start (You have to wait
  206.     for the DLG to start before the thread gets kicked off.)
  207.  
  208. VII. Other shareware/PD programs to look for:
  209.     (OS/2 Programs I've written over the years)
  210.  
  211.      o EasyPlay - MM/PM program to play AVI, WAV, VOC, FLI, and
  212.                   any other file types MM/PM uses.  Features
  213.                   the ability to scan an entire drive for
  214.                   files, and play all lists files.  Makes use of
  215.                   threads for ALL file searching/playing (including
  216.                   PowerThreads!)
  217.  
  218.      o NetChat - This program allows many users to have Chat
  219.                  sessions over the LAN.  It allows each user to set
  220.                  up Conference groups and security levels.  Each
  221.                  Conference can have as many users as you want
  222.                  Chatting.  This is similar to CompuServer's CB, or
  223.                  a BBS's multi-node chat area.  (This program is free
  224.                  when you use QuikWare to register EasyPlay
  225.  
  226.      o NetMail - Improved net massaging (i.e. "Blue Boxes")
  227.  
  228.                     This program gives you better control of
  229.                system level LAN messages.  You can enter message
  230.                subjects, set priority levels, and type in longer
  231.                messages. 
  232.                     NetMail allows each user to set up their own
  233.                message groups, along with global message groups. 
  234.                Each user can choose which groups to receive
  235.                messages from, and what groups to send messages to.
  236.                     NetMail also let's you choose whether to get
  237.                the message in the traditional VIO BlueBox (but
  238.                better looking!), a PM Message Box, or to display
  239.                no message but to retrieve it at a latter time.
  240.                     This program makes Net Massaging easier to
  241.                use, and less annoying to the recipients.
  242.  
  243.      o    DeleteDir - A simple full-screen program to delete a
  244.           directory and all files/directories that are children to
  245.           it.
  246.  
  247.      o    ChkPath - Will check the path's you set in your
  248.           config.sys, and let you know if you've got problems.
  249.  
  250.      o    Pwh - Path'ed Where.  Will search a path for a file.  PWH
  251.           will tell you every place it hit's the file.  Very useful
  252.           for checking what version of a program you using.
  253.      
  254.      o    MDD - Multiple make directory.  MDD will create a
  255.           multiple directories (i.e. if you wanted to make
  256.           C:\GREG\PROGRAM\SOURCE20\MDD\RELEASE, MDD could do it in
  257.           one shot.)
  258.      
  259.      o    WHO - Will display information about all users of a
  260.           LAN/Domain.
  261.  
  262.      o    QWHO - Displays all user ID's currently on a LAN/Domain.
  263.  
  264.      o    Vtree - Visual directory tree.
  265.      o    EDCNFG - PM based program that will verify everything's
  266.           okay in your config.sys, keep track/retro changes into
  267.           multiple config's, and edit/setup a config.sys
  268.  
  269.      o    HPMLib - Library tracking system
  270.  
  271.      o    HPMCook - Cooking software
  272.  
  273.      o    HPMDiet - Dieting software
  274.  
  275.      o    JOGGER - OS/2 Program for runners.
  276.  
  277.      o    DosText - Change the message a OS/2 program gives when
  278.           running it from DOS.
  279.  
  280.  
  281.      Program Utilities/Toolkits:
  282.  
  283.      o    AniButtn - Two-state animated pushbuttons that you can
  284.           easily replace any pushbutton with.
  285.  
  286.      o    VidButtn -  Just like AniButtn, but will full-frame
  287.           animation.  (The ones in EasyPlay works exactly like a
  288.           pushbutton, but have up to 17 frames of animation!)
  289.  
  290.      o    DynoHelp - Dynamic Help toolkit (late '94, '95)
  291.  
  292.      o    Pops  - Dynamic Pop-up menu toolkit  (late '94, '95)
  293.