Class DOSThread is now available as CUG Library volume #385. Volume #385 also includes the class TSR and the class Coroutine. All three packages have been contributed by John English.

DOSThread is a C++ class for creating multithreaded DOS programs. To produce threads, programs must derive classes from DOSThread; each instance of a derived class then implements a single thread. The executable code for each thread will be contained in each class's member function main. Users of DOSThread write member function main, but the derived class already does most of the work of multithreading, by supplying member functions for starting, stopping, and delaying threads.

This article is laid out in four major sections. The first section is a brief introduction to the overall capabilities of DOSThread threaded applications. The second section of the article shows how to create DOSThread applications. The third section introduces interthread communication and the use of Monitors via DOSThread-supplied member functions. Finally, the fourth section discusses a few problem areas in the current DOSThread implementation. The author of DOSThread welcomes communication about DOSThread; his various addresses are listed at the end of this article.

To create a thread, you derive a class from the DOSThread class; the derived class should contain the code you want to execute in a member function main. Then you simply declare an instance of your derived class and call the member function run to start it running. Each thread executes in intervals of 1 clock tick (55 milliseconds), then suspends execution to allow the other threads to execute. You can change the length of this timeslice if necessary, through member function timeslice. If necessary, you can disable timeslicing entirely, in which case it is up to each thread to relinquish the processor at regular intervals so the other threads have a chance to run.

Threads can delay themselves for a given number of clock ticks by calling member function delay; they can relinquish the processor to other threads by calling the member function pause; and they can terminate themselves or each other by calling the member function terminate. You can also inspect the current state of any thread (ready-to-run, terminated, delayed, etc.) by calling member function status, and you can cause your program to wait for a thread to terminate by calling the member function wait.

You can derive monitor classes of your own from two additional classes (DOSMonitor and DOSMonitorQueue) to facilitate communication between threads. A monitor implementation normally includes data structures to be accessed by several threads. To guarantee that only one thread at a time is executing a monitor member function (which accesses the data), call the member function lock at the start of the monitor function. If any other thread is already executing a monitor function guarded by lock, a contending thread will wait until it is safe to proceed. At the end of the monitor function, you should call unlock to allow any waiting threads to proceed.

Monitors containing instances of DOSMonitorQueue can also allow threads to suspend themselves in a monitor function until some condition has been fulfilled (e.g. buffer not empty). Other threads executing within the monitor can resume suspended threads when a condition is fulfilled (e.g. when a data item has been put into an empty buffer). This distribution also includes a template class which implements a bounded buffer.

The preceding paragraphs describe what are probably the most common uses of monitors in DOS applications, so you may not even need to define any monitor classes of your own.

void MyThread::main ()
{
    // code to be executed by your thread
}

After deriving a thread class, you can instantiate this derived class, as in:

MyThread threadl;        // a thread called "thread1"
MyThread threads [5];        // five identical threads

thread1.run ();

Once a thread has started successfully, it will execute in parallel with the main program. The main program effectively becomes another thread (although it has no name, and it can only call the static functions pause and delay described later).

As a default, each thread executes in a "timeslice" of one clock tick (55 msec). If a thread is still running when its timeslice expires, it moves to the back of the queue of ready-to-run threads, and the next thread in the queue resumes execution. You can call static member function timeslice to change the length of the timeslices. timeslice requires an unsigned integer parameter specifying the desired timeslice duration in clock ticks. For example:

DOSThread::timeslice (18);
    // timeslice once a second (18 x 55ms)

You must call timeslice before you declare any threads; as soon as the first thread has been declared, the program will ignore calls to timeslice. In other words, you cannot change the length of the timeslice during execution of the program.

pause ();           // schedule another thread

You can also make your thread wait for a fixed time by calling the static member function delay, specifying the delay period as a number of 55 msec clock ticks:

delay (18);            // delay for 1 second (18 x 55ms)

When MyThread::main returns, the main thread terminates. You can also terminate a thread explicitly by calling the member function terminate. If another thread (or the main program) wants to terminate thread1, it can do so like this:

thread1.terminate ();

terminate ();

When execution reaches the end of a block in which a thread was declared, the program calls the thread's destructor. The program calls any destructor in your derived class first (the thread could still be running), and then calls the standard DOSThread destructor to wait for the thread to terminate before tidying up. Your destructor should not do anything that might cause the thread to fail. To ensure that it does not interfere with the thread's execution, your destructor may call the member function wait, to wait for the thread to terminate. Your destructor should call this function before doing anything that might cause the thread to fail. In other words, your destructor should be written like this:

MyThread::~MyThread ()R
{
    wait ();          // wait for thread to terminate
    ...                // do any class-specific tidying up
}

if (DOSThread::userbreak ()) ...

