← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/virtualbox-ose/gutsy

« back to all changes in this revision

Viewing changes to src/libs/xpcom18a4/nsprpub/lib/msgc/include/prgc.h

  • Committer: Bazaar Package Importer
  • Author(s): Steve Kowalik
  • Date: 2007-09-08 16:44:58 UTC
  • Revision ID: james.westby@ubuntu.com-20070908164458-wao29470vqtr8ksy
Tags: upstream-1.5.0-dfsg2
Import upstream version 1.5.0-dfsg2

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/libs/xpcom18a4/nsprpub/lib/msgc/include/prgc.h
 
1
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
 
2
/* ***** BEGIN LICENSE BLOCK *****
 
3
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 
4
 *
 
5
 * The contents of this file are subject to the Mozilla Public License Version
 
6
 * 1.1 (the "License"); you may not use this file except in compliance with
 
7
 * the License. You may obtain a copy of the License at
 
8
 * http://www.mozilla.org/MPL/
 
9
 *
 
10
 * Software distributed under the License is distributed on an "AS IS" basis,
 
11
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 
12
 * for the specific language governing rights and limitations under the
 
13
 * License.
 
14
 *
 
15
 * The Original Code is the Netscape Portable Runtime (NSPR).
 
16
 *
 
17
 * The Initial Developer of the Original Code is
 
18
 * Netscape Communications Corporation.
 
19
 * Portions created by the Initial Developer are Copyright (C) 1998-2000
 
20
 * the Initial Developer. All Rights Reserved.
 
21
 *
 
22
 * Contributor(s):
 
23
 *
 
24
 * Alternatively, the contents of this file may be used under the terms of
 
25
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 
26
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 
27
 * in which case the provisions of the GPL or the LGPL are applicable instead
 
28
 * of those above. If you wish to allow use of your version of this file only
 
29
 * under the terms of either the GPL or the LGPL, and not to allow others to
 
30
 * use your version of this file under the terms of the MPL, indicate your
 
31
 * decision by deleting the provisions above and replace them with the notice
 
32
 * and other provisions required by the GPL or the LGPL. If you do not delete
 
33
 * the provisions above, a recipient may use your version of this file under
 
34
 * the terms of any one of the MPL, the GPL or the LGPL.
 
35
 *
 
36
 * ***** END LICENSE BLOCK ***** */
 
37
 
 
38
#ifndef prgc_h___
 
39
#define prgc_h___
 
40
 
 
41
/*
 
42
** API to NSPR gc memory system.
 
43
*/
 
44
#include "prtypes.h"
 
45
#include "prmon.h"
 
46
#include "prthread.h"
 
47
#include <stdio.h>
 
48
 
 
49
#if defined(WIN16)
 
50
#define GCPTR __far
 
51
#else
 
52
#define GCPTR
 
53
#endif
 
54
 
 
55
 
 
56
PR_BEGIN_EXTERN_C
 
57
 
 
58
/*
 
59
** Initialize the garbage collector.
 
60
**     "flags" is the trace flags (see below).
 
61
**     "initialHeapSize" is the initial size of the heap and may be zero
 
62
**        if the default is desired.
 
63
**    "segmentSize" is the size of each segment of memory added to the
 
64
**       heap when the heap is grown.
 
65
*/
 
66
PR_EXTERN(void) PR_InitGC(
 
67
    PRWord flags, PRInt32 initialHeapSize, PRInt32 segmentSize, PRThreadScope scope);
 
68
 
 
69
/*
 
70
** Shuts down gc and frees up all memory associated with it. 
 
71
*/
 
72
PR_EXTERN(void) PR_ShutdownGC(PRBool finalizeOnExit);
 
73
 
 
74
/*
 
75
** This walk function will be called for every gc object in the
 
76
** heap as it is walked. If it returns non-zero, the walk is terminated.
 
77
*/
 
78
typedef PRInt32 (*PRWalkFun)(void GCPTR* obj, void* data);
 
79
 
 
80
/*
 
81
** GC Type record. This defines all of the GC operations used on a
 
82
** particular object type. These structures are passed to
 
83
** PR_RegisterType.
 
84
*/
 
