2.6 Functions for Use in Foreign Code

In addition to functions for passing data between Prolog an C, XSB contains other functions that may be useful in Foreign C code. We mention a few here that pertain to throwing exceptions from C code (cf. Volume 1 Chapter 8: Exception Handling). These functions can be used by code that uses either the lower- or higher-level interface.

void xsb_domain_error(CTXTdeclc char *valid_domain,Cell culprit,char *pred,int arity,int arg)

Used to throw an ISO-style domain error from foreign code, indicating that culprit is not in domain valid_domain in argument arg of pred/arity.

Example: The code fragment

    Cell num;
    : 
    xsb_domain_error(CTXTc "not_less_than_zero",num,"atom_length",2,2);

in atom_length/2 gives rise to the behavior

| ?- atom_length(abcde,-1).
++Error[XSB/Runtime/P]: [Domain (-1 not in domain not_less_than_zero)] 
             in arg 2 of predicate atom_length/2)

void xsb_existence_error(CTXTdeclc char *objType,Cell culprit,char *pred,int arity,int arg)

Used to throw an ISO-style existence error from foreign code, indicating that an object culprit of type objType does not exist, in argument arg of pred/arity.

Example: The code fragment

    Cell tid;
    :
    xsb_existence_error(CTXTc "thread",reg[2],"xsb_thread_join",1,1);

in thread_join/1 gives rise to a the behavior

| ?- thread_join(7).
++Error[XSB/Runtime/P]: [Existence (No thread 1 exists)] 
             in arg 1 of predicate thread_join/1)

if a thread with thread id 7 does not exist.

void xsb_instantiation_error(CTXTdeclc char *pred,int arity,int arg,char *state)

Used to throw an ISO-style instantiation error from foreign code. If state is a NULL pointer, the message indicates that there is an instantiation error for argument arg of of pred/arity. If state is non-NULL, the message additionally indicates that argument arg must be state.

Example: The code fragment

    xsb_instantiation_error(CTXTc "atom_length",2,1,NULL);

in atom_length/2 gives rise to a the behavior

| ?- atom_length(X,Y).
++Error[XSB/Runtime/P]: [Instantiation]  in arg 1 of predicate atom_length/2

void xsb_misc_error(CTXTdeclc char *message,char *pred,int arity)

Used to throw a non ISO-error from foreign code, printing message and indicating that the error arose in pred/arity.

void xsb_permission_error(CTXTdeclc char *op,char *obj,Cell culprit,char *pred,int arity)

Used to throw an ISO-style permission error from foreign code, indicating that an operation of type op on type obj is not permitted on culprit, in argument arg of pred/arity.

Example: The code fragment

xsb_permission_error(CTXTc "unlock mutex","mutex not held by thread",
                     xsb_thread_id,"mutex_unlock",2);

in mutex_unlock/1 gives rise to a the behavior

| ?- mutex_unlock(mymut).
++Error[XSB/Runtime/P]: [Permission (Operation) unlock mutex on mutex not held
 by thread: 0] in predicate mutex_unlock/1)

if thread 0 does not own mutex mymut.

void xsb_resource_error(CTXTdeclc char *resource,char *pred,int arity)

Used to indicate that there are not sufficient resources of type resource for pred/arity to succeed.

Example: The code fragment

xsb_resource_error(th,"system threads","thread_create",2);

in thread_create/1 gives rise to a the behavior

| ?- thread_create(X).
++Error[XSB/Runtime/P]: [Resource (system threads))] in predicate thread_create/2)

If the number of system threads has been exceeded.

void xsb_type_error(CTXTdeclc char *valid_type,Cell culprit,char *pred,int arity,int arg)

Used to throw an ISO-style type error from foreign code, indicating that culprit is not in ISO type valid_type in argument arg of pred/arity.

Example: The code fragment

    Cell num;
    : 
    if (!isinteger(num)) xsb_type_error(CTXTc "integer",num,"atom_length",2,2);

in atom_length/2 gives rise to the behavior

| ?- atom_length(foo,a).
++Error[XSB/Runtime/P]: [Type (a in place of integer)] in arg 2 
of predicate atom_length/2)

void xsb_throw(CTXTdeclc prolog_term Ball)

Used to throw a Prolog term from C code, when an ISO-style error is not required. The term can be caught and handled by the Prolog predicate catch/3 just as any other thrown term; however if it is not caught, XSB's default error handler will treat it as an unhandled exception.