Fix a typo in 'primitives' word in ChangeLog
[platform/upstream/libgc.git] / README.md
1 # Boehm-Demers-Weiser Garbage Collector
2
3 [![Travis-CI build status](https://travis-ci.org/ivmai/bdwgc.svg?branch=master)](https://travis-ci.org/ivmai/bdwgc)
4 [![AppVeyor CI build status](https://ci.appveyor.com/api/projects/status/github/ivmai/bdwgc?branch=master&svg=true)](https://ci.appveyor.com/project/ivmai/bdwgc)
5 [![Codecov.io](https://codecov.io/github/ivmai/bdwgc/coverage.svg?branch=master)](https://codecov.io/github/ivmai/bdwgc?branch=master)
6 [![Coveralls test coverage status](https://coveralls.io/repos/github/ivmai/bdwgc/badge.png?branch=master)](https://coveralls.io/github/ivmai/bdwgc)
7 [![Coverity Scan build status](https://scan.coverity.com/projects/10813/badge.svg)](https://scan.coverity.com/projects/ivmai-bdwgc)
8 [![LGTM Code Quality: Cpp](https://img.shields.io/lgtm/grade/cpp/g/ivmai/bdwgc.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/ivmai/bdwgc/context:cpp)
9 [![LGTM Total Alerts](https://img.shields.io/lgtm/alerts/g/ivmai/bdwgc.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/ivmai/bdwgc/alerts)
10
11 This is version 8.1.0 (next release development) of a conservative garbage
12 collector for C and C++.
13
14
15 ## Download
16
17 You might find a more recent/stable version on the
18 [Download](https://github.com/ivmai/bdwgc/wiki/Download) page, or
19 [BDWGC site](http://www.hboehm.info/gc/).
20
21 Also, the latest bug fixes and new features are available in the
22 [development repository](https://github.com/ivmai/bdwgc).
23
24
25 ## Overview
26
27 This is intended to be a general purpose, garbage collecting storage
28 allocator.  The algorithms used are described in:
29
30  * Boehm, H., and M. Weiser, "Garbage Collection in an Uncooperative
31    Environment", Software Practice & Experience, September 1988, pp. 807-820.
32
33  * Boehm, H., A. Demers, and S. Shenker, "Mostly Parallel Garbage Collection",
34    Proceedings of the ACM SIGPLAN '91 Conference on Programming Language Design
35    and Implementation, SIGPLAN Notices 26, 6 (June 1991), pp. 157-164.
36
37  * Boehm, H., "Space Efficient Conservative Garbage Collection", Proceedings
38    of the ACM SIGPLAN '91 Conference on Programming Language Design and
39    Implementation, SIGPLAN Notices 28, 6 (June 1993), pp. 197-206.
40
41  * Boehm H., "Reducing Garbage Collector Cache Misses", Proceedings of the
42    2000 International Symposium on Memory Management.
43
44 Possible interactions between the collector and optimizing compilers are
45 discussed in
46
47  * Boehm, H., and D. Chase, "A Proposal for GC-safe C Compilation",
48    The Journal of C Language Translation 4, 2 (December 1992).
49
50 and
51
52  * Boehm H., "Simple GC-safe Compilation", Proceedings of the ACM SIGPLAN '96
53    Conference on Programming Language Design and Implementation.
54
55 Unlike the collector described in the second reference, this collector
56 operates either with the mutator stopped during the entire collection
57 (default) or incrementally during allocations.  (The latter is supported
58 on fewer machines.)  On the most common platforms, it can be built
59 with or without thread support.  On a few platforms, it can take advantage
60 of a multiprocessor to speed up garbage collection.
61
62 Many of the ideas underlying the collector have previously been explored
63 by others.  Notably, some of the run-time systems developed at Xerox PARC
64 in the early 1980s conservatively scanned thread stacks to locate possible
65 pointers (cf. Paul Rovner, "On Adding Garbage Collection and Runtime Types
66 to a Strongly-Typed Statically Checked, Concurrent Language" Xerox PARC
67 CSL 84-7).  Doug McIlroy wrote a simpler fully conservative collector that
68 was part of version 8 UNIX (tm), but appears to not have received
69 widespread use.
70
71 Rudimentary tools for use of the collector as a
72 [leak detector](doc/leak.md) are included,
73 as is a fairly sophisticated string package "cord" that makes use of the
74 collector.  (See doc/README.cords and H.-J. Boehm, R. Atkinson, and M. Plass,
75 "Ropes: An Alternative to Strings", Software Practice and Experience 25, 12
76 (December 1995), pp. 1315-1330.  This is very similar to the "rope" package
77 in Xerox Cedar, or the "rope" package in the SGI STL or the g++ distribution.)
78
79 Further collector documentation can be found in the
80 [overview](doc/overview.md).
81
82
83 ## General Description
84
85 This is a garbage collecting storage allocator that is intended to be
86 used as a plug-in replacement for C's malloc.
87
88 Since the collector does not require pointers to be tagged, it does not
89 attempt to ensure that all inaccessible storage is reclaimed.  However,
90 in our experience, it is typically more successful at reclaiming unused
91 memory than most C programs using explicit deallocation.  Unlike manually
92 introduced leaks, the amount of unreclaimed memory typically stays
93 bounded.
94
95 In the following, an "object" is defined to be a region of memory allocated
96 by the routines described below.
97
98 Any objects not intended to be collected must be pointed to either
99 from other such accessible objects, or from the registers,
100 stack, data, or statically allocated bss segments.  Pointers from
101 the stack or registers may point to anywhere inside an object.
102 The same is true for heap pointers if the collector is compiled with
103 `ALL_INTERIOR_POINTERS` defined, or `GC_all_interior_pointers` is otherwise
104 set, as is now the default.
105
106 Compiling without `ALL_INTERIOR_POINTERS` may reduce accidental retention
107 of garbage objects, by requiring pointers from the heap to the beginning
108 of an object.  But this no longer appears to be a significant
109 issue for most programs occupying a small fraction of the possible
110 address space.
111
112 There are a number of routines which modify the pointer recognition
113 algorithm.  `GC_register_displacement` allows certain interior pointers
114 to be recognized even if `ALL_INTERIOR_POINTERS` is not defined.
115 `GC_malloc_ignore_off_page` allows some pointers into the middle of
116 large objects to be disregarded, greatly reducing the probability of
117 accidental retention of large objects.  For most purposes it seems
118 best to compile with `ALL_INTERIOR_POINTERS` and to use
119 `GC_malloc_ignore_off_page` if you get collector warnings from
120 allocations of very large objects.  See [here](doc/debugging.md) for details.
121
122 _WARNING_: pointers inside memory allocated by the standard `malloc` are not
123 seen by the garbage collector.  Thus objects pointed to only from such a
124 region may be prematurely deallocated.  It is thus suggested that the
125 standard `malloc` be used only for memory regions, such as I/O buffers, that
126 are guaranteed not to contain pointers to garbage collectible memory.
127 Pointers in C language automatic, static, or register variables,
128 are correctly recognized.  (Note that `GC_malloc_uncollectable` has
129 semantics similar to standard malloc, but allocates objects that are
130 traced by the collector.)
131
132 _WARNING_: the collector does not always know how to find pointers in data
133 areas that are associated with dynamic libraries.  This is easy to
134 remedy IF you know how to find those data areas on your operating
135 system (see `GC_add_roots`).  Code for doing this under SunOS, IRIX
136 5.X and 6.X, HP/UX, Alpha OSF/1, Linux, and win32 is included and used
137 by default.  (See doc/README.win32 for Win32 details.)  On other systems
138 pointers from dynamic library data areas may not be considered by the
139 collector.  If you're writing a program that depends on the collector
140 scanning dynamic library data areas, it may be a good idea to include
141 at least one call to `GC_is_visible` to ensure that those areas are
142 visible to the collector.
143
144 Note that the garbage collector does not need to be informed of shared
145 read-only data.  However, if the shared library mechanism can introduce
146 discontiguous data areas that may contain pointers then the collector does
147 need to be informed.
148
149 Signal processing for most signals may be deferred during collection,
150 and during uninterruptible parts of the allocation process.
151 Like standard ANSI C mallocs, by default it is unsafe to invoke
152 malloc (and other GC routines) from a signal handler while another
153 malloc call may be in progress.
154
155 The allocator/collector can also be configured for thread-safe operation.
156 (Full signal safety can also be achieved, but only at the cost of two system
157 calls per malloc, which is usually unacceptable.)
158
159 _WARNING_: the collector does not guarantee to scan thread-local storage
160 (e.g. of the kind accessed with `pthread_getspecific`).  The collector
161 does scan thread stacks, though, so generally the best solution is to
162 ensure that any pointers stored in thread-local storage are also
163 stored on the thread's stack for the duration of their lifetime.
164 (This is arguably a longstanding bug, but it hasn't been fixed yet.)
165
166
167 ## Installation and Portability
168
169 The collector operates silently in the default configuration.
170 In the event of problems, this can usually be changed by defining the
171 `GC_PRINT_STATS` or `GC_PRINT_VERBOSE_STATS` environment variables.  This
172 will result in a few lines of descriptive output for each collection.
173 (The given statistics exhibit a few peculiarities.
174 Things don't appear to add up for a variety of reasons, most notably
175 fragmentation losses.  These are probably much more significant for the
176 contrived program "test.c" than for your application.)
177
178 On most Unix-like platforms, the collector can be built either using a
179 GNU autoconf-based build infrastructure (type `./configure; make` in the
180 simplest case), or with a classic makefile by itself (type
181 `make -f Makefile.direct`).
182
183 Please note that the collector source repository does not contain configure
184 and similar auto-generated files, thus the full procedure of autoconf-based
185 build of `master` branch of the collector could look like:
186
187     git clone git://github.com/ivmai/bdwgc.git
188     cd bdwgc
189     git clone git://github.com/ivmai/libatomic_ops.git
190     ./autogen.sh
191     ./configure
192     make -j
193     make check
194
195 Cloning of `libatomic_ops` is now optional provided the compiler supports
196 atomic intrinsics.
197
198 Below we focus on the collector build using classic makefile.
199 For the Makefile.direct-based process, typing `make check` instead of `make`
200 will automatically build the collector and then run `setjmp_test` and `gctest`.
201 `Setjmp_test` will give you information about configuring the collector, which is
202 useful primarily if you have a machine that's not already supported.  Gctest is
203 a somewhat superficial test of collector functionality.  Failure is indicated
204 by a core dump or a message to the effect that the collector is broken.  Gctest
205 takes about a second to two to run on reasonable 2007 vintage desktops.  It may
206 use up to about 30 MB of memory.  (The multi-threaded version will use more.
207 64-bit versions may use more.) `make check` will also, as its last step,
208 attempt to build and test the "cord" string library.)
209
210 Makefile.direct will generate a library gc.a which you should link against.
211 Typing "make cords" will build the cord library (cord.a).
212
213 The GNU style build process understands the usual targets.  `make check`
214 runs a number of tests.  `make install` installs at least libgc, and libcord.
215 Try `./configure --help` to see the configuration options.  It is currently
216 not possible to exercise all combinations of build options this way.
217
218 All include files that need to be used by clients will be put in the
219 include subdirectory.  (Normally this is just gc.h.  `make cords` adds
220 "cord.h" and "ec.h".)
221
222 The collector currently is designed to run essentially unmodified on
223 machines that use a flat 32-bit or 64-bit address space.
224 That includes the vast majority of Workstations and X86 (X >= 3) PCs.
225
226 In a few cases (Amiga, OS/2, Win32, MacOS) a separate makefile
227 or equivalent is supplied.  Many of these have separate README.system
228 files.
229
230 Dynamic libraries are completely supported only under SunOS/Solaris,
231 (and even that support is not functional on the last Sun 3 release),
232 Linux, FreeBSD, NetBSD, IRIX 5&6, HP/UX, Win32 (not Win32S) and OSF/1
233 on DEC AXP machines plus perhaps a few others listed near the top
234 of dyn_load.c.  On other machines we recommend that you do one of
235 the following:
236
237   1. Add dynamic library support (and send us the code).
238   2. Use static versions of the libraries.
239   3. Arrange for dynamic libraries to use the standard malloc. This is still
240   dangerous if the library stores a pointer to a garbage collected object.
241   But nearly all standard interfaces prohibit this, because they deal
242   correctly with pointers to stack allocated objects.  (`strtok` is an
243   exception.  Don't use it.)
244
245 In all cases we assume that pointer alignment is consistent with that
246 enforced by the standard C compilers.  If you use a nonstandard compiler
247 you may have to adjust the alignment parameters defined in gc_priv.h.
248 Note that this may also be an issue with packed records/structs, if those
249 enforce less alignment for pointers.
250
251 A port to a machine that is not byte addressed, or does not use 32 bit
252 or 64 bit addresses will require a major effort.  A port to plain MSDOS
253 or win16 is hard.
254
255 For machines not already mentioned, or for nonstandard compilers,
256 some porting suggestions are provided [here](doc/porting.md).
257
258
259 ## The C Interface to the Allocator
260
261 The following routines are intended to be directly called by the user.
262 Note that usually only `GC_malloc` is necessary.  `GC_clear_roots` and
263 `GC_add_roots` calls may be required if the collector has to trace
264 from nonstandard places (e.g. from dynamic library data areas on a
265 machine on which the collector doesn't already understand them.)  On
266 some machines, it may be desirable to set `GC_stackbottom` to a good
267 approximation of the stack base (bottom).
268
269 Client code may include "gc.h", which defines all of the following, plus many
270 others.
271
272   1. `GC_malloc(bytes)` - Allocate an object of a given size.  Unlike malloc,
273   the object is cleared before being returned to the user.  `GC_malloc` will
274   invoke the garbage collector when it determines this to be appropriate.
275   GC_malloc may return 0 if it is unable to acquire sufficient space from the
276   operating system.  This is the most probable consequence of running out
277   of space.  Other possible consequences are that a function call will fail
278   due to lack of stack space, or that the collector will fail in other ways
279   because it cannot maintain its internal data structures, or that a crucial
280   system process will fail and take down the machine.  Most of these
281   possibilities are independent of the malloc implementation.
282
283   2. `GC_malloc_atomic(bytes)` - Allocate an object of a given size that
284   is guaranteed not to contain any pointers.  The returned object is not
285   guaranteed to be cleared. (Can always be replaced by `GC_malloc`, but
286   results in faster collection times.  The collector will probably run faster
287   if large character arrays, etc. are allocated with `GC_malloc_atomic` than
288   if they are statically allocated.)
289
290   3. `GC_realloc(object, new_bytes)` - Change the size of object to be of
291   a given size.  Returns a pointer to the new object, which may, or may not,
292   be the same as the pointer to the old object.  The new object is taken to
293   be atomic if and only if the old one was.  If the new object is composite
294   and larger than the original object then the newly added bytes are cleared.
295   This is very likely to allocate a new object.
296
297   4. `GC_free(object)` - Explicitly deallocate an object returned by
298   `GC_malloc` or `GC_malloc_atomic`, or friends.  Not necessary, but can be
299   used to minimize collections if performance is critical.  Probably
300   a performance loss for very small objects (<= 8 bytes).
301
302   5. `GC_expand_hp(bytes)` - Explicitly increase the heap size.  (This is
303   normally done automatically if a garbage collection failed to reclaim
304   enough memory.  Explicit calls to `GC_expand_hp` may prevent unnecessarily
305   frequent collections at program startup.)
306
307   6. `GC_malloc_ignore_off_page(bytes)` - Identical to `GC_malloc`, but the
308   client promises to keep a pointer to the somewhere within the first 256
309   bytes of the object while it is live.  (This pointer should normally be
310   declared volatile to prevent interference from compiler optimizations.)
311   This is the recommended way to allocate anything that is likely to be
312   larger than 100 KB or so.  (`GC_malloc` may result in a failure to reclaim
313   such objects.)
314
315   7. `GC_set_warn_proc(proc)` - Can be used to redirect warnings from the
316   collector.  Such warnings should be rare, and should not be ignored during
317   code development.
318
319   8. `GC_enable_incremental()` - Enables generational and incremental
320   collection.  Useful for large heaps on machines that provide access to page
321   dirty information.  Some dirty bit implementations may interfere with
322   debugging (by catching address faults) and place restrictions on heap
323   arguments to system calls (since write faults inside a system call may not
324   be handled well).
325
326   9. `GC_register_finalizer(object, proc, data, 0, 0)` and friends - Allow for
327   registration of finalization code.  User supplied finalization code
328   (`(*proc)(object, data)`) is invoked after object becomes unreachable.
329   For more sophisticated uses, and for finalization ordering issues, see gc.h.
330
331 The global variable `GC_free_space_divisor` may be adjusted up from it
332 default value of 3 to use less space and more collection time, or down for
333 the opposite effect.  Setting it to 1 will almost disable collections
334 and cause all allocations to simply grow the heap.
335
336 The variable `GC_non_gc_bytes`, which is normally 0, may be changed to reflect
337 the amount of memory allocated by the above routines that should not be
338 considered as a candidate for collection.  Careless use may, of course, result
339 in excessive memory consumption.
340
341 Some additional tuning is possible through the parameters defined
342 near the top of gc_priv.h.
343
344 If only `GC_malloc` is intended to be used, it might be appropriate to define:
345
346     #define malloc(n) GC_malloc(n)
347     #define calloc(m,n) GC_malloc((m)*(n))
348
349 For small pieces of VERY allocation intensive code, gc_inline.h includes
350 some allocation macros that may be used in place of `GC_malloc` and
351 friends.
352
353 All externally visible names in the garbage collector start with `GC_`.
354 To avoid name conflicts, client code should avoid this prefix, except when
355 accessing garbage collector routines.
356
357 There are provisions for allocation with explicit type information.
358 This is rarely necessary.  Details can be found in gc_typed.h.
359
360
361 ## The C++ Interface to the Allocator
362
363 The Ellis-Hull C++ interface to the collector is included in the collector
364 distribution.  If you intend to use this, type
365 `./configure --enable-cplusplus; make` (or `make -f Makefile.direct c++`)
366 after the initial build of the collector is complete.  See gc_cpp.h for the
367 definition of the interface.  This interface tries to approximate the
368 Ellis-Detlefs C++ garbage collection proposal without compiler changes.
369
370 Very often it will also be necessary to use gc_allocator.h and the
371 allocator declared there to construct STL data structures.  Otherwise
372 subobjects of STL data structures will be allocated using a system
373 allocator, and objects they refer to may be prematurely collected.
374
375
376 ## Use as Leak Detector
377
378 The collector may be used to track down leaks in C programs that are
379 intended to run with malloc/free (e.g. code with extreme real-time or
380 portability constraints).  To do so define `FIND_LEAK` in Makefile.
381 This will cause the collector to print a human-readable object description
382 whenever an inaccessible object is found that has not been explicitly freed.
383 Such objects will also be automatically reclaimed.
384
385 If all objects are allocated with `GC_DEBUG_MALLOC` (see the next section)
386 then, by default, the human-readable object description will at least contain
387 the source file and the line number at which the leaked object was allocated.
388 This may sometimes be sufficient.  (On a few machines, it will also report
389 a cryptic stack trace.  If this is not symbolic, it can sometimes be called
390 into a symbolic stack trace by invoking program "foo" with
391 `tools/callprocs.sh foo`.  It is a short shell script that invokes adb to
392 expand program counter values to symbolic addresses.  It was largely supplied
393 by Scott Schwartz.)
394
395 Note that the debugging facilities described in the next section can
396 sometimes be slightly LESS effective in leak finding mode, since in the latter
397 `GC_debug_free` actually results in reuse of the object.  (Otherwise the
398 object is simply marked invalid.)  Also, note that most GC tests are not
399 designed to run meaningfully in `FIND_LEAK` mode.
400
401
402 ## Debugging Facilities
403
404 The routines `GC_debug_malloc`, `GC_debug_malloc_atomic`, `GC_debug_realloc`,
405 and `GC_debug_free` provide an alternate interface to the collector, which
406 provides some help with memory overwrite errors, and the like.
407 Objects allocated in this way are annotated with additional
408 information.  Some of this information is checked during garbage
409 collections, and detected inconsistencies are reported to stderr.
410
411 Simple cases of writing past the end of an allocated object should
412 be caught if the object is explicitly deallocated, or if the
413 collector is invoked while the object is live.  The first deallocation
414 of an object will clear the debugging info associated with an
415 object, so accidentally repeated calls to `GC_debug_free` will report the
416 deallocation of an object without debugging information.  Out of
417 memory errors will be reported to stderr, in addition to returning `NULL`.
418
419 `GC_debug_malloc` checking during garbage collection is enabled
420 with the first call to this function.  This will result in some
421 slowdown during collections.  If frequent heap checks are desired,
422 this can be achieved by explicitly invoking `GC_gcollect`, e.g. from
423 the debugger.
424
425 `GC_debug_malloc` allocated objects should not be passed to `GC_realloc`
426 or `GC_free`, and conversely.  It is however acceptable to allocate only
427 some objects with `GC_debug_malloc`, and to use `GC_malloc` for other objects,
428 provided the two pools are kept distinct.  In this case, there is a very
429 low probability that `GC_malloc` allocated objects may be misidentified as
430 having been overwritten.  This should happen with probability at most
431 one in 2**32.  This probability is zero if `GC_debug_malloc` is never called.
432
433 `GC_debug_malloc`, `GC_debug_malloc_atomic`, and `GC_debug_realloc` take two
434 additional trailing arguments, a string and an integer.  These are not
435 interpreted by the allocator.  They are stored in the object (the string is
436 not copied).  If an error involving the object is detected, they are printed.
437
438 The macros `GC_MALLOC`, `GC_MALLOC_ATOMIC`, `GC_REALLOC`, `GC_FREE`,
439 `GC_REGISTER_FINALIZER` and friends are also provided.  These require the same
440 arguments as the corresponding (nondebugging) routines.  If gc.h is included
441 with `GC_DEBUG` defined, they call the debugging versions of these
442 functions, passing the current file name and line number as the two
443 extra arguments, where appropriate.  If gc.h is included without `GC_DEBUG`
444 defined then all these macros will instead be defined to their nondebugging
445 equivalents.  (`GC_REGISTER_FINALIZER` is necessary, since pointers to
446 objects with debugging information are really pointers to a displacement
447 of 16 bytes from the object beginning, and some translation is necessary
448 when finalization routines are invoked.  For details, about what's stored
449 in the header, see the definition of the type oh in dbg_mlc.c file.)
450
451
452 ## Incremental/Generational Collection
453
454 The collector normally interrupts client code for the duration of
455 a garbage collection mark phase.  This may be unacceptable if interactive
456 response is needed for programs with large heaps.  The collector
457 can also run in a "generational" mode, in which it usually attempts to
458 collect only objects allocated since the last garbage collection.
459 Furthermore, in this mode, garbage collections run mostly incrementally,
460 with a small amount of work performed in response to each of a large number of
461 `GC_malloc` requests.
462
463 This mode is enabled by a call to `GC_enable_incremental`.
464
465 Incremental and generational collection is effective in reducing
466 pause times only if the collector has some way to tell which objects
467 or pages have been recently modified.  The collector uses two sources
468 of information:
469
470   1. Information provided by the VM system.  This may be provided in one of
471   several forms.  Under Solaris 2.X (and potentially under other similar
472   systems) information on dirty pages can be read from the /proc file system.
473   Under other systems (e.g. SunOS4.X) it is possible to write-protect
474   the heap, and catch the resulting faults. On these systems we require that
475   system calls writing to the heap (other than read) be handled specially by
476   client code. See `os_dep.c` for details.
477
478   2. Information supplied by the programmer.  The object is considered dirty
479   after a call to `GC_end_stubborn_change` provided the library has been
480   compiled suitably. It is typically not worth using for short-lived objects.
481   Note that bugs caused by a missing `GC_end_stubborn_change` or
482   `GC_reachable_here` call are likely to be observed very infrequently and
483   hard to trace.
484
485
486 ## Bugs
487
488 Any memory that does not have a recognizable pointer to it will be
489 reclaimed.  Exclusive-or'ing forward and backward links in a list
490 doesn't cut it.
491
492 Some C optimizers may lose the last undisguised pointer to a memory
493 object as a consequence of clever optimizations.  This has almost
494 never been observed in practice.
495
496 This is not a real-time collector.  In the standard configuration,
497 percentage of time required for collection should be constant across
498 heap sizes.  But collection pauses will increase for larger heaps.
499 They will decrease with the number of processors if parallel marking
500 is enabled.
501
502 (On 2007 vintage machines, GC times may be on the order of 5 ms
503 per MB of accessible memory that needs to be scanned and processed.
504 Your mileage may vary.)  The incremental/generational collection facility
505 may help in some cases.
506
507
508 ## Feedback, Contribution, Questions and Notifications
509
510 Please address bug reports and new feature ideas to
511 [GitHub issues](https://github.com/ivmai/bdwgc/issues).  Before the
512 submission please check that it has not been done yet by someone else.
513
514 If you want to contribute, submit
515 a [pull request](https://github.com/ivmai/bdwgc/pulls) to GitHub.
516
517 If you need help, use
518 [Stack Overflow](https://stackoverflow.com/questions/tagged/boehm-gc).
519 Older technical discussions are available in `bdwgc` mailing list archive - it
520 can be downloaded as a
521 [compressed file](https://github.com/ivmai/bdwgc/files/1038163/bdwgc-mailing-list-archive-2017_04.tar.gz)
522 or browsed at [Narkive](http://bdwgc.opendylan.narkive.com).
523
524 To get new release announcements, subscribe to
525 [RSS feed](https://github.com/ivmai/bdwgc/releases.atom).
526 (To receive the notifications by email, a 3rd-party free service like
527 [IFTTT RSS Feed](https://ifttt.com/feed) can be setup.)
528 To be notified on all issues, please
529 [watch](https://github.com/ivmai/bdwgc/watchers) the project on
530 GitHub.
531
532
533 ## Copyright & Warranty
534
535  * Copyright (c) 1988, 1989 Hans-J. Boehm, Alan J. Demers
536  * Copyright (c) 1991-1996 by Xerox Corporation.  All rights reserved.
537  * Copyright (c) 1996-1999 by Silicon Graphics.  All rights reserved.
538  * Copyright (c) 1999-2011 by Hewlett-Packard Development Company.
539  * Copyright (c) 2008-2019 Ivan Maidanski
540
541 The files pthread_stop_world.c, pthread_support.c and some others are also
542
543  * Copyright (c) 1998 by Fergus Henderson.  All rights reserved.
544
545 The file include/gc.h is also
546
547  * Copyright (c) 2007 Free Software Foundation, Inc
548
549 The files Makefile.am and configure.ac are
550
551  * Copyright (c) 2001 by Red Hat Inc. All rights reserved.
552
553 The files extra/msvc_dbg.c and include/private/msvc_dbg.h are
554
555  * Copyright (c) 2004-2005 Andrei Polushin
556
557 The file tests/initsecondarythread.c is
558
559  * Copyright (c) 2011 Ludovic Courtes
560
561 The file tests/disclaim_weakmap_test.c is
562
563  * Copyright (c) 2018 Petter A. Urkedal
564
565 Several files supporting GNU-style builds are copyrighted by the Free
566 Software Foundation, and carry a different license from that given
567 below.
568
569 THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
570 OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.
571
572 Permission is hereby granted to use or copy this program
573 for any purpose,  provided the above notices are retained on all copies.
574 Permission to modify the code and to distribute modified code is granted,
575 provided the above notices are retained, and a notice that the code was
576 modified is included with the above copyright notice.
577
578 A few of the files needed to use the GNU-style build procedure come with
579 slightly different licenses, though they are all similar in spirit.  A few
580 are GPL'ed, but with an exception that should cover all uses in the
581 collector. (If you are concerned about such things, I recommend you look
582 at the notice in config.guess or ltmain.sh.)