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. If it is started from the

command line, it will usually run in the background. Wait a few

minutes (a few seconds on a modern machine) before you check the output.

You should see either a failure indication or a "Collector appears to

work" message.

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 gcconfig.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, gcconfig.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.

The test program and DLL will reside in the Release directory.

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.

Version 4.13 attempts to fix some of the earlier problems, but there

may be other issues. If you need solid support for win32 threads, you

might check with Geodesic Systems. Their collector must be licensed,

but they have invested far more time in win32-specific issues.

Hans

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

The collector has been compiled with Watcom C 10.6 and 11.0.

It runs under win32, win32s, and even under msdos with dos4gw

dos-extender. It should also run under OS/2, though this isn't

tested. Under win32 the collector can be built either as dll

or as static library.

Note that all compilations were done under Windows 95 or NT.

For unknown reason compiling under Windows 3.11 for NT (one

attempt has been made) leads to broken executables.

Incremental collection is not supported.

cord is not ported.

Before compiling you may need to edit WCC_MAKEFILE to set target

platform, library type (dynamic or static), calling conventions, and

optimization options.

To compile the collector and testing programs use the command:

wmake -f WCC_MAKEFILE

All programs using gc should be compiled with 4-byte alignment.

For further explanations on this see comments about Borland.

If gc compiled as dll, the macro ``GC_DLL'' should be defined before

including "gc.h" (for example, with -DGC_DLL compiler option). It's

important, otherwise resulting programs will not run.

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