85
typedef struct GCType {
 
86
    /*
 
87
    ** Scan an object that is in the GC heap and call GCInfo.livePointer
 
88
    ** on all of the pointers in it. If this slot is null then the object
 
89
    ** won't be scanned (i.e. it has no embedded pointers).
 
90
    */
 
91
    void (PR_CALLBACK *scan)(void GCPTR *obj);
 
92
 
 
93
    /*
 
94
    ** Finalize an object that has no references. This is called by the
 
95
    ** GC after it has determined where the object debris is but before
 
96
    ** it has moved the debris to the logical "free list". The object is
 
97
    ** marked alive for this call and removed from the list of objects
 
98
    ** that need finalization (finalization only happens once for an
 
99
    ** object). If this slot is null then the object doesn't need
 
100
    ** finalization.
 
101
    */
 
102
    void (PR_CALLBACK *finalize)(void GCPTR *obj);
 
103
 
 
104
    /*
 
105
    ** Dump out an object during a PR_DumpGCHeap(). This is used as a
 
106
    ** debugging tool.
 
107
    */
 
108
    void (PR_CALLBACK *dump)(FILE *out, void GCPTR *obj, PRBool detailed, PRIntn indentLevel);
 
109
 
 
110
    /*
 
111
    ** Add object to summary table.
 
112
    */
 
113
    void (PR_CALLBACK *summarize)(void GCPTR *obj, PRUint32 bytes);
 
114
 
 
115
    /*
 
116
    ** Free hook called by GC when the object is being freed.
 
117
    */
 
118
    void (PR_CALLBACK *free)(void *obj);
 
119
 
 
120
    /* Weak pointer support: If the object has a weak pointer (Note:
 
121
       at most one), this function is used to get the weak link's
 
122
       offset from the start of the body of a gc object */
 
123
    PRUint32 (PR_CALLBACK *getWeakLinkOffset)(void *obj);
 
124
 
 
125
    /* Descriptive character for dumping this GCType */
 
126
    char kindChar;
 
127
 
 
128
    /*
 
129
    ** Walker routine. This routine should apply fun(obj->ptr, data)
 
130
    ** for every gc pointer within the object.
 
131
    */
 
132
    PRInt32 (PR_CALLBACK *walk)(void GCPTR *obj, PRWalkFun fun, void* data);
 
133
} GCType;
 
134
 
 
135
/*
 
136
** This data structure must be added as the hash table passed to 
 
137
** the summarize method of GCType.
 
138
*/ 
 
139
typedef struct PRSummaryEntry {
 
140
    void* clazz;
 
141
    PRInt32 instancesCount;
 
142
    PRInt32 totalSize;
 
143
} PRSummaryEntry;
 
144
 
 
145
/*
 
146
** This function pointer must be registered by users of nspr
 
147
** to produce the finally summary after all object in the
 
148
** heap have been visited.
 
149
*/
 
150
typedef void (PR_CALLBACK *PRSummaryPrinter)(FILE *out, void* closure);
 
151
 
 
152
PR_EXTERN(void) PR_CALLBACK PR_RegisterSummaryPrinter(PRSummaryPrinter fun, void* closure);
 
153
 
 
154
typedef void PR_CALLBACK GCRootFinder(void *arg);
 
155
typedef void PR_CALLBACK GCBeginFinalizeHook(void *arg);
 
156
typedef void PR_CALLBACK GCEndFinalizeHook(void *arg);
 
157
typedef void PR_CALLBACK GCBeginGCHook(void *arg);
 
158
typedef void PR_CALLBACK GCEndGCHook(void *arg);
 
159
 
 
160
typedef enum { PR_GCBEGIN, PR_GCEND } GCLockHookArg;
 
161
 
 
162
typedef void PR_CALLBACK GCLockHookFunc(GCLockHookArg arg1, void *arg2);
 
163
 
 
164
typedef struct GCLockHook GCLockHook;
 
165
 
 
166
struct GCLockHook {
 
167
  GCLockHookFunc* func;
 
168
  void* arg;
 
169
  GCLockHook* next;
 
170
  GCLockHook* prev;
 
171
};
 
