And, there is no warranty that CTask does perform without errors,
        or does exactly what you or I intended. So CTask should not be
        used in applications in which malfunction of routines of this
        package would result in damage to property or health of any
        person without *very* extensive testing under all kinds of loads.
        In using CTask, you do so at your own risk. I have tested CTask
        extensively, but with a complex system like CTask, where timing
        might make a big difference, you can't be completely sure that
        all will work as intended.


                          What is required to use CTask?

        To compile CTask, Microsoft C 5.1 or later, or Turbo C 2.0 or
        later are required. Microsoft MASM 5.1 or later, or TASM 1.01 or
        later is required for the assembler parts. Conversion to other
        compilers is possible if they conform to the new ANSI standard.
        Conversion of the assembler parts to other Assembler versions
        will likely be more complicated, since it requires substitution
        of the simplified model directives by explicit segment
        definitions, and adding the DGROUP to offsets referencing data.

        Note that you can not use TASM 1.0 to assemble CTask routines.
        The first version of TASM was not fully compatible with MASM, and
        creates different code in some places, which will lead to fatal
        crashes. TASM version 1.01 does not have this problem, and can
        safely be used.
        
        
        Ctask Manual       - Version 2.2 - 90-10-12 -              Page 7


        The CTask modules have been compiled and tested with Microsoft C
        6.0 without any apparent problems (Optimization level tested was
        /Ox). Since the stability of the MSC 6.0 code generator is
        doubtful, the distributed library was compiled with MSC 5.1.

        CTask will add 14k-25k of code to your program, depending on
        options and installed drivers. The minimum static data used by
        CTask is approximately 4k. Non-DOS versions use less memory.

        Converting CTask for stand-alone operation requires few changes.
        Mainly, the timer interrupt handler (in "tsktim.asm") has to be
        rewritten, and the initialization code (in "tskmain.c") may have
        to be changed. Changes to other modules (naturally except the
        optional hardware drivers) should not be necessary. The "DOS" and
        "IBM" configuration flags in tskconf.h can be disabled to elimi-
        nate most system-dependent features of CTask.

        Another requirement is a good debugger. If you never before wrote
        multitasking applications, you're in for some surprises. The nor-
        mal debugging tools (Symdeb, Codeview) are of only limited use,
        since they use DOS calls for their I/O, and thus may conflict
        with your background tasks. One safety measure is to first thor-
        oughly test your program with preemption disabled, possibly
        inserting some schedule() calls, and only allow task preemption
        if you found most major bugs. I personally recommend Periscope
        for debugging, since it can be made resident and so is always
        available, and because it does not use DOS. Periscope IV is the
        most expensive solution, and the best tool you can imagine, but
        the less costly versions will also help a lot.


                        Do I have to pay for using CTask?

        No. One reason for writing CTask was to provide a free, no
        strings attached, utility, instead of the usual "for personal use
        only" restriction. Writing a multitasking application for
        personal use only doesn't seem too interesting to me. CTask is
        completely free, and there is no restriction on its use. You may
        incorporate all or parts of CTask in your programs, and redistri-
        bute it in source or binary form by any means. I also do not
        restrict the use of CTask in commercial applications. Since
        trying to distribute the unmodified CTask for money will only
        give you a bad name, you may even do that if you find someone
        dumb enough to buy it. Naturally, if you make a bundle from it,
        or simply like CTask, I would not reject a donation. However,
        this is not required, and it will not give you any special
        support.






        
        
        Ctask Manual       - Version 2.2 - 90-10-12 -              Page 8


                           What support can I expect?

        I will try my best to eliminate any bugs reported to me, and to
        incorporate suggested enhancements and changes. However, my spare
        time is limited, so I can not guarantee continued or individual
        support. (But since I'm one of the owners of a consulting firm,
        you can always hire me to do it...). Please address all reports
        or questions to my business address:

                Ferrari electronic GmbH
                attn: Thomas Wagner
                Beusselstrasse 27
                D-1000 Berlin 21, Germany

                Phone: (+49 30) 396 50 21
                Fax:   (+49 30) 396 80 20

                BIX:   twagner
                UUCP:  oeschi@netmbx.UUCP (attn: Thomas Wagner)


        But, please, if at all possible, do it in writing. Please do not
        phone unless it is absolutely vital (or you have a business
        proposal). I like to hear about any applications for CTask, and
        if you are visiting Berlin, I also invite you to drop by for a
        talk. But I am usually not that happy when I am interrupted in my
        paid work by a phone call requesting support for a free product.

        I will try to answer all letters and Faxes I receive. However, I
        am usually not the fastest in this respect, so please be patient.
        If you don't hear for me for a while, send me a short reminder.
        The same goes for UUCP E-mail, since I'm not directly connected.
        The preferred, and the fastest, method to reach me is through
        BIX.

        BIX (tm) is the BYTE Information Exchange, an electronic confe-
        rencing system created by McGraw-Hill, the publishers of the well
        renowned BYTE magazine. BIX can be (and is) accessed from all
        parts of the world. Although accessing BIX from outside the US
        isn't exactly cheap (don't ask me what I have to pay each month),
        the wealth of information available there, and the fast and
        extensive help the other members can give you on all kinds of
        hard- and software problems, makes it worth every Mark, Peseta,
        Franc, or Ruble you have to spend. New versions and updates of
        CTask will first appear on BIX.

        At the time of this writing, I am one of the moderators of the
        IBM exchange on BIX, moderating the "ibm.other" conference. I
        have created a support topic for CTask, where all suggested
        enhancements and changes, plus bug reports, can be posted. Just
        join "ibm.other", topic "ctask". You can also report problems of
        limited general interest via BIXmail to "twagner". Unless I am
        not able to reach the keyboard for some reason, I log on at least
        
        
        Ctask Manual       - Version 2.2 - 90-10-12 -              Page 9


        once per day, so you can expect relatively fast responses to your
        queries.

        To get more info on joining BIX, call the BIX Customer Service at
        800-227-2983 (U.S. and Canada), or 603-924-7681 (New Hampshire
        and outside the U.S.) from 8:30 to 23:00 Eastern Time (-5 GMT).
        BIX access currently is $39 for three months (flat fee, no extra
        charges for connect time), plus the applicable telecomm charges
        (Tymnet in the U.S. and Canada, your local PTT's Packet Net
        charges from outside the U.S.). If you're calling from the US,
        you can subscribe by dialling BIX direct at 617-861-9767. Hit the
        return key, and enter "bix" at the 'login (enter "bix")' prompt.
        At the 'Name?' prompt, enter "bix.flatfee". International users
        living near a BT Tymnet node can access BIX through international
        Tymnet at special low rates. Call the BIX helpline for Tymnet
        access points and charges. Other international users will need an
        account (NUI) with their local packet net. Please enquire at your
        post/telecomm office for details. If you already own a NUI, enter
        the BIX international network address (NUA), "310690157800", and
        enter "bix.flatfee" at the 'Name?' prompt.


                                About this Release

        Since the Beta release of CTask in March 1988, CTask has found
        widespread distribution through several channels. I have heard
        from some users, and their suggestions have been implemented in
        this version as far as possible.

        Special thanks go to Kent J. Quirk, Peter Heinrich, Stephen
        Worthington, Burt Bicksler, Tron Hvaring, Joe Urso, Dave Goodwin,
        Chris Blum, and Dan Heine, for their bug reports, suggestions,
        and enhancements. Bug reports and suggestions also came in from
        others, thanks to all who wrote or called. The serial code in
        TSKSIO.C was enhanced for version 2.0 by S. Worthington, and his
        ideas on debugging have been incorporated in the version 2.1
        debugging mode. Dan Heine provided valuable info on 80x87 numeric
        coprocessor support. Chris Blum wrote the integer-based
        millisecond to clock-tick conversion routine.

        Again, please notify me of your CTask application, report bugs,
        or suggest changes and enhancements. If I know you're using
        CTask, I can notify you of possible new releases and of possible
        severe bugs.









        
        
        Ctask Manual       - Version 2.2 - 90-10-12 -             Page 10


                               Multitasking Basics

                                      Tasks

        In CTask, a "task" is defined as a (far) C function. The number
        of tasks is not limited, and one function may be used for several
        tasks. There is little difference between a task function and a
        normal function. The usual form of a task function is

             void Taskfunc my_task (farptr arg)
             {
                  one-time initialization code
                  while (TRUE)
                    {
                    processing code
                    }
             }

        A task function is (usually) never called directly. Rather, it is
        specified in the call to the create_task routine, and started by
        start_task. It will then continue to run, sharing the processor
        time with all other tasks, until it is "killed" by kill_task.
        Returning from the routine will have the same effect as a kill.
        The sharing of processor time is accomplished by "preempting" the
        tasks. Preemption means that the task is interrupted in the
        middle of some statement by a hardware interrupt (usually the
        timer), and is *not* immediately restarted when the interrupt
        handler returns. Instead, the next task that is able to run is
        activated by the "scheduler", with the interrupted task
        continuing its duty at some (normally unpredictable) later time.
        You can also have multi-tasking without preemption, and CTask
        supports this, too, but this requires full cooperation of all
        tasks in the system, such that no task continues to run for an
        extended period of time without passing control to other tasks by
        an explicit scheduling request, or by waiting for an event.

        The optional argument to the task function may be used if one
        function is to be used for more than one task, for example to
        pass a pointer to a static data area for use by this specific
        instance of the function.


                                      Events

        Tasks alone would be of limited use. If you have several routines
        which just do number crunching or sorting or such, making them
        into parallel tasks would be sensible only on a multiprocessor
        system. Normally, at least some of your tasks will wait for some
        outside "event" to happen, be it the user pressing a key, or a
        character arriving from the modem. Then there may be tasks which
        have to wait until another task finishes processing on some piece
        of data before they can continue. For this synchronization, there
        are a number of constructs in CTask, which I summarize under the
        
        
        Ctask Manual       - Version 2.2 - 90-10-12 -             Page 11


        name "event". Common to all events are the operations of waiting
        for an event to happen, and signalling that the event has
        happened. Using a CTask event is much more efficient than looping
        while waiting on some shared data location to change state, and
        also eliminates concurrency problems inherent in such a simple
        approach. Tasks waiting for an event are taken off the scheduler
        queue, so they no longer use processor time.


                                    Reentrancy

        One of the biggest problem with multitasking in general, and C on
        the PC in particular, is reentrancy. Reentrancy means that you
        can use a routine, be it you own, or one of the C run-time
        library, from different tasks at the same time. When writing your
        own code, you can easily avoid problems, but when using the run-
        time library routines, you often can only guess if the routines
        are reentrant or not.

        A routine is NOT reentrant if it modifies static data. This can
        be illustrated by the following nonsense example:

             int non_reentrant (int val)
             {    static int temp;
                  temp = val;
                  return temp * 2;
             }