DOS will generate critical errors (the familiar "Abort, Retry, Fail?" errors) if a disk is write-protected or if a printer is offline. Classes derived from DOSThread can provide a virtual function error to deal with critical errors generated within their member functions. Threads must provide their own critical error handlers on an individual basis; the default handler just fails the operation. To provide a critical error handler for a thread class, define a member function DOSerror as follows:

DOSThread::Error DOSerror (int N);

You should never call the function DOSerror directly; the program will call it automatically if an error occurs during execution of a thread.

state = thread1.status ();

Value                     Indication
OSThread::CREATED       — the thread is newly created and
                           can be started by calling run.
DOSThread::READY        — the thread is ready to run
                           (or is currently running).
DOSThread::DELAYED      — the thread has delayed itself
                           by calling delay.
DOSThread::WAITING      — the thread is waiting to enter a
                           monitor function guarded by lock.
DOSThread::QUEUED       — the thread is inside a monitor and
                           is suspended on a monitor queue.
DOSThread::TERMINATED   — the thread has terminated.

The base class DOSMonitor provides a convenient base for building safe interthread communication. You simply derive a class from DOSMonitor which encapsulates any shared data, and which provides functions to access the data. Each access function should begin by calling the member function lock and end by calling unlock. This practice will guarantee that only one thread at a time is executing an access function in any individual monitor. Therefore, the general structure required for a monitor access function is as follows:

void MyMonitor::access ( /* parameter list */ )
{
    lock ();
    ...           // access shared data as required
    unlock ();
}

Note that you should call suspend from within a loop; since resume will restart all the threads in the specified queue, you can't be sure that when your thread resumes execution that the condition the thread was waiting for will still be true. Thus, to suspend a thread until a counter is non-zero, use code such as the following:

while (counter != 0)
    suspend (some_queue);

class Buffer : public DOSMonitor
{
    char data[20];          // the buffer itself
    int count;              // no. of chars in buffer
    int in;                 // where to put next char
    int out;                // where to get next char from
    DOSMonitorQueue full;
    OSMonitorQueue empty;
public:
    Buffer ()                  {
count = in = out = 0; }
    void get (char& c);
     // get a char from the buffer
    void put (char& c);
     // put a char in the buffer
};

void Buffer::get (char& c)
{
    //--- lock the monitor
    //--- against re-entry
    lock ();

    //--- suspend until the
    //--- buffer isn't empty
    while (count == 0)
        suspend (empty);

    //--- get next character from the buffer
    c = data [out++];
    out %= 20

    //--- resume any threads waiting until buffer isn't full
    resume (full);

    //--- unlock the monitor to let other threads in
    unlock ();
}

BoundedBuffer<char> buffer(20);

Function       Description
get (item)  — Get the next item from the buffer and store it
               in item. The function returns 1 (true) if it is
               successful and 0 (false) if the buffer has
               been closed (see close).
put (item)  — Put a copy of item into the buffer. This
               function returns 1 (true) if it is successful
               and 0 (false) if the buffer has been closed
               (see close).
items ()    — Return the number of items in the buffer.
close ()    — Close the buffer to prevent further accesses.
               If you do not close buffers when you have
               finished using them, you run the risk of your
               program never terminating — a thread may be
               suspended waiting for a character that will
               never arrive, which means that its destructor
               will wait forever for it to terminate.

void error (DOSMonitor::ErrorCode);

Error Code Value             Interpretation
DOSMonitor::NEW_FAIL      — there was insufficient memory to
                             create the necessary data structures
                             for the monitor.
DOSMonitor::NO_THREAD     — a monitor has been called when
                             there are no threads running.
DOSMonitor::LOCK_FAIL     — the current thread is calling lock
                             when it has already locked the
                             monitor.
DOSMonitor::UNLOCK_FAIL   — the current thread has called
                             unlock without having locked
                             the monitor.
DOSMonitor::SUSPEND_FAIL  — the current thread has called
                             suspend without having locked
                             the monitor.
DOSMonitor::RESUME_FAIL   — the current thread has called
                             resume without having locked
                             the monitor.

If you do need to use BIOS functions directly, the best way is to localize all BIOS calls in a single monitor so that only one task can call a BIOS function at a time; however, since DOS services will make BIOS calls to perform their functions, you must also encapsulate all DOS calls in the monitor to guarantee that only one task is making a BIOS call at a time. Encapsulating all DOS calls may not be a terribly practical solution.

Another point worth noting: you should perform screen output with fputs rather than cout, printf or puts. These last three functions generate several DOS calls to output their data, so their output could become interleaved with the output of another thread. In particular, cout may produce the same output twice if its calling thread is interrupted at a particular moment (after output has been displayed but before the internal buffer has been cleared). Also, the next thread calling cout will append its output to the existing contents of the buffer, which will then be displayed in its entirety.

A more serious problem is that the program will not work with upper memory managers. In order to work, the program would need to save memory management context information during a thread context switch. In the interest of removing this limitation, the author would greatly appreciate the assistance of anyone familiar with the inner-workings of upper memory managers.