12.4.12.1 Predicate references

This section discusses the functions used to communicate about predicates. Though a Prolog predicate may be defined or not, redefined, etc., a Prolog predicate has a handle that is neither destroyed nor moved. This handle is known by the type predicate_t.

predicate_t PL_pred(functor_t f, module_t m)

Return a handle to a predicate for the specified name/arity in the given module. If the module argument m is NULL, the current context module is used. If the target predicate does not exist a handle to a new undefined predicate is returned. The predicate may fail, returning (predicate_t)0 after setting a resource exception, if the target module has a limit on the program_space, see set_module/1. Currently aborts the process with a fatal error when out of memory. Future versions may raise a resource exception and return (predicate_t)0.

predicate_t PL_predicate(const char *name, int arity, const char* module)

Same as PL_pred(), but provides a more convenient interface to the C programmer. If the module argument module is NULL, the current context module is used. The predicate_t handle may be stored as global data and reused for future queries^{229PL_predicate() involves 5 hash lookups (two to get the atoms, one to get the module, one to get the functor and the final one to get the predicate associated with the functor in the module)} as illustrated below.

static predicate_t p = 0;

  ...
  if ( !p )
    p = PL_predicate("is_a", 2, "database");

Note that PL_cleanup() invalidates the predicate handle. Foreign libraries that use the above mechanism must implement the module uninstall() function to clear the predicate_t global variable.

bool PL_predicate_info(predicate_t p, atom_t *n, size_t *a, module_t *m)

Return information on the predicate p. The name is stored over n, the arity over a, while m receives the definition module. Note that the latter need not be the same as specified with PL_predicate(). If the predicate is imported into the module given to PL_predicate(), this function will return the module where the predicate is defined. Any of the arguments n, a and m can be NULL. Currently always returns TRUE.