From 3772a04825f800858a15fc3b4e5fc0ff78fe600a Mon Sep 17 00:00:00 2001 From: Gareth Rees Date: Tue, 1 Sep 2015 13:06:05 +0100 Subject: [PATCH] Add note about choice of base/client pointer representation. Copied from Perforce Change: 188193 ServerID: perforce.ravenbrook.com --- mps/manual/source/topic/format.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/mps/manual/source/topic/format.rst b/mps/manual/source/topic/format.rst index 2fe2b4a4e30..7db5c8a1178 100644 --- a/mps/manual/source/topic/format.rst +++ b/mps/manual/source/topic/format.rst @@ -179,6 +179,20 @@ There are some cautions to be observed when using in-band headers: #. Not all :term:`pool classes` support objects with in-band headers. See the documentation for the pool class. +.. note:: + + A :term:`client program` that allocates objects with + :term:`in-band headers` has to make a choice about how to + represent references to those objects. It can represent them using + :term:`base pointers` (which is convenient for allocation, since + :c:func:`mps_reserve` returns a base pointer, but requires + decoding when scanning) or using :term:`client pointers` (which is + convenient for scanning, since the :term:`scan method` takes a + client pointer, but requires encoding on allocation). Either + approach will work, but :term:`client pointers` are normally the + better choice, since scanning is normally more + performance-critical than allocation. + .. index:: pair: object format; cautions