home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / MAILBOX.ZIP / MPTHD.MAN < prev    next >
Encoding:
Text File  |  1988-06-27  |  4.6 KB  |  123 lines
  1. MPTHD(3C)        "MP-UNIX" Programmer's Manual        MPTHD(3C)
  2.  
  3.  
  4.  
  5. NAME
  6.     mpthd - cluster for managing multiple threads of execution
  7.  
  8.  
  9. SYNOPSIS
  10.     #include "mpthd.h"    /* (also link in mpthd libarary) */
  11.  
  12.     typedef    struct _MPTHD    MPTHD, PTR MPTHDID;
  13.     typedef    MPTHDID        (*MPTHDFN)(MPTHDID callingmpthd);
  14.  
  15.     MPTHDID        mpthd_setup(VOIDPTR buf, UINT size);
  16.     void        _mpthd_setup(MPTHDID mainmpthd);
  17.  
  18.     MPTHDID        mpthd_init(VOIDPTR buff, UINT size, MPTHDFN mpthdfn);
  19.     VOIDPTR        mpthd_dinit(MPTHDID mpthdtodie);
  20.  
  21.     MPTHDID        mpthd_me(void);
  22.  
  23.     MPTHDID        mpthd_switch(MPTHDID mpthdtoswitchto);
  24.  
  25.     STRTYPE PTR    mpthd_heap(MPTHDID mpthd, STRTYPE);
  26.     STRTYPE PTR    mpthd_myheap(STRTYPE);
  27.  
  28.  
  29. DESCRIPTION
  30.  
  31. The mpthd cluster allows software switching of program control between
  32. multiple threads of execution.  Threads are "light weight" processes.  Unlike
  33. fork(2), they are quick to create, destroy, & switch between, and allow easy
  34. communication by sharing all global and dynamic variables.
  35.  
  36. The mpthd_switch function suspends the current thread of execution, mpthd_me(),
  37. and switches into the new thread, mpthdtoswitchto.  The first thread will
  38. resume when another thread switches back to it, and mpthd_switch will return
  39. this thread which restored control.
  40.  
  41. Threads can be initialized using the mpthd_init(...) function.  The initializer
  42. must specify the thdfn (thread function) which the thread is to execute when it
  43. is switched to, as well as the stack buff and its size in which the thread is
  44. to execute.  When first switched to, the new thread will set up to
  45. allow/disallow interrupts (see mpsig(3C)) as its initializer had set up when
  46. the thread was initialized.
  47.  
  48. The new thread will call mpthdfn with the previous thread as its argument; it
  49. will switch to the thread that mpthdfn returns, and repeat this process
  50. indefinitely.  In other words,
  51.  
  52.     for (EVER)    prevmpthd= mpthd_switch(mpthdfn(prevmpthd));
  53.  
  54. mpthd_dinit is used to deinitialize threads.  It will wait until mpthdtodie is
  55. not being executed, and will return the original buff pointer.
  56.  
  57. mpthd_heap(MPTHDID mpthd, STRTYPE) returns a STRTYPE pointer to the thread's
  58. local heap, where STRTYPE is your own structure type.  The local heap can be
  59. used by the thread for dynamically-allocated variables, but is most useful for
  60. passing arguments between threads without using global variables.
  61. mpthd_myheap(STRTYPE) is shorthand for mpthd_heap(mpthd_me(),STRTYPE).
  62.  
  63. mpthd_setup(void PTR buf, UINT size) is used to setup the environment for
  64. mpthd's.  It initializes a thread in buf as mpthd_init() does, and sets it
  65. up as the current (main()) thread (the main() function, however, uses
  66. a normal stack, not a thread stack).  Internal _mpthd_setup does the
  67. setup, and is provided for higher-level multitaskers.
  68.  
  69.  
  70. RETURN VALUES & ERRORS
  71.  
  72. Return values are as specified.  Exceptions: mpthd_switch will return NIL iff
  73. it finds the mpthdtoswitchto structure/stack corrupted.  Usually this is
  74. happens when a thread's stack is smaller than what its thdfn needs to execute.
  75. To help prevent this, mpthd_init and mpthd_setup will return NIL iff
  76. size < 3*sizeof(MPTHD).  Also, mpthd_dinit(...) will return NIL iff a thread
  77. tries to deinitialize itself.
  78.  
  79.  
  80. NOTES
  81.  
  82. The calls are robust.  The interrupt enable/disable state is preserved between
  83. switches so switches can be made within signal handlers to implement
  84. pre-emptive multitasking.
  85.  
  86. The implementation is highly portable; with little modification it will run on
  87. most machines/operating systems compiling "C" and supporting the standard
  88. setjmp and longjmp library functions.  Using semaphores to control the
  89. execution of threads, the implementation can also be used on multiprocessor
  90. machines with a common address space.
  91.  
  92. The multitasking interface is also designed to be portable.  Using the same
  93. interface, similar functionality can be obtained with most stack-based
  94. languages.
  95.  
  96.  
  97. AVAILABILITY & BUGS
  98.  
  99. The mpthd cluster has been tested under MS-DOS (Turbo C) and UNIX BSD 4.3
  100. (IBM RT, DEC VAX).  It may be easily ported to other machines & op. systems.
  101.  
  102.  
  103. SEE ALSO
  104.     mpsig(3C), mpsem(3C), and the mpthd.* files.
  105.  
  106.     "Building a Portable Multitasking Environment in "C":
  107.     #1 - Switching Contexts"  found in the file mpthd.tex
  108.  
  109.  
  110. AUTHOR
  111.  
  112. Copyright (C) 1987 Michael Benjamin Parker        (USA SS# 557-49-4130)
  113.  
  114. This interface, code, and documentation may be freely distributed *at no cost*
  115. provided the copyright notices are preserved and modifications are forwarded
  116. to the author (for inclusion in future releases).  All other rights reserved.
  117.  
  118. mbparker@ATHENA.MIT.EDU / 721 E Walnut, Orange, CA  92667-6833 / 714-639-9497
  119.  
  120.  
  121. Created: 12/8/87        Release: 0.7        Version: 4/1/88
  122.  
  123.