Did you know ... Search Documentation:
PL_register_foreign_in_module()
Availability:C-language interface function
bool PL_register_foreign_in_module(char *mod, char *name, int arity, foreign_t (*f)(), int flags, ...)
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.

Tags are associated to your profile if you are logged in|Report abuse
Tags:
  • doc-needs-help
LogicalCaptain said (2020-04-01T18:51:33):0 upvotes 0 0 downvotes
Picture of user LogicalCaptain.

"After this call returns successfully" means it returns with TRUE (i.e. 1)

Declared in SWI-Prolog.h as follows:

typedef foreign_t (*pl_function_t)();

PL_EXPORT(int)
PL_register_foreign_in_module(const char *module,
                              const char *name,
                              int arity,
                              pl_function_t func,
                              int flags,
                              ...);

and defined in pl-fli.c although with a different argument list:

int
PL_register_foreign_in_module(const char *module,
                              const char *name,
                              int arity,
                              Func f,
                              int flags,
                              ...)

In shared libraries, this function is called from a specially designated C function that is called on module load so that the predicates implemented implemented by the module become visible.

See: https://eu.swi-prolog.org/pldoc/man?section=foreignlink