[commit: ghc] master: Improve the API doc description of the SmallArray primitive types (faddad7)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/faddad7ec6e5738987d5571ad23054a5aa39c193/ghc

>---------------------------------------------------------------

commit faddad7ec6e5738987d5571ad23054a5aa39c193
Author: Duncan Coutts <duncan at well-typed.com>
Date:   Tue Jun 10 13:50:59 2014 +0100

    Improve the API doc description of the SmallArray primitive types
    
    Say how it differs from Array in terms of size and performance.
    These are primitives so it's also ok to talk a bit about implementation
    details like card tables.


>---------------------------------------------------------------

faddad7ec6e5738987d5571ad23054a5aa39c193
 compiler/prelude/primops.txt.pp | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/compiler/prelude/primops.txt.pp b/compiler/prelude/primops.txt.pp
index dfc1421..764ba10 100644
--- a/compiler/prelude/primops.txt.pp
+++ b/compiler/prelude/primops.txt.pp
@@ -843,8 +843,22 @@ primop CasArrayOp  "casArray#" GenPrimOp
 section "Small Arrays"
 
 	{Operations on {\tt SmallArray\#}. A {\tt SmallArray\#} works
-         just like an {\tt Array\#}, except that its implementation is
-         optimized for small arrays (i.e. no more than 128 elements.)}
+         just like an {\tt Array\#}, but with different space use and
+         performance characteristics (that are often useful with small
+         arrays). The {\tt SmallArray\#} and {\tt SmallMutableArray#}
+         lack a `card table'. The purpose of a card table is to avoid
+         having to scan every element of the array on each GC by
+         keeping track of which elements have changed since the last GC
+         and only scanning those that have changed. So the consequence
+         of there being no card table is that the representation is
+         somewhat smaller and the writes are somewhat faster (because
+         the card table does not need to be updated). The disadvantage
+         of course is that for a {\tt SmallMutableArray#} the whole
+         array has to be scanned on each GC. Thus it is best suited for
+         use cases where the mutable array is not long lived, e.g.
+         where a mutable array is initialised quickly and then frozen
+         to become an immutable {\tt SmallArray\#}.
+        }
 
 ------------------------------------------------------------------------