From: Ivan Maidanski Date: Mon, 26 Dec 2011 07:47:35 +0000 (+0400) Subject: Complete GC documentation with 'finalization' topic X-Git-Tag: gc7_3alpha2~272 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=d6982ea99a5bcd6929e73d653d9105e624e42955;p=gc Complete GC documentation with 'finalization' topic * doc/finalization.html: New file (copy file from BDWGC site). * Makefile.direct (DOC_FILES): Add "doc/finalization.html" entry. * doc.am (dist_pkgdata_DATA): Likewise. * doc/gcdescr.html: Convert absolute references to finalization.html file to local ones. * doc/gcinterface.html: Likewise. * doc/overview.html: Likewise. --- diff --git a/Makefile.direct b/Makefile.direct index a8168b50..cfdecfb6 100644 --- a/Makefile.direct +++ b/Makefile.direct @@ -112,7 +112,7 @@ SRCS= $(CSRCS) \ DOC_FILES= README.QUICK TODO doc/README.Mac doc/README.OS2 \ doc/README.amiga doc/README.cords doc/debugging.html \ - doc/porting.html doc/overview.html \ + doc/finalization.html doc/porting.html doc/overview.html \ doc/README.dj doc/README.hp doc/README.linux doc/README.rs6000 \ doc/README.sgi doc/README.solaris2 doc/README.uts \ doc/README.win32 doc/barrett_diagram \ diff --git a/doc/doc.am b/doc/doc.am index 36e410ba..27c4691a 100644 --- a/doc/doc.am +++ b/doc/doc.am @@ -38,6 +38,7 @@ dist_pkgdata_DATA = \ doc/README.win64 \ doc/barrett_diagram \ doc/debugging.html \ + doc/finalization.html \ doc/gc.man \ doc/gcdescr.html \ doc/gcinterface.html \ diff --git a/doc/finalization.html b/doc/finalization.html new file mode 100644 index 00000000..3733c0c4 --- /dev/null +++ b/doc/finalization.html @@ -0,0 +1,190 @@ + + +Finalization in the Boehm-Demers-Weiser collector + + +

Finalization

+Many garbage collectors provide a facility for executing user code +just before an object is collected. This can be used to reclaim any +system resources or non-garbage-collected memory associated with the +object. +Experience has shown that this can be a useful facility. +It is indispensable in cases in which system resources are embedded +in complex data structures (e.g. file descriptors +in the cord package). +

+Our collector provides the necessary functionality through +GC_register_finalizer in +gc.h, or by +inheriting from gc_cleanup +in gc_cpp.h. +

+However, finalization should not be used in the same way as C++ +destructors. In well-written programs there will typically be +very few uses of finalization. (Garbage collected programs that +interact with explicitly memory-managed libraries may be an exception.) +

+In general the following guidelines should be followed: +

