New function: cptr-size-hint.

* eval.c (eval_init): Register cptr-size-hint intrinsic.

* lib.c (cptr_size_hint): New function.

* lib.h (cptr_size_hint): Declared.

* txr.1: Documented.

4 files changed, 29 insertions, 0 deletions

diff --git a/eval.c b/eval.c
index 93ca1d5d..68aed2ed 100644
--- a/eval.c
+++ b/eval.c
@@ -6872,6 +6872,7 @@ void eval_init(void)
   reg_fun(intern(lit("int-cptr"), user_package), func_n1(int_cptr));
   reg_fun(intern(lit("cptrp"), user_package), func_n1(cptrp));
   reg_fun(intern(lit("cptr-type"), user_package), func_n1(cptr_type));
+  reg_fun(intern(lit("cptr-size-hint"), user_package), func_n2(cptr_size_hint));
   reg_varl(intern(lit("cptr-null"), user_package), cptr(0));
 
   reg_fun(intern(lit("rt-defvarl"), system_package), func_n1(rt_defvarl));
diff --git a/lib.c b/lib.c
index ab898277..c787174f 100644
--- a/lib.c
+++ b/lib.c
@@ -7723,6 +7723,13 @@ val cptr_type(val cptr)
   return cptr->co.cls;
 }
 
+val cptr_size_hint(val cptr, val size)
+{
+  (void) cptr;
+  malloc_bytes += c_unum(size);
+  return nil;
+}
+
 val cptr_int(val n, val type_sym_in)
 {
   val type_sym = default_null_arg(type_sym_in);
diff --git a/lib.h b/lib.h
index c9b6198f..8ff88b76 100644
--- a/lib.h
+++ b/lib.h
@@ -1020,6 +1020,7 @@ val cptr(mem_t *ptr);
 val cptr_typed(mem_t *handle, val type_sym, struct cobj_ops *ops);
 val cptrp(val obj);
 val cptr_type(val cptr);
+val cptr_size_hint(val cptr, val size);
 val cptr_int(val n, val type_sym);
 val cptr_obj(val obj, val type_sym);
 val cptr_zap(val cptr);
diff --git a/txr.1 b/txr.1
index ddaac786..697ff1bd 100644
--- a/txr.1
+++ b/txr.1
@@ -59882,6 +59882,26 @@ The expression
 .code "(cptr-int 0)"
 also produces a null pointer on all platforms where \*(TX is found.
 
+.coNP Function @ cptr-size-hint
+.synb
+.mets (cptr-size-hint < cptr << bytes )
+.syne
+.desc
+The
+.code cptr-size-hint
+function indicates to the garbage collector that the given
+.meta cptr
+object is associated with
+.meta bytes
+of foreign memory that are otherwise invisible to the garbage collector.
+
+Note: this function should be used if the foreign memory is indirectly
+managed by the
+.meta cptr
+object in cooperation with the garbage collector. Specifically,
+.meta cptr
+should have a finalizer registered against it which will liberate the
+foreign memory.
 
 .SH* FOREIGN FUNCTION INTERFACE