gcc/boehm-gc/README.win32

The collector has only been compiled under Windows NT, with the
original Microsoft SDK, with Visual C++ 2.0 and later, with
the GNU win32 environment, with Borland 4.5, and recently with
Watcom C.

It runs under both win32s and win32, but with different semantics.
Under win32, all writable pages outside of the heaps and stack are
scanned for roots.  Thus the collector sees pointers in DLL data
segments.  Under win32s, only the main data segment is scanned.
(The main data segment should always be scanned.  Under some
versions of win32s, other regions may also be scanned.)
Thus all accessible objects should be accessible from local variables
or variables in the main data segment.  Alternatively, other data
segments (e.g. in DLLs) may be registered with the collector by
calling GC_init() and then GC_register_root_section(a), where
a is the address of some variable inside the data segment.  (Duplicate
registrations are ignored, but not terribly quickly.)

(There are two reasons for this.  We didn't want to see many 16:16
pointers.  And the VirtualQuery call has different semantics under
the two systems, and under different versions of win32s.)

The collector test program "gctest" is linked as a GUI application,
but does not open any windows.  Its output appears in the file
"gc.log".  It may be started from the file manager.  The hour glass
cursor will appear as long as it's running.

The cord test program has not been ported (but should port
easily).  A toy editor (cord/de.exe) based on cords (heavyweight
strings represented as trees) has been ported and is included.
It runs fine under either win32 or win32S.  It serves as an example
of a true Windows application, except that it was written by a
nonexpert Windows programmer.  (There are some peculiarities
in the way files are displayed.  The <cr> is displayed explicitly
for standard DOS text files.  As in the UNIX version, control
characters are displayed explicitly, but in this case as red text.
This may be suboptimal for some tastes and/or sets of default
window colors.)

For Microsoft development tools, rename NT_MAKEFILE as
MAKEFILE.  (Make sure that the CPU environment variable is defined
to be i386.)

For GNU-win32, use the regular makefile, possibly after uncommenting
the line "include Makefile.DLLs".  The latter should be necessary only
if you want to package the collector as a DLL.  The GNU-win32 port is
believed to work only for b18, not b19, probably dues to linker changes
in b19.  This is probably fixable with a different definition of
DATASTART and DATAEND in config.h.

For Borland tools, use BCC_MAKEFILE.  Note that
Borland's compiler defaults to 1 byte alignment in structures (-a1),
whereas Visual C++ appears to default to 8 byte alignment (/Zp8).
The garbage collector in its default configuration EXPECTS AT
LEAST 4 BYTE ALIGNMENT.  Thus the BORLAND DEFAULT MUST
BE OVERRIDDEN.  (In my opinion, it should usually be anyway.
I expect that -a1 introduces major performance penalties on a
486 or Pentium.)  Note that this changes structure layouts.  (As a last
resort, config.h can be changed to allow 1 byte alignment.  But
this has significant negative performance implications.)
The Makefile is set up to assume Borland 4.5.  If you have another
version, change the line near the top.  By default, it does not
require the assembler.  If you do have the assembler, I recommend
removing the -DUSE_GENERIC.

Incremental collection support was recently added.  This is
currently pretty simpleminded.  Pages are protected.  Protection
faults are caught by a handler installed at the bottom of the handler
stack.  This is both slow and interacts poorly with a debugger.
Whenever possible, I recommend adding a call to
GC_enable_incremental at the last possible moment, after most
debugging is complete.  Unlike the UNIX versions, no system
calls are wrapped by the collector itself.  It may be necessary
to wrap ReadFile calls that use a buffer in the heap, so that the
call does not encounter a protection fault while it's running.
(As usual, none of this is an issue unless GC_enable_incremental
is called.)

Note that incremental collection is disabled with -DSMALL_CONFIG,
which is the default for win32.  If you need incremental collection,
undefine SMALL_CONFIG.

Incremental collection is not supported under win32s, and it may not
be possible to do so.  However, win32 applications that attempt to use
incremental collection should continue to run, since the
collector detects if it's running under win32s and turns calls to
GC_enable_incremental() into noops.

James Clark has contributed the necessary code to support win32 threads.
This code is known to exhibit some problems with incremental collection
enabled.  Use NT_THREADS_MAKEFILE (a.k.a gc.mak) instead of NT_MAKEFILE
to build this version.  Note that this requires some files whose names
are more than 8 + 3 characters long.  Thus you should unpack the tar file
so that long file names are preserved.  To build the garbage collector
test with VC++ from the command line, use

nmake /F ".\gc.mak" CFG="gctest - Win32 Release"

This requires that the subdirectory gctest\Release exist.

This version relies on the collector residing in a dll.

This version currently supports incremental collection only if it is
enabled before any additional threads are created.
It is known to not be completely solid.  At a minimum it can deadlock
if a thread starts in the middle of an allocation.  There may be
other problems.  If you need solid support for win32 threads, you
check with Geodesic Systems.  I haven't tried it, but they claim
to support it.

Hans

Ivan V. Demakov's README for the Watcom port:

[ He points out in a later message that there may be a problem compiling
  under Windows-3.11 for Windows NT. ]

Watcom C/C++ 10.5, 10.6, 11.0 tested.

The collector runs on WIN32 and DOS4GW dos-extender with both
stack and register based calling conventions (options -5r and -5s).
Incremental collection not supported.

OS/2 not tested, but should work (only some #ifdef's added for OS/2 port).

cord not ported. Watcom C fails to compile it, from first attempt.
Since I don't use it, I don't try to fix it.

cpp_test succeeds, but not compiled automaticaly with WCC_MAKEFILE.


My changes:

      * config.h      Added definitions for Watcom C/C++.
                      Undefined MPROTECT_VDB for Watcom C/C++ MSWIN32,
                      I don't have idea why it not work.

      * gc.h          Explicitly declared GC_noop. This prevents
                      program crash, compiled with -5r option.

      * gc_priv.h     Changed declaration for GC_push_one to make
                      compiler happy.
                      Added GC_dos4gw_get_mem declaration and
                      GET_MEM uses it in DOS4GW environment.

      * os_dep.c      Added __WATCOMC__ and DOS4GW #ifdef's.
                      Added GC_dos4gw_get_mem.

      * mach_dep.c    For Watcom used setjmp method of marking registers.

      * WCC_MAKEFILE  New file. Makefile for Watcom C/C++.

      * gc_watcom.asm New file. Some functions for DOS4GW.
                      This functions may (probably) be done in C,
                      but I can't figure out how do this for all
                      possible options of compiler.

      * README.watcom This file.


  Ivan Demakov (email: dem@tgrad.nsk.su)