README.TXT for MicroThread V2.5
What is MicroThread?
MicroThread is a minimal Turbo C multi-threading library for DOS
programs. Normal DOS programs are normally single-threaded, i.e. a
single determinate path of execution. However, in certain situations,
programs can be much easier to design if there can have multiple
concurrent paths of execution, i.e. multi-threaded. MicroThread
allows your Borland C DOS programs to have this multi-threading
capability, simply and easily.
MicroThread consists of a pre-emptive scheduling kernel which
dispatch threads on every timer interrupt(INT 8). It has a priority-
based scheduling algorithm, and has support for semaphores, critical
sections and inter-thread messages. The main features of MicroThread
1) It is written entirely in Turbo C, with no assembly code, so that
it can be easily understood and modified to suit your needs.
2) It is small. Unlike a number of other such libraries, MicroThread
contains only the basic essential code to implement a multi-threading
kernel for DOS programs and very little else. (Unfortunately the code
has grown a bit with each version, but I will try to keep this down
to a minimum).
3) It is FREE. I have placed the source code in the public domain in
the hope that somebody else would find it useful.
What MicroThread isn't:
1) MicroThread isn't a replacement for a "industrial-strength" multi-
tasking or multi-threading kernel. It was written primarily as an aid
for teaching multi-threading on an operating-systems course at the
University of Wolverhampton, UK.
2) It is not in any way optimised, either in its algorithms,
functionality, or speed. The code source was written in such a way
that it would be easier to go through on an overhead projection
screen in front of a class, rather than for elegance, style or speed.
Thus, the verbosity of the code and comments may be a bit of an over-
kill at times.
What do you need?
Though MicroThread was written mainly with Borland C V3.1, the source
files should compile quite happy under most versions of Turbo/Borland
C/C++. They have been compiled with the following versions: Turbo C
V2.0, Turbo C++ V1.1, Borland C V3.1 and Borland C++ V4.5.
The main MicroThread kernel is contained within the file MTHREAD.C
and you will also need the header file MTHREAD.H. The file MTCRTLIB.C
contains some C runtime library functions. Unfortunately Turbo C's
runtime library functions were never designed for multi-threaded use,
and are not re-entrant. Thus, you can't use them in a multi-threaded
program, except if you guard against re-entering them from different
threads at the same time. MTCRTLIB.C contains several functions which
uses a semaphore to guard against re-entrancy problems in calls to
Turbo C runtime function. The range of functions in MTCRTLIB.C are by
no means complete, as they were the only ones I had need to date, but
it should be straight forward enough add your own functions. It
however, you have no need for the runtime library functions or are
using runtime library functions in only one thread at any time, then
you won't need MTCRTLIB.C
Several example programs (DEMO1.C, DEMO2.C,...) are included within
the distribution along with their project files(DEMO1.PRJ,etc.). The
problem with project files is that they are version and installation
specific. These particular ones are specific to my version(V3.1) and
installation (C:\BORLANDC), so you may have to adjust the various
options once you have loaded them.
When you are building an application with MicroThread, there are
several points to bear in mind:
1) MicroThread has only ever been tested with the large model. I
haven't tried it with any other models yet as I very rarely use them
(I haven't installed them to save on disk space)
2) MicroThread needs a stack frame. It uses different stacks to keep
track of different threads. Thus you must build your application with
the "Standard Stack Frame" option enabled. You mustn't however enable
the stack overflow testing option. This will kill MicroThread stone-
3) DOS is not re-entrant. So if you use any DOS functions or any C
runtime functions which eventually calls DOS routines, MicroThread
will stop multi-threading temporarily until the DOS routine returns.
It accomplishes this by testing the InDOS flag. The upshot of this is
that if you use Control-S or the PAUSE key to pause the screen
output, you will effectively pause all threads in your program.
4) MicroThread will NOT run inside the Turbo C IDE debugger. The
Turbo C IDE debugger get confused by MicroThread's stack switching
and will crash. One possible way to trace through a MicroThread
program is to use Turbo Debugger and trace through it at the
instruction level(assembly code trace). Breakpoints, and
stepping(rather than tracing) also don't work terribly well.
5) Floating point isn't supported at the moment. Turbo C's floating
point emulator library isn't re-entrant, but can be guarded in the
same way as the other runtime libraries. However, if you have a
coprocessor or 486DX, then I am afraid things are not so great.
Adding support for coprocessors will mean delving into assembly code,
which confuses the issue would make MicroThread less of a useful
teaching tool for me. One possible work-around is to limit floating
point operations to only one thread, but this won't always work if
the other thread are also using other C runtime functions. Oh well,
such is life.
Details of how to use MicroThread are contained with the file
MTHREAD.TXT. The file describes the various functions and macros that
your application can call to use MicroThread.
Please do not hold me responsible if any of your programs break when
you use MicroThread. The only thing I will guarantee is that
MicroThread's behaviour is totally unpredictable, and will definitely
crash, at some point. When it does crash, it will probably also take
out whatever multi-tasking environment you happen to be running at
the time, be it DR Concurrent DOS, Windows 3.1, Windows 95, OS/2
Warp, Windows NT, or Desqview. You have been warn
Use and Distribution
Please feel free to use and distribute the source code in any manner
that you feel fit. If you do distribute your MicroThreaded
applications, I would appreciate a mention. If you develop any
extensions or modifications to MicroThread or demonstration programs
that you want to distribute, I would be grateful if you drop me a
note, so that I can mention it in this 'readme' file.
Comments and suggestions would be very welcome to :
Internet Email : email@example.com
Otherwise : J Ting
University of Wolverhampton
School of Computing & I. T.
WOLVERHAMPTON WV1 1SB