172
 
 
173
 
 
174
/*
 
175
** Hooks which are called at the beginning and end of the GC process.
 
176
** The begin hooks are called before the root finding step. The hooks are
 
177
** called with threading disabled, so it is now allowed to re-enter the
 
178
** kernel. The end hooks are called after the gc has finished but before
 
179
** the finalizer has run.
 
180
*/
 
181
PR_EXTERN(void) PR_CALLBACK PR_SetBeginGCHook(GCBeginGCHook *hook, void *arg);
 
182
PR_EXTERN(void) PR_CALLBACK PR_GetBeginGCHook(GCBeginGCHook **hook, void **arg);
 
183
PR_EXTERN(void) PR_CALLBACK PR_SetEndGCHook(GCBeginGCHook *hook, void *arg);
 
184
PR_EXTERN(void) PR_CALLBACK PR_GetEndGCHook(GCEndGCHook **hook, void **arg);
 
185
 
 
186
/*
 
187
** Called before SuspendAll is called by dogc, so that GC thread can hold
 
188
** all the locks before hand to avoid any deadlocks
 
189
*/
 
190
 
 
191
/*
 
192
PR_EXTERN(void) PR_SetGCLockHook(GCLockHook *hook, void *arg);
 
193
PR_EXTERN(void) PR_GetGCLockHook(GCLockHook **hook, void **arg);
 
194
*/
 
195
 
 
196
PR_EXTERN(int) PR_RegisterGCLockHook(GCLockHookFunc *hook, void *arg);
 
197
 
 
198
/*
 
199
** Hooks which are called at the beginning and end of the GC finalization
 
200
** process. After the GC has identified all of the dead objects in the
 
201
** heap, it looks for objects that need finalization. Before it calls the
 
202
** first finalization proc (see the GCType structure above) it calls the
 
203
** begin hook. When it has finalized the last object it calls the end
 
204
** hook.
 
205
*/
 
206
PR_EXTERN(void) PR_SetBeginFinalizeHook(GCBeginFinalizeHook *hook, void *arg);
 
207
PR_EXTERN(void) PR_GetBeginFinalizeHook(GCBeginFinalizeHook **hook, void **arg);
 
208
PR_EXTERN(void) PR_SetEndFinalizeHook(GCBeginFinalizeHook *hook, void *arg);
 
209
PR_EXTERN(void) PR_GetEndFinalizeHook(GCEndFinalizeHook **hook, void **arg);
 
210
 
 
211
/*
 
212
** Register a GC type. Return's the index into the GC internal type
 
213
** table. The returned value is passed to PR_AllocMemory. After the call,
 
214
** the "type" memory belongs to the GC (the caller must not free it or
 
215
** change it).
 
216
*/
 
217
PR_EXTERN(PRInt32) PR_RegisterType(GCType *type);
 
218
 
 
219
/*
 
220
** Register a root finder with the collector. The collector will call
 
221
** these functions to identify all of the roots before collection
 
222
** proceeds. "arg" is passed to the function when it is called.
 
223
*/
 
224
PR_EXTERN(PRStatus) PR_RegisterRootFinder(GCRootFinder func, char *name, void *arg);
 
225
 
 
226
/*
 
227
** Allocate some GC'able memory. The object must be at least bytes in
 
228
** size. The type index function for the object is specified. "flags"
 
229
** specifies some control flags. If PR_ALLOC_CLEAN is set then the memory
 
230
** is zero'd before being returned. If PR_ALLOC_DOUBLE is set then the
 
231
** allocated memory is double aligned.
 
232
**
 
233
** Any memory cell that you store a pointer to something allocated by
 
234
** this call must be findable by the GC. Use the PR_RegisterRootFinder to
 
235
** register new places where the GC will look for pointers into the heap.
 
236
** The GC already knows how to scan any NSPR threads or monitors.
 
237
*/
 
238
PR_EXTERN(PRWord GCPTR *)PR_AllocMemory(
 
239
    PRWord bytes, PRInt32 typeIndex, PRWord flags);
 
