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