/usr/share/mozart/doc/system/node79.html is in mozart-doc 1.4.0-8ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD><TITLE>26 Memory Management: Finalize</TITLE><LINK href="ozdoc.css" rel="stylesheet" type="text/css"></HEAD><BODY><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node78.html#chapter.errorformatters"><< Prev</A></TD><TD><A href="index.html">- Up -</A></TD><TD><A href="node80.html#chapter.system">Next >></A></TD></TR></TABLE><DIV id="chapter.finalize"><H1><A name="chapter.finalize">26 Memory Management: <CODE>Finalize</CODE></A></H1><P>The finalization facility gives the programmer the ability to process an Oz value when it is discovered (during garbage collection) that it has otherwise become unreachable. This is often used to release native resources held or encapsulated by said value.</P><P>Native functors and extension classes make it very easy to extend Oz with new interfaces to arbitrary resources. Typically, the access to a resource will be encapsulated into a data-structure that is an instance of an extension class and we would like the resource to be automatically released when the data-structure is no longer being referenced and can be garbage collected. For example: </P><UL><LI><P>we may encapsulate a handle to access a database: when the handle is garbage collected, we would like the connection to the database to be automatically closed. </P></LI><LI><P>we may encapsulate a pointer to malloc'ed memory, e.g. for a large bitmap to be manipulated by native DLLs: when this is no longer referenced, we would like the memory to be automatically freed. </P></LI></UL><P> This is the purpose of <EM>finalization</EM>: to execute a cleanup action when a computational object is no longer referenced. </P><P>Mozart proposes two finalization mechanisms, one being <EM>pre-mortem</EM>, and the other one being <EM>post-mortem</EM>. The pre-mortem finalization facility was inspired by the article <A href="ftp://ftp.cs.indiana.edu/pub/scheme-repository/doc/pubs/guardians.ps.gz">Guardians in a Generation-Based Garbage Collector</A> (R. Kent Dybvig, Carl Bruggeman, David Eby, June 1993). It is built on top of weak dictionaries (<A href="../base/weakdictionary.html#section.chunks.weakdictionaries">Section 9.4 of ``The Oz Base Environment''</A>): each weak dictionary is associated with a <EM>finalization stream</EM> on which pairs <CODE>Key<SPAN class="keyword">#</SPAN>Value</CODE> appear when <CODE>Value</CODE> becomes unreachable except through one or more weak dictionaries. </P><P>We recommend to use the post-mortem finalization facility when possible. The reason is that it gives stronger guarantees: upon finalization, there is no possibility for a value to remain in memory, it is already gone. Except, of course, if the value is brought back in memory via distribution or unpickling (<A href="node57.html#chapter.pickle">Chapter 22</A>). </P><P>Note that since instances of the same stateless value are indistinguishable, we cannot tell the difference between one instance of the integer 7 and another one. Thus, the question of whether such an instance is unreachable or whether it is an identical copy of it which is unreachable can usually not be answered. Also, since these values are indistinguishable, the engine is in principle licensed to either duplicate or merge them at its discretion (duplication actually occurs when such values are distributed to other sites). For this reason, finalization only makes sense for datatypes with token equality, i. e. where the identity of an instance is unique. Stateless values with structural equality are treated by the finalization mechanism as if they were unreachable (i. e. as if the weak dictionary contained a copy) and will be subjected to finalization at the very next garbage collection. One exception are atoms: since they remain in the global atom table, they are currently considered to always be reachable. This might change if we implement garbage collection of the atom table. </P><H2><A name="label881">26.1 Pre-mortem finalization facilities</A></H2><P> </P><DL><DT><CODE>Finalize<SPAN class="keyword">.</SPAN>guardian</CODE> <A name="label882"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Finalize<SPAN class="keyword">.</SPAN>guardian </CODE><CODE>+<I>Finalizer</I></CODE><CODE> </CODE><CODE>?<I>Register</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>This takes as input a 1-ary procedure <CODE>Finalizer</CODE> and returns a 1-ary procedure <CODE>Register</CODE> representing a new guardian. A value <CODE>X</CODE> can be registered in the guardian using: </P><BLOCKQUOTE class="code"><CODE>{Register X}</CODE></BLOCKQUOTE><P> Thereafter, when <CODE>X</CODE> becomes unreachable except through a weak dictionary (e. g. a guardian), at the next garbage collection <CODE>X</CODE> is removed from the guardian and the following is eventually executed: </P><BLOCKQUOTE class="code"><CODE>{Finalizer X}</CODE></BLOCKQUOTE><P> We say eventually because the finalization thread is subject to the same fair scheduling as any other thread. Note that the value <CODE><I>X</I></CODE> has still not been garbage collected; only at the next garbage collection after the call to <CODE><I>Finalizer</I></CODE> has returned, and assuming <CODE><I>Value</I></CODE> is no longer referenced at all, not even by the guardian, will it really be garbage collected.</P><DIV class="danger"><P class="margin"><IMG align="top" alt="Danger" src="danger.gif"></P><P>The <CODE><I>Register</I></CODE> procedure cannot be used in a (subordinated) space other than where <CODE><I>Finalize.guardian</I></CODE> has been called. Keep in mind that it probably doesn't make sense to create a guardian in a non-toplevel space because a space can become failed. When this happens, everything in the space is discarded, including the guardians, which means the values registered in them will never be finalized. </P></DIV></DD><DT><CODE>Finalize<SPAN class="keyword">.</SPAN>register</CODE> <A name="label883"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Finalize<SPAN class="keyword">.</SPAN>register </CODE><CODE>+<I>Value</I></CODE><CODE> </CODE><CODE>+<I>Handler</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>This is a slightly different interface that allows to register simultaneously a <CODE><I>Value</I></CODE> and a corresponding finalizer procedure <CODE><I>Handler</I></CODE>. After <CODE><I>Value</I></CODE> becomes otherwise unreachable, <CODE>{</CODE><CODE><I>Handler</I></CODE><CODE> </CODE><CODE><I>Value</I></CODE><CODE>}</CODE> is eventually executed. </P></DD><DT><CODE>Finalize<SPAN class="keyword">.</SPAN>everyGC</CODE> <A name="label884"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Finalize<SPAN class="keyword">.</SPAN>everyGC </CODE><CODE>+<I>P/0</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>This simply registers a 0-ary procedure to be invoked after each garbage collection. Note that you cannot rely on how soon after the garbage collection this procedure will really be invoked: it is in principle possible that the call may only be scheduled several garbage collections later if the system has an incredibly large number of live threads and generates tons of garbage. It is instructive to look at the definition of <CODE>EveryGC</CODE>: </P><BLOCKQUOTE class="code"><CODE><SPAN class="keyword">proc</SPAN><SPAN class="variablename"> </SPAN>{<SPAN class="functionname">EveryGC</SPAN> P}<BR> <SPAN class="keyword">proc</SPAN><SPAN class="variablename"> </SPAN>{<SPAN class="functionname">DO</SPAN> _} {P} {Finalize<SPAN class="keyword">.</SPAN>register DO DO} <SPAN class="keyword">end</SPAN> <BR><SPAN class="keyword">in</SPAN> {Finalize<SPAN class="keyword">.</SPAN>register DO DO} <SPAN class="keyword">end</SPAN></CODE></BLOCKQUOTE><P> in other words, we create a procedure <CODE>DO</CODE> and register it using itself as its own handler. When invoked, it calls <CODE>P</CODE> and registers itself again. </P></DD></DL><P></P><H2><A name="label885">26.2 Post-mortem finalization facilities</A></H2><P> </P><DL><DT><CODE>Finalize<SPAN class="keyword">.</SPAN>postmortem</CODE> <A name="label886"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{Finalize<SPAN class="keyword">.</SPAN>postmortem </CODE><CODE><I>X</I></CODE><CODE> </CODE><CODE>+<I>P</I></CODE><CODE> </CODE><CODE><I>Y</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>This statement registers the value <CODE><I>X</I></CODE> for post-mortem finalization. <CODE><I>X</I></CODE> and <CODE><I>Y</I></CODE> can be any value or variable, while <CODE><I>P</I></CODE> must be a port. Once the garbage collector detects that <CODE><I>X</I></CODE> has become unreachable, it sends the value <CODE><I>Y</I></CODE> on the port <CODE><I>P</I></CODE>. In other words, it looks like the statement <CODE>{Send </CODE><CODE><I>P</I></CODE><CODE> </CODE><CODE><I>Y</I></CODE><CODE>}</CODE> is executed automatically once <CODE><I>X</I></CODE> disappears from memory. </P></DD></DL><P></P></DIV><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node78.html#chapter.errorformatters"><< Prev</A></TD><TD><A href="index.html">- Up -</A></TD><TD><A href="node80.html#chapter.system">Next >></A></TD></TR></TABLE><HR><ADDRESS><A href="http://www.ps.uni-sb.de/~duchier/">Denys Duchier</A>, <A href="http://www.ps.uni-sb.de/~kornstae/">Leif Kornstaedt</A>, <A href="http://www.ps.uni-sb.de/~homik/">Martin Homik</A>, <A href="http://www.ps.uni-sb.de/~tmueller/">Tobias Müller</A>, <A href="http://www.ps.uni-sb.de/~schulte/">Christian Schulte</A> and <A href="http://www.info.ucl.ac.be/~pvr">Peter Van Roy</A><BR><SPAN class="version">Version 1.4.0 (20110908185330)</SPAN></ADDRESS></BODY></HTML>
|