allow users to check for out of space conditions explicitly.

C/c_interface.c

@@ -561,6 +561,7 @@ X_API YAP_tag_t STD_PROTO(YAP_TagOfTerm,(Term));
 X_API size_t   STD_PROTO(YAP_ExportTerm,(Term, char *, size_t));
 X_API size_t   STD_PROTO(YAP_SizeOfExportedTerm,(char *));
 X_API Term     STD_PROTO(YAP_ImportTerm,(char *));
+X_API int      STD_PROTO(YAP_RequiresExtraStack,(size_t));
 
 static UInt
 current_arity(void)
@@ -4119,3 +4120,22 @@ YAP_ImportTerm(char * buf) {
   return Yap_ImportTerm(buf);
 }
 
+X_API int
+YAP_RequiresExtraStack(size_t sz) {
+  if (sz < 16*1024) 
+    sz = 16*1024;
+  if (H <= ASP-sz) {
+    return FALSE;
+  }
+  BACKUP_H();
+  while (H > ASP-sz) {
+    CACHE_REGS
+    RECOVER_H();
+    if (!dogc( 0, NULL PASS_REGS )) {
+      return -1;
+    }
+    BACKUP_H();
+  }
+  RECOVER_H();
+  return TRUE;
+}

docs/yap.tex

@@ -16471,6 +16471,21 @@ then allow one to construct functors, and to obtain their name and arity.
 Note that the functor is essentially a pair formed by an atom, and
 arity.
 
+Constructing terms in the stack may lead to overflow. The routine
+@example
+      int          YAP_RequiresExtraStack(size_t @var{min})
+@end example
+verifies whether you have at least @var{min} cells free in the stack,
+and it returns true if it has to ensure enough memory by calling the
+garbage collector and or stack shifter. The routine returns false if no
+memory is needed, and a negative number if it cannot provide enough
+memory.
+
+You can set @var{min} to zero if you do not know how much room you need
+but you do know you do not need a big chunk at a single go. Usually, the routine
+would usually be called together with a long-jump to restart the
+code. Slots can also be used if there is small state.
+
 @node Unifying Terms, Manipulating Strings, Manipulating Terms, C-Interface
 @section Unification
 

include/YapInterface.h

@@ -599,6 +599,8 @@ extern X_API size_t   PROTO(YAP_SizeOfExportedTerm,(char *));
 
 extern X_API YAP_Term     PROTO(YAP_ImportTerm,(char *));
 
+extern X_API int      PROTO(YAP_RequiresExtraStack,(size_t));
+
 #define YAP_InitCPred(N,A,F)  YAP_UserCPredicate(N,F,A)
 
 __END_DECLS