240
PR_EXTERN(PRWord GCPTR *)PR_AllocSimpleMemory(
 
241
    PRWord bytes, PRInt32 typeIndex);
 
242
 
 
243
/*
 
244
** This function can be used to cause PR_AllocMemory to always return
 
245
** NULL. This may be useful in low memory situations when we're trying to
 
246
** shutdown applets.
 
247
*/
 
248
PR_EXTERN(void) PR_EnableAllocation(PRBool yesOrNo);
 
249
 
 
250
/* flags bits */
 
251
#define PR_ALLOC_CLEAN 0x1
 
252
#define PR_ALLOC_DOUBLE 0x2
 
253
#define PR_ALLOC_ZERO_HANDLE 0x4              /* XXX yes, it's a hack */
 
254
 
 
255
/*
 
256
** Force a garbage collection right now. Return when it completes.
 
257
*/
 
258
PR_EXTERN(void) PR_GC(void);
 
259
 
 
260
/*
 
261
** Force a finalization right now. Return when finalization has
 
262
** completed. Finalization completes when there are no more objects
 
263
** pending finalization. This does not mean there are no objects in the
 
264
** gc heap that will need finalization should a collection be done after
 
265
** this call.
 
266
*/
 
267
PR_EXTERN(void) PR_ForceFinalize(void);
 
268
 
 
269
/*
 
270
** Dump the GC heap out to the given file. This will stop the system dead
 
271
** in its tracks while it is occuring.
 
272
*/
 
273
PR_EXTERN(void) PR_DumpGCHeap(FILE *out, PRBool detailed);
 
274
 
 
275
/*
 
276
** Wrapper for PR_DumpGCHeap
 
277
*/
 
278
PR_EXTERN(void) PR_DumpMemory(PRBool detailed);
 
279
 
 
280
/*
 
281
** Dump summary of objects allocated.
 
282
*/
 
283
PR_EXTERN(void) PR_DumpMemorySummary(void);
 
284
 
 
285
/*
 
286
** Dump the application heaps.
 
287
*/
 
288
PR_EXTERN(void) PR_DumpApplicationHeaps(void);
 
289
 
 
290
/*
 
291
** Helper function used by dump routines to do the indentation in a
 
292
** consistent fashion.
 
293
*/
 
294
PR_EXTERN(void) PR_DumpIndent(FILE *out, PRIntn indent);
 
295
 
 
296
/*
 
297
** The GCInfo structure contains all of the GC state...
 
298
**
 
299
** busyMemory:
 
300
**    The amount of GC heap memory that is busy at this instant. Busy
 
301
**    doesn't mean alive, it just means that it has been
 
302
**    allocated. Immediately after a collection busy means how much is
 
303
**    alive.
 
304
**
 
305
** freeMemory:
 
306
**    The amount of GC heap memory that is as yet unallocated.
 
307
**
 
308
** allocMemory:
 
309
**    The sum of free and busy memory in the GC heap.
 
310
**
 
311
** maxMemory:
 
312
**    The maximum size that the GC heap is allowed to grow.
 
313
**
 
314
** lowSeg:
 
315
**    The lowest segment currently used in the GC heap.
 
316
**
 
317
** highSeg:
 
318
**    The highest segment currently used in the GC heap.  
 
319
**    The lowSeg and highSeg members are used for a "quick test" of whether 
 
320
**    a pointer falls within the GC heap. [ see GC_IN_HEAP(...) ]
 
321
**
 
322
** lock:
 
323
**    Monitor used for syncronization within the GC.
 
324
**
 
325
** finalizer:
 
326
**    Thread in which the GC finalizer is running.
 
327
**
 
328
** liveBlock:
 
329
**    Object scanning functions call through this function pointer to
 
330
**    register a potential block of pointers with the collector. (This is
 
331
**    currently not at all different than processRoot.)
 
332
**
 
333
** livePointer:
 
334
**    Object scanning functions call through this function pointer to
 
335
**    register a single pointer with the collector.
 
336
**
 
337
** processRootBlock:
 
338
**    When a root finder identifies a root it should call through this
 
339
**    function pointer so that the GC can process the root. The call takes
 
340
**    a base address and count which the gc will examine for valid heap
 
341
**    pointers.
 
342
**
 
343
** processRootPointer:
 
344
**    When a root finder identifies a root it should call through this
 
345
**    function pointer so that the GC can process the root. The call takes
 
346
**    a single pointer value.
 
347
*/
 
