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/eval.c b/eval.c
index 68ea1865..ca9fe25d 100644
--- a/eval.c
+++ b/eval.c
@@ -7509,6 +7509,8 @@ void eval_init(void)
   reg_fun(intern(lit("merge"), user_package), func_n4o(merge_wrap, 2));
   reg_fun(intern(lit("nsort"), user_package), func_n3o(nsort, 1));
   reg_fun(intern(lit("sort"), user_package), func_n3o(sort, 1));
+  reg_fun(intern(lit("snsort"), user_package), func_n3o(snsort, 1));
+  reg_fun(intern(lit("ssort"), user_package), func_n3o(ssort, 1));
   reg_fun(intern(lit("nshuffle"), user_package), func_n2o(nshuffle, 1));
   reg_fun(intern(lit("shuffle"), user_package), func_n2o(shuffle, 1));
   reg_fun(intern(lit("find"), user_package), func_n4o(find, 2));