From 069d2bc97ad890cc8dca3e366c5a400075bfc7bd Mon Sep 17 00:00:00 2001
From: Gareth Rees <gdr@ravenbrook.com>
Date: Thu, 20 Oct 2016 13:59:21 +0100
Subject: [PATCH] Move design.mps.finalize from old to current.

Copied from Perforce
 Change: 192663
 ServerID: perforce.ravenbrook.com
---
 mps/design/finalize.txt            | 13 +++++++++++--
 mps/manual/source/design/index.rst |  1 +
 mps/manual/source/design/old.rst   |  1 -
 3 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/mps/design/finalize.txt b/mps/design/finalize.txt
index 9f14395591c..2553df81cc2 100644
--- a/mps/design/finalize.txt
+++ b/mps/design/finalize.txt
@@ -6,7 +6,7 @@ Finalization
 :Tag: design.mps.finalize
 :Author: David Jones
 :Date: 1997-02-14
-:Status: incomplete design
+:Status: complete design
 :Revision: $Id$
 :Copyright: See `Copyright and License`_.
 :Index terms: pair: finalization; design
@@ -74,7 +74,8 @@ then ``ArenaDestroy()`` destroys the final pool.
 _`.impl.access`: ``mps_message_finalization_ref()`` needs to access
 the finalization message to retrieve the reference and then write it
 to where the client asks. This must be done carefully, in order to
-avoid breaking the invariants or creating a hidden root.
+avoid hitting the write barrier or invalidating collection invariants
+such as the segment summary.
 
 _`.impl.invariants`: We protect the invariants by using special
 routines ``ArenaRead()`` and ``ArenaPoke()`` to read and write the
@@ -90,6 +91,14 @@ reference. This works as long as there's no write-barrier collection.
     write-barrier, it's functionally identical to ``ArenaPoke()``.
     Pekka P. Pirinen, 1997-12-09.
 
+.. note::
+
+    There is no need to maintain a write barrier on segments belonging
+    to the MRG pool, as these segments are never given to the mutator.
+    See job004030_.
+
+    .. _job004030: https://www.ravenbrook.com/project/mps/issue/job004030/
+
 
 External interface
 ------------------
diff --git a/mps/manual/source/design/index.rst b/mps/manual/source/design/index.rst
index 3b397d39745..072ff4d84d1 100644
--- a/mps/manual/source/design/index.rst
+++ b/mps/manual/source/design/index.rst
@@ -15,6 +15,7 @@ Design
     critical-path
     exec-env
     failover
+    finalize
     freelist
     guide.hex.trans
     guide.impl.c.format
diff --git a/mps/manual/source/design/old.rst b/mps/manual/source/design/old.rst
index 7e53ebc2255..ba3f3e4cbd5 100644
--- a/mps/manual/source/design/old.rst
+++ b/mps/manual/source/design/old.rst
@@ -22,7 +22,6 @@ Old design
     check
     collection
     diag
-    finalize
     fix
     io
     lib