348
typedef struct GCInfoStr {
 
349
    PRWord  flags;         /* trace flags (see below)               */
 
350
    PRWord  busyMemory;    /* memory in use right now               */
 
351
    PRWord  freeMemory;    /* memory free right now                 */
 
352
    PRWord  allocMemory;   /* sum of busy & free memory             */
 
353
    PRWord  maxMemory;     /* max memory we are allowed to allocate */
 
354
    PRWord *lowSeg;        /* lowest segment in the GC heap         */
 
355
    PRWord *highSeg;       /* higest segment in the GC heap         */
 
356
 
 
357
    PRMonitor *lock;
 
358
    PRThread  *finalizer;
 
359
 
 
360
    void (PR_CALLBACK *liveBlock)(void **base, PRInt32 count);
 
361
    void (PR_CALLBACK *livePointer)(void *ptr);
 
362
    void (PR_CALLBACK *processRootBlock)(void **base, PRInt32 count);
 
363
    void (PR_CALLBACK *processRootPointer)(void *ptr);
 
364
    FILE* dumpOutput;
 
365
#ifdef GCTIMINGHOOK
 
366
    void (*gcTimingHook)(int32 gcTime);
 
367
#endif
 
368
} GCInfo;
 
369
 
 
370
PR_EXTERN(GCInfo *) PR_GetGCInfo(void);
 
371
PR_EXTERN(PRBool) PR_GC_In_Heap(void GCPTR *object);
 
372
 
 
373
/*
 
374
** Simple bounds check to see if a pointer is anywhere near the GC heap.
 
375
** Used to avoid calls to PR_ProcessRoot and GCInfo.livePointer by object
 
376
** scanning code.
 
377
*/
 
378
#if !defined(XP_PC) || defined(_WIN32)
 
379
#define GC_IN_HEAP(_info, _p) (((PRWord*)(_p) >= (_info)->lowSeg) && \
 
380
                               ((PRWord*)(_p) <  (_info)->highSeg))
 
381
#else
 
382
/*
 
383
** The simple bounds check, above, doesn't work in Win16, because we don't
 
384
** maintain: lowSeg == MIN(all segments) and highSeg == MAX(all segments).
 
385
** So we have to do a little better.
 
386
*/
 
387
#define GC_IN_HEAP(_info, _p) PR_GC_In_Heap(_p)
 
388
#endif
 
389
 
 
390
PR_EXTERN(PRWord) PR_GetObjectHeader(void *ptr);
 
391
 
 
392
PR_EXTERN(PRWord) PR_SetObjectHeader(void *ptr, PRWord newUserBits);
 
393
 
 
394
/************************************************************************/
 
395
 
 
396
/* Trace flags (passed to PR_InitGC or in environment GCLOG) */
 
397
#define GC_TRACE    0x0001
 
398
#define GC_ROOTS    0x0002
 
399
#define GC_LIVE     0x0004
 
400
#define GC_ALLOC    0x0008
 
401
#define GC_MARK     0x0010
 
402
#define GC_SWEEP    0x0020
 
403
#define GC_DEBUG    0x0040
 
404
#define GC_FINAL    0x0080
 
405
 
 
406
#if defined(DEBUG_kipp) || defined(DEBUG_warren)
 
407
#define GC_CHECK    0x0100
 
408
#endif
 
409
 
 
410
#ifdef DEBUG
 
411
#define GCTRACE(x, y) if (PR_GetGCInfo()->flags & x) GCTrace y
 
412
PR_EXTERN(void) GCTrace(char *fmt, ...);
 
413
#else
 
414
#define GCTRACE(x, y)
 
415
#endif
 
416
 
 
417
PR_END_EXTERN_C
 
418
 
 
419
#endif /* prgc_h___ */