Before a Prolog predicate can be called from a foreign language it
must be looked up. The C functions QP_predicate() and
QP_pred() perform this function. The lookup step could have been
folded into the functions that make the query, but if a predicate was
to be called many times the redundant, if hidden, predicate lookup
would be a source of unnecessary overhead. Instead,
QP_predicate() or QP_pred() can be called just once per
predicate. The result can then be stored in a variable and used as
necessary.
Both QP_predicate() and QP_pred return a QP_pred_ref, which
represents a Prolog predicate. The type definition for QP_pred_ref
is found in <quintus/quintus.h>.
QP_pred_ref QP_predicate(name_string, arity, module_string)
char *name_string;
long int arity;
char *module_string;
QP_predicate() is the most convenient way of looking up a
callable Prolog predicate. It is simply passed the name and module
of the predicate to be called as strings, the arity as an integer, and
returns a QP_pred_ref, which is used to make the actual call to Prolog.
QP_predicate() can only be used to look up predicates that have
been declared callable from foreign code. If some other predicate is
looked up, QP_ERROR is returned. Checking the return value protects
you from attempting to call a predicate that isn't yet ready to be
called.
QP_pred_ref QP_pred(name_atom, arity, module_atom)
QP_atom name_atom;
long int arity;
QP_atom module_atom;
QP_pred() is a less convenient, but faster, means of looking up a
callable Prolog predicate. Unlike QP_predicate(), it has its name
and module arguments passed as Prolog atoms. These may have been
returned to C from Prolog, or may have been built in the foreign
language using QP_atom_from_string(). One additional difference
is that the name passed is not the name of the Prolog predicate to be
called, but rather the name of the interface predicate constructed
when the Prolog predicate was made callable from foreign code
fli-ffp-ppc. Much of the cost of QP_predicate() is from having
to look up Prolog atoms for its name and module arguments. By
avoiding doing this unnecessarily, what QP_pred() gives up in
convenience is returned in performance. Like QP_predicate(),
QP_pred() returns a QP_pred_ref, which is used to make the
actual call to Prolog. If a predicate that is not an interface
predicate is looked up, QP_pred() returns QP_ERROR.
QP_pred() can only be used to look up predicates that
have been declared callable from foreign code. If some other predicate,
or a predicate that does not exist, is looked up, QP_ERROR is returned.
This protects you from attempting to call a predicate that
isn't yet ready to be called.