s to discard a foreign frame. Foreign frames may be nested.

int
count_atoms()
{ fid_t fid = PL_open_foreign_frame();
  term_t goal  = PL_new_term_ref();
  term_t a1    = PL_new_term_ref();
  term_t a2    = PL_new_term_ref();
  functor_t s2 = PL_new_functor(PL_new_atom("statistics"), 2);
  int atoms;

  PL_put_atom_chars(a1, "atoms");
  PL_cons_functor(goal, s2, a1, a2);
  PL_call(goal, NULL);         /* call it in current module */

  PL_get_integer(a2, &atoms);
  PL_discard_foreign_frame(fid);

  return atoms;
}

12.4.14 String buffering

Many of the functions of the foreign language interface involve strings. Some of these strings point into static memory like those associated with atoms. These strings are valid as long as the atom is protected against atom garbage collection, which generally implies the atom must be locked using PL_register_atom() or be part of an accessible term. Other strings are more volatile. Several functions provide a BUF_* flag that can be set to either BUF_STACK (default) or BUF_MALLOC. Strings returned by a function accepting BUF_MALLOC must be freed using PL_free(). Strings returned using BUF_STACK are pushed on a stack that is cleared when a foreign predicate returns control back to Prolog. More fine grained control may be needed if functions that return strings are called outside the context of a foreign predicate or a foreign predicate creates many strings during its execution. Temporary strings are scoped using these macros:

void PL_STRINGS_MARK()

void PL_STRINGS_RELEASE()

These macros must be paired and create a C block ({...}). Any string created using BUF_STACK after PL_STRINGS_MARK() is released by the corresponding PL_STRINGS_RELEASE(). These macros should be used like below. Note that strings returned by any of the Prolog functions between this pair may be invalidated.

  ...
  PL_STRINGS_MARK();
    <operations involving strings>
  PL_STRINGS_RELEASE();
  ...

The Prolog flag string_stack_tripwire may be used to set a tripwire to help finding places where scoping strings may help reducing resources.

12.4.15 Foreign Code and Modules

Modules are identified via a unique handle. The following functions are available to query and manipulate modules.

module_t PL_context()

Return the module identifier of the context module of the currently active foreign predicate. If there is no currently active predicate it returns a handle to the user module.

int PL_strip_module(term_t +raw, module_t *m, term_t -plain)

Utility function. If raw is a term, possibly holding the module construct <module>:<rest>, this function will make plain a reference to <rest> and fill module * with <module>. For further nested module constructs the innermost module is returned via module *. If raw is not a module construct, raw will simply be put in plain. The value pointed to by m must be initialized before calling PL_strip_module(), either to the default module or to NULL. A NULL value is replaced by the current context module if raw carries no module. The following example shows how to obtain the plain term and module if the default module is the user module:

{ module m = PL_new_module(PL_new_atom("user"));
  term_t plain = PL_new_term_ref();

  PL_strip_module(term, &m, plain);
  ...
}

Returns TRUE on success and FALSE on error, leaving an exception. Currently the only exception condition is raw to be a cyclic term.

atom_t PL_module_name(module_t module)

Return the name of module as an atom.

module_t PL_new_module(atom_t name)

Find an existing module or create a new module with the name name. Currently aborts the process with a fatal error on failure. Future versions may raise a resource exception and return (module_t)0.

12.4.16 Prolog exceptions in foreign code

This section discusses PL_exception() and PL_raise_exception(), the interface functions to detect and generate Prolog exceptions from C code. PL_raise_exception() from the C interface registers the exception term and returns FALSE. If a foreign predicate returns FALSE, while an exception term is registered, a Prolog exception will be raised by the virtual machine. This implies for a foreign function that implements a predicate and wishes to raise an exception, the function must call PL_raise_exception(), perform any necessary cleanup, and return the return code of PL_raise_exception() or explicitly FALSE. Calling PL_raise_exception() outside the context of a function implementing a foreign predicate results in undefined behaviour.

Note that many of the C API functions may call PL_raise_exception() and return FALSE. The user must test for this, cleanup, and make the foreign function return FALSE.

PL_exception() may be used to inspect the currently registered exception. It is normally called after a call to PL_next_solution() returns FALSE, and returns a term reference to an exception term if an exception is pending, and (term_t)0 otherwise. It may also be called after, e.g., PL_unify() to distinguish a normal failing unification from a unification that raised an resource error exception. PL_exception() must only be called after a function such as PL_next_solution() or PL_unify() returns failure; if called elsewhere, the return value is undefined.

If a C function implementing a predicate that calls Prolog should use PL_open_query() with the flag PL_Q_PASS_EXCEPTION and make the function return FALSE if PL_next_solution() returns FALSE and PL_exception() indicates an exception is pending.

Both for C functions implementing a predicate and when Prolog is called while the main control of the process is in C, user code should always check for exceptions. As explained above, C functions implementing a predicate should normally cleanup and return with FALSE. If the C function whishes to continue it may call PL_clear_exception(). Note that this may cause any exception to be ignored, including time outs and abort. Typically the user should check the exception details before ignoring an exception (using PL_exception(0) or PL_exception(qid) as appropriate). If the C code does not implement a predicate it normally prints the exception and calls PL_clear_exception() to discard it. Exceptions may be printed by calling print_message/2 through the C interface.

int PL_raise_exception(term_t exception)

Generate an exception (as throw/1) and return FALSE. If there is already a pending exception, the most urgent exception is kept; and if both are of the same urgency, the new exception is kept. Urgency of exceptions is defined as

1. abort ('$aborted').
2. time_limit_exceeded (see call_with_time_limit/2).
3. resource_error exceptions.
4. Other error(Formal, ImplDef) exceptions.
5. Oth