home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_300 / 362_01 / rmaxtask.h < prev    next >
C/C++ Source or Header  |  1991-12-10  |  15KB  |  316 lines
  1. /*****************************************************************************
  2.  *                  rmaxtask.h                     *
  3.  *****************************************************************************
  4.  * DESCRIPTION: This file contains data structure definitions and function   *
  5.  *        prototypes for the RMAXTask multitasking package.         *
  6.  *                                         *
  7.  * REVISIONS:     1 JUL 90 - RAC - Original code                     *
  8.  *        10 DEC 91 - RAC - Added kill_task() and changed create_task  *
  9.  *                  to return a pointer to the created task    *
  10.  *                  instead of a status code.             *
  11.  *****************************************************************************/
  12.  
  13. /*****************************************************************************
  14.  *              Data Structure Definitions                 *
  15.  *****************************************************************************/
  16.  
  17. #ifndef _RMAXTASK
  18. #define _RMAXTASK
  19.  
  20. #define TDESC    struct task_descriptor
  21.  
  22. TDESC {                    /* The Task Descriptor */
  23.     char    task_name[20];        /* Text task name for debugging */
  24.     TDESC    *prev_wait;        /* Links to other tasks waiting at a */
  25.     TDESC    *next_wait;        /*  mailbox or semaphore */
  26.     TDESC    *prev_time;        /* Links to other tasks waiting on */
  27.     TDESC    *next_time;        /*  the timer */
  28.     long    timeout;        /* Timer expiration time */
  29.     unsigned    priority;        /* 0 = lowest, 0xFFFF = highest */
  30.     char    *stack_bottom;        /* Beginning of memory for stack */
  31.     char    far *my_stack;        /* Far pointer to this task's stack */
  32.     unsigned    my_BP;            /* Saved BP register */
  33.     unsigned    my_SI;            /* Saved SI register */
  34.     unsigned    my_DI;            /* Saved DI register */
  35.     unsigned    wait_status;        /* Status of last wait operation, or */
  36.                     /*  semaphore count */
  37.     void    *msg;            /* Pointer to place to put mail, or */
  38.                     /*  to oldest queued mailbox message */
  39.     unsigned    *mail_size;        /* Pointer to place to put mail size */
  40.     };
  41.  
  42. #define MQE struct msg_queue_entry
  43.  
  44. MQE {
  45.     MQE        *next_msg;        /* Link to next message in mailbox */
  46.     unsigned    msg_size;        /* Size of this message */
  47.     char    *msg_text;        /* Pointer to message text */
  48.     };    
  49.  
  50. /*****************************************************************************
  51.  *                  Manifest Constants                 *
  52.  *****************************************************************************/
  53.  
  54. #define TIMER_PRIORITY        0xF000    /* Timer task is very high priority */
  55. #define STANDARD_PRIORITY    100    /* Priority of Joe Average task */
  56. #define STANDARD_STACK        2000    /* Stack size for Joe Average task */
  57.  
  58. enum { OKAY, TIMEOUT };            /* Wait return status values */
  59.  
  60. /*****************************************************************************
  61.  *                  Function Prototypes                 *
  62.  *****************************************************************************/
  63.  
  64. /*****************************************************************************
  65.  *                   start_RMAXTask()                     *
  66.  *****************************************************************************
  67.  * DESCRIPTION:    Initializes the RMAXTask software.  This function must be    *
  68.  *        called before any other RMAXTask functions are used.         *
  69.  *                                         *
  70.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  71.  *****************************************************************************/
  72.  
  73. int start_RMAXTask(void);        /* 1 if all is well, 0 if error */
  74.  
  75. /*****************************************************************************
  76.  *                    stop_RMAXTask()                     *
  77.  *****************************************************************************
  78.  * DESCRIPTION:    Cleans up after the RMAXTask software.  Must be called         *
  79.  *        before the application returns to DOS.                 *
  80.  *                                         *
  81.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  82.  *****************************************************************************/
  83.  
  84. void stop_RMAXTask(void);
  85.  
  86. /*****************************************************************************
  87.  *                 create_task()                     *
  88.  *****************************************************************************
  89.  * DESCRIPTION: Establishes a specified C function as an RMAXTask task and   *
  90.  *        makes it READY.                             *
  91.  *                                         *
  92.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  93.  *        10 DEC 91 - RAC - Changed return value from simple error     *
  94.  *                   code to a pointer to the created task.    *
  95.  *****************************************************************************/
  96.  
  97. TDESC *create_task(            /* Pointer to task, or NULL if error */
  98.     char    *name,            /* Pointer to text name for task */
  99.     void    (*fn)(),        /* Ptr to the code for the task */
  100.     unsigned    priority,        /* Desired task priority */
  101.     unsigned    ssize            /* # of bytes for task's stack */
  102.     ); 
  103.  
  104. /*****************************************************************************
  105.  *                  kill_task()                     *
  106.  *****************************************************************************
  107.  * DESCRIPTION:    Allows one task to murder another.                 *
  108.  *                                         *
  109.  * NOTES:    This function must be used with extreme care to make sure    *
  110.  *        that the task being killed has his affairs in order.  He     *
  111.  *        should not "own" any dynamic memory, he should not have any  *
  112.  *        open files, etc.                         *
  113.  *                                         *
  114.  *        A task should NOT use this function to kill itself.  Tasks   *
  115.  *        wishing to commit suicide should do so by simply returning   *
  116.  *        from themselves, either by an explicit return or by simply   *
  117.  *        running off the end of themselves.  Tasks contemplating      *
  118.  *        suicide should also make sure their affairs are in order     *
  119.  *        as noted above.                             *
  120.  *                                         *
  121.  * REVISIONS:    10 DEC 91 - RAC - Adapted from auto_kill()             *
  122.  *****************************************************************************/
  123.  
  124. void kill_task(TDESC *victim);            /* Kill victim */
  125.  
  126. /*****************************************************************************
  127.  *                    yield()                     *
  128.  *****************************************************************************
  129.  * DESCRIPTION: Makes the calling task READY and then invokes the scheduler. *
  130.  *        If a task plans to run for a long time without either         *
  131.  *        waiting for an event or going to sleep, it should call this  *
  132.  *        routine periodically to allow higher-priority tasks the      *
  133.  *        chance to run.                             *
  134.  *                                         *
  135.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  136.  *****************************************************************************/
  137.  
  138. void yield(void);
  139.  
  140. /*****************************************************************************
  141.  *                   suspend()                     *
  142.  *****************************************************************************
  143.  * DESCRIPTION: Suspends a task for a given period of time.  The time is     *
  144.  *        given in BIOS clock ticks, which occur at about 18.2 Hz.     *
  145.  *                                         *
  146.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  147.  *****************************************************************************/
  148.  
  149. void suspend(
  150.     long    ticks            /* Sleep for <ticks> clock ticks */
  151.     );
  152.  
  153. /*****************************************************************************
  154.  *                   create_mailbox()                     *
  155.  *****************************************************************************
  156.  * DESCRIPTION: Creates a mailbox.                         *
  157.  *                                         *
  158.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  159.  *****************************************************************************/
  160.  
  161. TDESC *create_mailbox(void);        /* Ptr to new mailbox, NULL if error */
  162.  
  163. /*****************************************************************************
  164.  *                  send_mail()                     *
  165.  *****************************************************************************
  166.  * DESCRIPTION: Sends a message to a mailbox.                     *
  167.  *                                         *
  168.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  169.  *****************************************************************************/
  170.  
  171. int send_mail(                /* 1 if all is well, 0 if error */
  172.     void    *msg,            /* Pointer to message to send */
  173.     unsigned    size,            /* Size of message to send */
  174.     TDESC    *mailbox        /* Pointer to destination mailbox */
  175.     );
  176.  
  177. /*****************************************************************************
  178.  *                  get_mail()                     *
  179.  *****************************************************************************
  180.  * DESCRIPTION:    Waits at a mailbox for mail or a timeout.             *
  181.  *                                         *
  182.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  183.  *        29 NOV 90 - RAC - Added 'reverse' parameter.             *
  184.  *****************************************************************************/
  185.  
  186. void get_mail(
  187.     void    *msg,            /* Where to put result */
  188.     unsigned    *size,            /* Where to put result size */
  189.     TDESC    *mailbox,        /* Pointer to mailbox to use */
  190.     long    timeout,        /* Give up this many ticks from now */
  191.     int        reverse            /* Reverse normal queueing order */
  192.     );
  193.  
  194. /*****************************************************************************
  195.  *                 check_mail()                     *
  196.  *****************************************************************************
  197.  * DESCRIPTION: Tells if a particular mailbox has mail or not.             *
  198.  *                                         *
  199.  * REVISIONS:     1 JUL 90 - RAC - Original code                     *
  200.  *****************************************************************************/
  201.  
  202. int check_mail(                /* 1 if there is mail, else 0 */
  203.     TDESC    *mailbox        /* Ptr to mailbox of interest */
  204.     );
  205.  
  206. /*****************************************************************************
  207.  *                 get_status()                     *
  208.  *****************************************************************************
  209.  * DESCRIPTION:    For the current task, returns the status of the most recent  *
  210.  *        call to suspend(), get_mail(), wait_key(), or wait_sem().    *
  211.  *                                         *
  212.  * NOTE:    This routine will always return TIMEOUT following a call to  *
  213.  *        suspend().                             *
  214.  *                                         *
  215.  * REVISIONS:     3 JUL 90 - RAC - Original definition.                 *
  216.  *****************************************************************************/
  217.  
  218. int get_status(void);            /* TIMEOUT or OKAY */
  219.  
  220. /*****************************************************************************
  221.  *                 create_sem()                     *
  222.  *****************************************************************************
  223.  * DESCRIPTION:    Creates a semaphore.                         *
  224.  *                                         *
  225.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  226.  *****************************************************************************/
  227.  
  228. TDESC *create_sem(            /* Ptr to semphore, or NULL if error */
  229.     unsigned    count            /* Desired initial count */
  230.     );
  231.  
  232. /*****************************************************************************
  233.  *                 signal_sem()                     *
  234.  *****************************************************************************
  235.  * DESCRIPTION: Signals a semaphore.                         *
  236.  *                                         *
  237.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  238.  *****************************************************************************/
  239.  
  240. void signal_sem(
  241.     TDESC    *semaphore        /* Ptr to semaphore of interest */
  242.     );
  243.  
  244. /*****************************************************************************
  245.  *                 wait_sem()                     *
  246.  *****************************************************************************
  247.  * DESCRIPTION: Waits for a semaphore.                         *
  248.  *                                         *
  249.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  250.  *****************************************************************************/
  251.  
  252. void wait_sem(
  253.     TDESC    *semaphore,        /* Ptr to semaphore of interest */
  254.     long    timeout            /* Give up this many ticks from now */
  255.     );
  256.  
  257. /*****************************************************************************
  258.  *                  check_sem()                     *
  259.  *****************************************************************************
  260.  * DESCRIPTION: Returns a semaphore count.                     *
  261.  *                                         *
  262.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  263.  *****************************************************************************/
  264.  
  265. unsigned check_sem(            /* The semaphore count */
  266.     TDESC    *semaphore        /* Ptr to semaphore of interest */
  267.     );
  268.  
  269. /*****************************************************************************
  270.  *                  wait_key()                     *
  271.  *****************************************************************************
  272.  * DESCRIPTION:    Waits for a keystroke or a timeout.                 *
  273.  *                                         *
  274.  * REVISIONS:     1 JUL 90 - RAC - Original definition.                 *
  275.  *****************************************************************************/
  276.  
  277. int wait_key(                /* The keystroke, or '\0' if timeout */
  278.     long    timeout            /* Give up this many ticks from now */
  279.     );
  280.  
  281. /*****************************************************************************
  282.  *                   key_hit()                     *
  283.  *****************************************************************************
  284.  * DESCRIPTION: Tells if keystroke is available or not.                 *
  285.  *                                         *
  286.  * REVISIONS:     1 JUL 90 - RAC - Original code                     *
  287.  *****************************************************************************/
  288.  
  289. int key_hit(void);            /* 1 if there is a key, else 0 */
  290.  
  291. ///////////////////////////////////////////////////////////////////////////////
  292. //                  fake_key()                     //
  293. ///////////////////////////////////////////////////////////////////////////////
  294. // DESCRIPTION:    Allows a task to simulate a keystroke from the keyboard.     //
  295. //                                         //
  296. // REVISIONS:     8 OCT 90 - RAC - Original code                     //
  297. ///////////////////////////////////////////////////////////////////////////////
  298.  
  299. void fake_key(int key);
  300.  
  301. /*****************************************************************************
  302.  *                  RMAX_time()                     *
  303.  *****************************************************************************
  304.  * DESCRIPTION: Returns the value of rmax_tick, which starts at zero and is  *
  305.  *        bumped at about 18.2 Hz forever thereafter.  (It's a long    *
  306.  *        integer and won't wrap around for years (literally)).  Use   *
  307.  *        this function instead of the BIOS ticks to avoid the dreaded *
  308.  *        "midnight death" syndrome.                     *
  309.  *                                         *
  310.  * REVISIONS:    11 OCT 91 - RAC - Original code                     *
  311.  *****************************************************************************/
  312.  
  313. long RMAX_time();
  314.  
  315. #endif
  316.