Return to README.win32 CVS log

Up to [local] / OpenXM_contrib2 / asir2000 / gc

Annotation of OpenXM_contrib2/asir2000/gc/README.win32, Revision 1.1.1.1

1.1       noro        1: The collector has only been compiled under Windows NT, with the
                      2: original Microsoft SDK, with Visual C++ 2.0 and later, with
                      3: the GNU win32 environment, with Borland 4.5, and recently with
                      4: Watcom C.
                      5:
                      6: It runs under both win32s and win32, but with different semantics.
                      7: Under win32, all writable pages outside of the heaps and stack are
                      8: scanned for roots.  Thus the collector sees pointers in DLL data
                      9: segments.  Under win32s, only the main data segment is scanned.
                     10: (The main data segment should always be scanned.  Under some
                     11: versions of win32s, other regions may also be scanned.)
                     12: Thus all accessible objects should be accessible from local variables
                     13: or variables in the main data segment.  Alternatively, other data
                     14: segments (e.g. in DLLs) may be registered with the collector by
                     15: calling GC_init() and then GC_register_root_section(a), where
                     16: a is the address of some variable inside the data segment.  (Duplicate
                     17: registrations are ignored, but not terribly quickly.)
                     18:
                     19: (There are two reasons for this.  We didn't want to see many 16:16
                     20: pointers.  And the VirtualQuery call has different semantics under
                     21: the two systems, and under different versions of win32s.)
                     22:
                     23: The collector test program "gctest" is linked as a GUI application,
                     24: but does not open any windows.  Its output appears in the file
                     25: "gc.log".  It may be started from the file manager.  The hour glass
                     26: cursor will appear as long as it's running.  If it is started from the
                     27: command line, it will usually run in the background.  Wait a few
                     28: minutes (a few seconds on a modern machine) before you check the output.
                     29: You should see either a failure indication or a "Collector appears to
                     30: work" message.
                     31:
                     32: The cord test program has not been ported (but should port
                     33: easily).  A toy editor (cord/de.exe) based on cords (heavyweight
                     34: strings represented as trees) has been ported and is included.
                     35: It runs fine under either win32 or win32S.  It serves as an example
                     36: of a true Windows application, except that it was written by a
                     37: nonexpert Windows programmer.  (There are some peculiarities
                     38: in the way files are displayed.  The <cr> is displayed explicitly
                     39: for standard DOS text files.  As in the UNIX version, control
                     40: characters are displayed explicitly, but in this case as red text.
                     41: This may be suboptimal for some tastes and/or sets of default
                     42: window colors.)
                     43:
                     44: For Microsoft development tools, rename NT_MAKEFILE as
                     45: MAKEFILE.  (Make sure that the CPU environment variable is defined
                     46: to be i386.)
                     47:
                     48: For GNU-win32, use the regular makefile, possibly after uncommenting
                     49: the line "include Makefile.DLLs".  The latter should be necessary only
                     50: if you want to package the collector as a DLL.  The GNU-win32 port is
                     51: believed to work only for b18, not b19, probably dues to linker changes
                     52: in b19.  This is probably fixable with a different definition of
                     53: DATASTART and DATAEND in gcconfig.h.
                     54:
                     55: For Borland tools, use BCC_MAKEFILE.  Note that
                     56: Borland's compiler defaults to 1 byte alignment in structures (-a1),
                     57: whereas Visual C++ appears to default to 8 byte alignment (/Zp8).
                     58: The garbage collector in its default configuration EXPECTS AT
                     59: LEAST 4 BYTE ALIGNMENT.  Thus the BORLAND DEFAULT MUST
                     60: BE OVERRIDDEN.  (In my opinion, it should usually be anyway.
                     61: I expect that -a1 introduces major performance penalties on a
                     62: 486 or Pentium.)  Note that this changes structure layouts.  (As a last
                     63: resort, gcconfig.h can be changed to allow 1 byte alignment.  But
                     64: this has significant negative performance implications.)
                     65: The Makefile is set up to assume Borland 4.5.  If you have another
                     66: version, change the line near the top.  By default, it does not
                     67: require the assembler.  If you do have the assembler, I recommend
                     68: removing the -DUSE_GENERIC.
                     69:
                     70: Incremental collection support was recently added.  This is
                     71: currently pretty simpleminded.  Pages are protected.  Protection
                     72: faults are caught by a handler installed at the bottom of the handler
                     73: stack.  This is both slow and interacts poorly with a debugger.
                     74: Whenever possible, I recommend adding a call to
                     75: GC_enable_incremental at the last possible moment, after most
                     76: debugging is complete.  Unlike the UNIX versions, no system
                     77: calls are wrapped by the collector itself.  It may be necessary
                     78: to wrap ReadFile calls that use a buffer in the heap, so that the
                     79: call does not encounter a protection fault while it's running.
                     80: (As usual, none of this is an issue unless GC_enable_incremental
                     81: is called.)
                     82:
                     83: Note that incremental collection is disabled with -DSMALL_CONFIG,
                     84: which is the default for win32.  If you need incremental collection,
                     85: undefine SMALL_CONFIG.
                     86:
                     87: Incremental collection is not supported under win32s, and it may not
                     88: be possible to do so.  However, win32 applications that attempt to use
                     89: incremental collection should continue to run, since the
                     90: collector detects if it's running under win32s and turns calls to
                     91: GC_enable_incremental() into noops.
                     92:
                     93: James Clark has contributed the necessary code to support win32 threads.
                     94: This code is known to exhibit some problems with incremental collection
                     95: enabled.  Use NT_THREADS_MAKEFILE (a.k.a gc.mak) instead of NT_MAKEFILE
                     96: to build this version.  Note that this requires some files whose names
                     97: are more than 8 + 3 characters long.  Thus you should unpack the tar file
                     98: so that long file names are preserved.  To build the garbage collector
                     99: test with VC++ from the command line, use
                    100:
                    101: nmake /F ".\gc.mak" CFG="gctest - Win32 Release"
                    102:
                    103: This requires that the subdirectory gctest\Release exist.
                    104: The test program and DLL will reside in the Release directory.
                    105:
                    106: This version relies on the collector residing in a dll.
                    107:
                    108: This version currently supports incremental collection only if it is
                    109: enabled before any additional threads are created.
                    110: Version 4.13 attempts to fix some of the earlier problems, but there
                    111: may be other issues.  If you need solid support for win32 threads, you
                    112: might check with Geodesic Systems.  Their collector must be licensed,
                    113: but they have invested far more time in win32-specific issues.
                    114:
                    115: Hans
                    116:
                    117: Ivan V. Demakov's README for the Watcom port:
                    118:
                    119: The collector has been compiled with Watcom C 10.6 and 11.0.
                    120: It runs under win32, win32s, and even under msdos with dos4gw
                    121: dos-extender. It should also run under OS/2, though this isn't
                    122: tested. Under win32 the collector can be built either as dll
                    123: or as static library.
                    124:
                    125: Note that all compilations were done under Windows 95 or NT.
                    126: For unknown reason compiling under Windows 3.11 for NT (one
                    127: attempt has been made) leads to broken executables.
                    128:
                    129: Incremental collection is not supported.
                    130:
                    131: cord is not ported.
                    132:
                    133: Before compiling you may need to edit WCC_MAKEFILE to set target
                    134: platform, library type (dynamic or static), calling conventions, and
                    135: optimization options.
                    136:
                    137: To compile the collector and testing programs use the command:
                    138:     wmake -f WCC_MAKEFILE
                    139:
                    140: All programs using gc should be compiled with 4-byte alignment.
                    141: For further explanations on this see comments about Borland.
                    142:
                    143: If gc compiled as dll, the macro ``GC_DLL'' should be defined before
                    144: including "gc.h" (for example, with -DGC_DLL compiler option). It's
                    145: important, otherwise resulting programs will not run.
                    146:
                    147: Ivan Demakov (email: ivan@tgrad.nsk.su)
                    148:
                    149: