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