Register the C function f to implement a Prolog predicate.
After this call returns successfully a predicate with name name
(a
char *) and arity arity (a C int)
is created in module mod. If mod is NULL,
the predicate is created in the module of the calling context, or if no
context is present in the module user.
When called in Prolog, Prolog will call function. flags
form a bitwise or’ed list of options for the
installation. These are:
PL_FA_META | Provide meta-predicate info
(see below) |
PL_FA_TRANSPARENT | Predicate is module
transparent (deprecated) |
PL_FA_NONDETERMINISTIC | Predicate is
non-deterministic. See also PL_retry(). |
PL_FA_NOTRACE | Predicate cannot be seen in
the tracer |
PL_FA_VARARGS | Use alternative calling
convention. |
If PL_FA_META is provided, PL_register_foreign_in_module()
takes one extra argument. This argument is of type const char*.
This string must be exactly as long as the number of arguments of the
predicate and filled with characters from the set 0-9:^-+?.
See
meta_predicate/1
for details. PL_FA_TRANSPARENT is implied if at least one
meta-argument is provided (0-9:^). Note that meta-arguments
are not always passed as <module>:<term>.
Always use PL_strip_module()
to extract the module and plain term from a meta-argument.237It
is encouraged to pass an additional NULL pointer for
non-meta-predicates.
Predicates may be registered either before or after PL_initialise().
When registered before initialisation the registration is recorded and
executed after installing the system predicates and before loading the
saved state.
Default calling (i.e., without PL_FA_VARARGS) function
is passed the same number of term_t arguments as the arity
of the predicate and, if the predicate is non-deterministic, an extra
argument of type
control_t (see section
12.4.1.1). If PL_FA_VARARGS is provided, function
is called with three arguments. The first argument is a term_t
handle to the first argument. Further arguments can be reached by adding
the offset (see also
PL_new_term_refs()).
The second argument is the arity, which defines the number of valid term
references in the argument vector. The last argument is used for
non-deterministic calls. It is currently undocumented and should be
defined of type void*. Here is an example:
static foreign_t
atom_checksum(term_t a0, int arity, void* context)
{ char *s;
if ( PL_get_atom_chars(a0, &s) )
{ int sum;
for(sum=0; *s; s++)
sum += *s&0xff;
return PL_unify_integer(a0+1, sum&0xff);
}
return FALSE;
}
install_t
install(void)
{ PL_register_foreign("atom_checksum", 2,
atom_checksum, PL_FA_VARARGS);
}
Note that the function is documented as foreign_t
(*function)(). The actual prototype uses void* as
C11 and later do not allow for function types with unspecified
arguments.
Register a series of predicates from an array of definitions of the type
PL_extension in the given module. If module
is
NULL, the predicate is created in the module of the calling
context, or if no context is present in the module user.
The PL_extension type is defined as
typedef struct PL_extension
{ char *predicate_name; /* Name of the predicate */
short arity; /* Arity of the predicate */
pl_function_t function; /* Implementing functions */
short flags; /* Or of PL_FA_... */
} PL_extension;
For details, see PL_register_foreign_in_module().
Here is an example of its usage:
static PL_extension predicates[] = {
{ "foo", 1, pl_foo, 0 },
{ "bar", 2, pl_bar, PL_FA_NONDETERMINISTIC },
{ NULL, 0, NULL, 0 }
};
main(int argc, char **argv)
{ PL_register_extensions_in_module("user", predicates);
if ( !PL_initialise(argc, argv) )
PL_halt(1);
...
}