+Actions that must be executed promptly do not belong in finalizers. +They should be handled by explicit calls in the code (or C++ +destructors if you prefer). If you expect the action to occur at +a specific point, this is probably not hard. +
+Finalizers are intended for resource reclamation. +
+Scarce system resources should be managed explicitly whenever +convenient. Use finalizers only as a backup mechanism for the +cases that would be hard to handle explicitly. +
+If scarce resources are managed with finalization, the allocation +routine for that resource (e.g. open for file handles) should force +a garbage collection (two if that doesn't suffice) if it finds itself +short of the resource. +
+If extremely scarce resources are managed by finalization (e.g. +file descriptors on systems which have a limit of 20 open files), +it may be necessary to introduce a descriptor caching scheme to +hide the resource limit. +(E.g., the program would keep real file descriptors +for the 20 most recently used logically open files. +Any other needed files would be closed after saving their state. +They would then be reopened on demand. +Finalization would logically close the file, closing the +real descriptor only if it happened to be cached.) +Note that most modern systems (e.g. Irix®) allow hundreds or +thousands of open files, and this is typically not an issue. +
+Finalization code may +be run anyplace an allocation or other call to the collector +takes place. +In multi-threaded programs, finalizers have to obey the normal +locking conventions to ensure safety. +Code run directly from finalizers should not acquire locks that may +be held during allocation. This restriction can be easily circumvented +by registering a finalizer which enqueues the real action for execution +in a separate thread. +
+In single-threaded code, it is also often easiest to have finalizers +queue actions, which are then explicitly run during an +explicit call by the user's program. +

Topologically Ordered Finalization

+Our conservative garbage collector supports +a form of finalization +(with GC_register_finalizer) +in which objects are finalized in topological +order. If A points to B, and both are registered for +finalization, it is guaranteed the A will be finalized first. +This usually guarantees that finalization procedures see only +unfinalized objects. +

+This decision is often questioned, particularly since it has an obvious +disadvantage. The current implementation finalizes long chains of +finalizable objects one per collection. This is hard to avoid, since +the first finalizer invoked may store a pointer to the rest of the chain +in a global variable, making it accessible again. Or it may mutate the +rest of the chain. +

+Cycles involving one or more finalizable objects are never finalized. +

+Why topological ordering? +

+It is important to keep in mind that the choice of finalization ordering +matters only in relatively rare cases. In spite of the fact that it has +received a lot of discussion, it is not one of the more important +decisions in designing a system. Many, especially smaller, applications +will never notice the difference. Nonetheless, we believe that topologically +ordered finalization is the right choice. +

+To understand the justification, observe that if As +finalization procedure does not refer to B, we could fairly easily have +avoided the dependency. We could have split A into A' +and A'' such that any references to A become references to +A', A' points to A'' but not vice-versa, only fields +needed for finalization are stored in A'', and A'' is enabled +for finalization. (GC_register_disappearing_link provides an +alternative mechanism that does not require breaking up objects.) +

+Thus assume that A actually does need access to B during +finalization. To make things concrete, assume that B is +finalizable because it holds a pointer to a C object, which must be +explicitly deallocated. (This is likely to be one of the most common +uses of finalization.) If B happens to be finalized first, +A will see a dangling pointer during its finalization. But a +principal goal of garbage collection was to avoid dangling pointers. +

+Note that the client program could enforce topological ordering +even if the system didn't. A pointer to B could be stored in +some globally visible place, where it is cleared only by As +finalizer. But this puts the burden to ensure safety back on the +programmer. +

+With topologically ordered finalization, the programmer +can fail to split an object, thus leaving an accidental cycle. This +results in a leak, which is arguably less dangerous than a dangling +pointer. More importantly, it is much easier to diagnose, +since the garbage collector would have to go out of its way not to +notice finalization cycles. It can trivially report them. +

+Furthermore unordered finalization does not really solve the problem +of cycles. Consider the above case in which As +finalization procedure depends on B, and thus a pointer to B +is stored in a global data structure, to be cleared by As finalizer. +If there is an accidental pointer from B back to A, and +thus a cycle, neither B nor A will become unreachable. +The leak is there, just as in the topologically ordered case, but it is +hidden from easy diagnosis. +

+A number of alternative finalization orderings have been proposed, e.g. +based on statically assigned priorities. In our opinion, these are much +more likely to require complex programming discipline to use in a large +modular system. (Some of them, e.g. Guardians proposed by Dybvig, +Bruggeman, and Eby, do avoid some problems which arise in combination +with certain other collection algorithms.) +

+Fundamentally, a garbage collector assumes that objects reachable +via pointer chains may be accessed, and thus should be preserved. +Topologically ordered finalization simply extends this to object finalization; +an finalizable object reachable from another finalizer via a pointer chain +is presumed to be accessible by the finalizer, and thus should not be +finalized. + +

Programming with topological finalization

+Experience with Cedar has shown that cycles or long chains of finalizable +objects are typically not a problem. +Finalizable objects are typically rare. +There are several ways to reduce spurious dependencies between finalizable +objects. Splitting objects as discussed above is one technique. +The collector also provides GC_register_disappearing_link, which +explicitly nils a pointer before determining finalization ordering. +

+Some so-called "operating systems" fail to clean up some resources associated +with a process. These resources must be deallocated at all cost before +process exit whether or not they are still referenced. Probably the best +way to deal with those is by not relying exclusively on finalization. +They should be registered in a table of weak pointers (implemented as +disguised pointers cleared by the finalization procedure that deallocates +the resource). If any references are still left at process exit, they +can be explicitly deallocated then. + +

Getting around topological finalization ordering

+There are certain situations in which cycles between finalizable objects are +genuinely unavoidable. Most notably, C++ compilers introduce self-cycles +to represent inheritance. GC_register_finalizer_ignore_self tells the +finalization part of the collector to ignore self cycles. +This is used by the C++ interface. +

+Finalize.c actually contains an intentionally undocumented mechanism +for registering a finalizable object with user-defined dependencies. +The problem is that this dependency information is also used for memory +reclamation, not just finalization ordering. Thus misuse can result in +dangling pointers even if finalization doesn't create any. +The risk of dangling pointers can be eliminated by building the collector +with -DJAVA_FINALIZATION. This forces objects reachable from finalizers +to be marked, even though this dependency is not considered for finalization +ordering. + + + diff --git a/doc/gcdescr.html b/doc/gcdescr.html index 08ca2a8f..f56b1fcf 100644 --- a/doc/gcdescr.html +++ b/doc/gcdescr.html @@ -407,7 +407,7 @@ object itself becomes marked, we have uncovered a cycle involving the object. This usually results in a warning from the collector. Such objects are not finalized, since it may be unsafe to do so. See the more detailed - discussion of finalization semantics. + discussion of finalization semantics.

Any objects remaining unmarked at the end of this process are added to a queue of objects whose finalizers can be run. Depending on collector diff --git a/doc/gcinterface.html b/doc/gcinterface.html index 83574bb8..eaa038c4 100644 --- a/doc/gcinterface.html +++ b/doc/gcinterface.html @@ -145,7 +145,7 @@ inaccessible. It is not an acceptable method to perform actions that must be performed in a timely fashion. See gc.h for details of the interface. -See here for a more detailed discussion +See here for a more detailed discussion of the design.

Note that an object may become inaccessible before client code is done diff --git a/doc/overview.html b/doc/overview.html index de589235..80d5f312 100644 --- a/doc/overview.html +++ b/doc/overview.html @@ -137,7 +137,7 @@ It provides incremental and generational collection under operating systems which provide the right kind of virtual memory support. (Currently this includes SunOS[45], IRIX, OSF/1, Linux, and Windows, with varying restrictions.) -It allows finalization code +It allows finalization code to be invoked when an object is collected. It can take advantage of type information to locate pointers if such information is provided, but it is usually used without such information.