sort: support stable sorting via ssort and snsort.

For array-like objecgts, these objects use an
array-based merge sort, using an auxiliary array
equal in size to the original array.

To provide the auxiliary array, a new kind of very simple
vector-like object is introduced into the gc module: protected
array.  This looks like a raw dynamic C array of val type,
returned as a val *. Under the hood, there is a heap object
there, which makes the array traversable by the garbage
collector.

The whole point of this exercise is to make the new mergesort
function safe even if the caller-supplied functions misbehave
in such a way that the auxiliary array holds the only
references to heap objects.

* gc.c (struct prot_array): New struct,
(prot_array_cls): New static variable.
(gc_late_init): Register COBJ class, retaining in
prot_array_cls.
(prot_array_mark, prot_array_free): New static functions.
(prot_array_ops): New static structure.
(prot_array_alloc, prot_array_free): New functions.

* gc.h (prot_array_alloc, prot_array_free): Declared.

* lib.c (mergesort, ssort_vec): New static function.
(snsort, ssort): New functions.

* lib.h (snsort, ssort): Declared.

* tests/010/sort.tl: Cover ssort.

* txr.1: Documented.

* stdlib/doc-syms.tl: Updated.

1 files changed, 2 insertions, 0 deletions

diff --git a/lib.h b/lib.h
index f7e6f992..9e71b5f9 100644
--- a/lib.h
+++ b/lib.h
@@ -1319,6 +1319,8 @@ val interpose(val sep, val seq);
 val merge(val list1, val list2, val lessfun, val keyfun);
 val nsort(val seq, val lessfun, val keyfun);
 val sort(val seq, val lessfun, val keyfun);
+val snsort(val seq, val lessfun, val keyfun);
+val ssort(val seq, val lessfun, val keyfun);
 val nshuffle(val seq, val randstate);
 val shuffle(val seq, val randstate);
 val multi_sort(val lists, val funcs, val key_funcs);