~ubuntu-branches/ubuntu/intrepid/ecl/intrepid

« back to all changes in this revision

Viewing changes to src/gc/README.QUICK

  • Committer: Bazaar Package Importer
  • Author(s): Peter Van Eynde
  • Date: 2006-05-17 02:46:26 UTC
  • Revision ID: james.westby@ubuntu.com-20060517024626-lljr08ftv9g9vefl
Tags: upstream-0.9h-20060510
ImportĀ upstreamĀ versionĀ 0.9h-20060510

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
Copyright 1988, 1989 Hans-J. Boehm, Alan J. Demers
 
2
Copyright (c) 1991-1995 by Xerox Corporation.  All rights reserved.
 
3
Copyright (c) 1996-1999 by Silicon Graphics.  All rights reserved.
 
4
Copyright (c) 1999-2001 by Hewlett-Packard. All rights reserved.
 
5
 
 
6
THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
 
7
OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.
 
8
 
 
9
Permission is hereby granted to use or copy this program
 
10
for any purpose,  provided the above notices are retained on all copies.
 
11
Permission to modify the code and to distribute modified code is granted,
 
12
provided the above notices are retained, and a notice that the code was
 
13
modified is included with the above copyright notice.
 
14
 
 
15
A few files have other copyright holders. A few of the files needed
 
16
to use the GNU-style build procedure come with a modified GPL license
 
17
that appears not to significantly restrict use of the collector, though
 
18
use of those files for a purpose other than building the collector may
 
19
require the resulting code to be covered by the GPL.
 
20
 
 
21
For more details and the names of other contributors, see the
 
22
doc/README* files and include/gc.h.  This file describes typical use of
 
23
the collector on a machine that is already supported.
 
24
 
 
25
For the version number, see doc/README or version.h.
 
26
 
 
27
INSTALLATION:
 
28
Under UN*X, Linux:
 
29
Alternative 1 (the old way): type "make test" in this directory.
 
30
        Link against gc.a.
 
31
 
 
32
Alternative 2 (the new way): type
 
33
        "./configure --prefix=<dir>; make; make check; make install".
 
34
        Link against <dir>/lib/libgc.a or <dir>/lib/libgc.so.
 
35
        See README.autoconf for details
 
36
 
 
37
Under OS/2 or Windows 95, 98, Me, NT, or 2000:
 
38
copy the appropriate makefile to MAKEFILE, read it, and type "nmake test".
 
39
(Under Windows, this assumes you have Microsoft command-line tools
 
40
installed, and have DOS configured with enough environment space to run them.)
 
41
Read the machine specific README in the doc directory if one exists.
 
42
The only way to develop code with the collector for Windows 3.1 is
 
43
to develop under Windows NT or 95+, and then to use win32S.
 
44
 
 
45
If you need thread support, you will need to either follow the special
 
46
platform-dependent instructions (win32), or add a suitable define
 
47
option as described in Makefile.
 
48
 
 
49
If you wish to use the cord (structured string) library, type
 
50
"make cords". (This requires an ANSI C compiler.  You may need
 
51
to redefine CC in the Makefile. The CORD_printf implementation in
 
52
cordprnt.c is known to be less than perfectly portable.  The rest
 
53
of the package should still work.)
 
54
 
 
55
If you wish to use the collector from C++, type
 
56
"make c++".  These add further files to gc.a and to the include
 
57
subdirectory.  See cord/cord.h and include/gc_cpp.h.
 
58
 
 
59
TYPICAL USE:
 
60
Include "gc.h" from the include subdirectory.  Link against the
 
61
appropriate library ("gc.a" under UN*X).  Replace calls to malloc
 
62
by calls to GC_MALLOC, and calls to realloc by calls to GC_REALLOC.
 
63
If the object is known to never contain pointers, use GC_MALLOC_ATOMIC
 
64
instead of GC_MALLOC.
 
65
 
 
66
Define GC_DEBUG before including gc.h for additional checking.
 
67
 
 
68
More documentation on the collector interface can be found at
 
69
http://www.hpl.hp.com/personal/Hans_Boehm/gc/gcinterface.html,
 
70
in doc/README, and in include/gc.h .
 
71
 
 
72
WARNINGS:
 
73
 
 
74
Do not store the only pointer to an object in memory allocated
 
75
with system malloc, since the collector usually does not scan
 
76
memory allocated in this way.
 
77
 
 
78
Use with threads may be supported on your system, but requires the
 
79
collector to be built with thread support.  See Makefile.  The collector
 
80
does not guarantee to scan thread-local storage (e.g. of the kind
 
81
accessed with pthread_getspecific()).  The collector does scan
 
82
thread stacks though, so generally the best solution is to ensure that
 
83
any pointers stored in thread-local storage are also stored on the
 
84
thread's stack for the duration of their lifetime.
 
85