OpenXM_contrib2/asir2000/gc5.3/README.win32 - annotate

Return to README.win32 CVS log

Up to [local] / OpenXM_contrib2 / asir2000 / gc5.3

Annotation of OpenXM_contrib2/asir2000/gc5.3/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:

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>