home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / MAILBOX.ZIP / MPTSK.MAN < prev    next >
Encoding:
Text File  |  1988-06-27  |  9.3 KB  |  224 lines
  1. MPTSK(3C)        "MP-UNIX" Programmer's Manual        MPTSK(3C)
  2.  
  3.  
  4.  
  5. NAME
  6.     mptsk - cluster for multitask scheduling and communications
  7.  
  8.  
  9. SYNOPSIS
  10.     #include "mptsk.h"    /* (also link in mptsk libarary) */
  11.  
  12.     typedef    struct _MPBOX    MPBOX, PTR MPBOXID;    /* Mailbox */
  13.     typedef    MPRNG        MPMSG, PTR MPMSGID;    /* Message */
  14.     typedef    struct _MPTSK    MPTSK, PTR MPTSKID;    /* Task       */
  15.  
  16.     typedef    MPBOX        MPSCD, PTR MPSCDID;    /* Schedule Mailbox */
  17.  
  18.  
  19.     /* INITIALIZATION */
  20.  
  21.     void        mptsk_setup(void);
  22.  
  23.     MPTSKID        mptsk_init(VOIDPTR buf, MPTHDFN mpthdfn,
  24.                         MPSCDID mpscd);
  25.     VOIDPTR        mptsk_dinit(MPSCDID mpscd);
  26.  
  27.  
  28.     /* MESSAGE/CONTROL TRANSFER FUNCTONS */
  29.  
  30.     MPMSGID        mptsk_xfer(MPBOXID mpbox, MPMSGID mpmsg, BOOL block,
  31.                             MPSCDID mpscd);
  32.  
  33.     void        mptsk_send(MPBOXID mpbox, MPMSGID mpmsg);
  34.     MPMSGID        mptsk_csend(MPBOXID mpbox, MPMSGID mpmsg);
  35.     MPMSGID        mptsk_recv(MPBOXID mpbox);
  36.     MPMSGID        mptsk_crecv(MPBOXID mpbox, MPMSGID mpmsg);
  37.     void        mptsk_yield(void);
  38.     void        mptsk_yieldto(MPSCDID mpscd);
  39.     void        mptsk_broadcast(MPBOXID    mpbox, MPMSGID mpmsg);
  40.  
  41.  
  42.     /* STATUS FUNCTIONS */
  43.     MPTSKID        mptsk_me(void);
  44.  
  45.     MPBOXID        mptsk_mpbox(MPTSKID mptsk);
  46.     MPBOXID        mptsk_mympbox(void);
  47.  
  48.     MPBOXID        mptsk_waitingfor(MPTSKID mptsk);
  49.     MPBOXID        mptsk_mywaitingfor(void);
  50.  
  51.     MPMSGID        mptsk_owns(MPTSKID mptsk);
  52.     MPMSGID        mptsk_myowns(void);
  53.  
  54.     MPSCDID        mptsk_mpscd(MPTSKID mptsk);
  55.     MPSCDID        mptsk_mympscd();
  56.  
  57.  
  58.     /* DEFAULT PRIORITY SCHEDULE BOXES */
  59.     MPSCDID    mpscd_toptasks();
  60.     MPSCDID    mpscd_emergencytasks;
  61.     MPSCDID    mpscd_timecriticaltasks;
  62.     MPSCDID    mpscd_interactivetasks;
  63.     MPSCDID    mpscd_backgroundtasks;
  64.     MPSCDID    mpscd_batchtasks;
  65.     MPSCDID    mpscd_idletasks;
  66.  
  67.  
  68. DESCRIPTION
  69.  
  70. The MPTSK CLUSTER is the middle (2nd) layer of the Mailbox Multitasker.  It
  71. provides fast and flexible hiearchal scheduling and mailbox message passing
  72. for light-weight tasks.  The design is portable and support even course-grain
  73. *multiprocessing*.
  74.  
  75. The design is based on a mailbox abstraction.  A mailbox is the laison
  76. between tasks and messages.  When not empty, a mailbox will either contain a
  77. surpus of messages (waiting for tasks) or a deficit of tasks (waiting for
  78. messages).  The tasks/messages are queued and dequeued one at a time in
  79. strict FIFO order.
  80.  
  81. The mailboxes are used for scheduling as well as message passing.  Mailboxes
  82. in an ordered list are treated as a schedule (mpscd); when a processor needs
  83. a task to run, it will choose the first task on the first mailbox with tasks.
  84. Lower scheduled tasks will not be run until all higher scheduled tasks are
  85. completed or blocked.  However, since a task can yieldto its own schedule
  86. list it can also subschedule its time and thus provide for hiearchal or other
  87. kinds of scheduling.
  88.  
  89. The underlying mpthd functions are still usable.  With care, the programmer
  90. can switch between threads within a task.
  91.  
  92. The schedule organization and fast message & task passing is done with the
  93. mprng cluster (worth looking into).  It allows any data strcture to be
  94. efficently organized into circular lists (rings).
  95.  
  96. ---
  97.  
  98. mptsk_setup() initializes the cluster.  It should be called after
  99. mpthd_setup() has been called, and before any mailbox operations are called.
  100.  
  101.  
  102. mptsk_init() and mptsk_dinit() initialize and deinitialize, returning the new
  103. task or old buffer.  The mpscd argument of mptsk_init() indicates what
  104. schedule mailbox (priority) the new task should be scheduled on now and by
  105. default in the future (see mptsk_mpscd()); if scheduled on one of the
  106. mpscd_toptasks() (accessable to mptsk_xfer()), for instance, the task may
  107. begin running immediately.  For safety, if either argument of mptsk_init() is
  108. nil it returns nil.  Note mptsk_dinit() takes a MPSCDID as an argument; it a
  109. multiprocessing environment, you cannot assume a task is not running when you
  110. are (even when interrupts are disabled) and must wait for the task to put
  111. itself on a schedule box; also note, if there are no tasks in this box,
  112. mptsk_dinit() returns immediately with nil.
  113.  
  114. mptsk_xfer() is the heart of the mailbox multitasker.  Iff mpmsg is nil, it
  115. attempts to receive (and return) a message from the mpbox mailbox; otherwise,
  116. it attempts to send (and return nil) the message to mpbox.  Iff block is
  117. false, however, and there is no message waiting / no task to receive the
  118. message, then mptsk_xfer() returns nil / returns the message.  In the case
  119. when another waiting task is activated by a send, both it and the calling
  120. (mptsk_me()) tasks are rescheduled (on their default mptsk_mpscd() schedule
  121. box) and a new task to run is selected.  Whenever a runable task is needed,
  122. the user-supplied mpscd schedule list argument (if not nil) is first checked;
  123. if none are found or no list is given, a task will be found from the
  124. mpscd_toptasks() list.
  125.  
  126. Several common scheduling and communications operations can be derived from
  127. the mptsk_xfer() call, easily implemented as macros.  mptsk_send() and
  128. mptsk_recv() send and receive from a mpbox with blocking, and continuous
  129. mptsk_csend() and mptsk_crecv() without blocking.  The mptsk_yield()
  130. reschedules the calling task and temporarily yields its timeslice for other
  131. tasks; it should be called whenever a need for polling some condition (which
  132. cannot be explicitly (and more efficently) signaled by a mptsk_send()).  The
  133. deluxe mptsk_yieldto() allows a parent task to yield to its own schedule of
  134. children tasks, thus allowing hiearchal and more elaborate schedulers to be
  135. built.
  136.  
  137. mptsk_me() returns the current (calling) task.  This function is similar (but
  138. independent from) the mpthd_me() function.  The shorthand functions
  139. mptsk_my...() use mptsk_me() as their mptsk argument.
  140.  
  141. mptsk_mpbox() is the task's private mailbox.  This is initialized but unused
  142. by any of the Mailbox Multitasker functions and is provided to the user for
  143. his own inventive uses.
  144.  
  145. mptsk_waitingfor() tells the mailbox on which a task is currently waiting (or
  146. nil if it is executing right now).  It is maintained but not used by Mailbox.
  147. The associated mptsk_owns(), for use with the high (3rd) layer, returns the
  148. ring of resource sources the task owns.  If deadlocking is a problem, these
  149. two pieces of information can be used to efficently find and break deadlock,
  150. or, better yet, detect potential deadlock and prevent it.  This is left as an
  151. excercise for the programmer.
  152.  
  153. The mptsk_mpscd() variable tells the task's default schedule box (in essence,
  154. its priority) on which it is scheduled by mptsk_xfer().  This is a variable
  155. associated with the task, and can be assigned a new schedule box to change
  156. the task's priority (or freeze a task).
  157.  
  158. WARNING: This status information can be accessed by tasks other than the
  159. owner.  For this reason, in pre-emptive or multiprocessing environments,
  160. information can be partially (non-autonomously) written by one task while it
  161. read by another, causing mysterious, haphazard, unrepeatable bugs.  It is up
  162. to the user to control access to shared objects and realize which objects are
  163. shared.
  164.  
  165. A suggested priority list of scheduling boxes is provided and initialized.
  166. The only required box is mpscd_idletasks.  Onto this box, any selection of
  167. scheduling boxes (priorities) can be attached and dynamically arranged to
  168. suit the application needs.  The highest priority box, returned by
  169. mpscd_toptasks(), must always be the one cyclically after (mprng_next) the
  170. mpscd_idletask.  For example, after mptsk_setup(), mpscd_toptasks() will
  171. return mpscd_emergencytasks.
  172.  
  173.  
  174. RETURN VALUES & ERRORS
  175.  
  176. Return values are as specified.  Note the mptsk_xfer() transfer function
  177. returns the message iff it was not sent and returns nil iff no message was
  178. received.
  179.  
  180. No error checking is done on the MPSCDID and MPBOXID arguments.  For
  181. initialization functions, the MPTHDID and MPTSKID arguments are checked for
  182. nil value, and return nil if so.
  183.  
  184. WARNING: A common error causing mysterious bugs is stack overflow within the
  185. mptsk's mpthd.  Though mpthd_switch() often detects this when it trys to
  186. switch into a corrupted mpthd, by that time it may be to late.  If there
  187. seems to be mysterious pointer problems, try significantly increasing all the
  188. thread stack sizes.
  189.  
  190. NOTES
  191.  
  192. The multitasking interface is especially designed to take advantage of
  193. course-grain common-memory multiprocessor machines and to be portable to
  194. different "C" environments.  Using the same interface, similar functionality
  195. can be obtained with most stack-based languages.
  196.  
  197.  
  198. AVAILABILITY & BUGS
  199.  
  200. The mptsk cluster has been partially tested under MS-DOS (Turbo C).  It will
  201. later be tested on UNIX BSD 4.3 (IBM RT, DEC VAX, & SUN).  It may be easily
  202. ported to other machines & operating  systems.
  203.  
  204. SEE ALSO
  205.     mpres(3C), mpthd(3C), mpbox(3C), mprng(3C), and the mptsk*.* files.
  206.  
  207.     "Building a Portable Multitasking Environment in "C":
  208.         found in the file mptsk.tex
  209.     "First Come, First Served", BYTE Magazine, July 1988.
  210.  
  211.  
  212. AUTHOR
  213.  
  214. Copyright (C) 1987, 1988 Michael Benjamin Parker    (USA SS# 557-49-4130)
  215.  
  216. This interface, code, and documentation may be freely distributed *at no cost*
  217. provided the copyright notices are preserved and modifications are forwarded
  218. to the author (for inclusion in future releases).  See the file "mpthd.cpy"
  219. for specific details.  All other rights reserved.
  220.  
  221. mbparker@ATHENA.MIT.EDU / 721 E Walnut, Orange, CA  92667-6833 / 714-639-9497
  222.  
  223. Created: 4/1/88            Release: 0.7        Version: 06/27/88
  224.