Did you know ... | Search Documentation: |
Storing foreign data |
When combining foreign code with Prolog, it can be necessary to make data represented in the foreign language available to Prolog. For example, to pass it to another foreign function. At the end of this section, there is a partial implementation of using foreign functions to manage bit-vectors. Another example is the SGML/XML library that manages a‘parser’object, an object that represents the current state of the parser and that can be directed to perform actions such as parsing a document or make queries about the document content.
This section provides some hints for handling foreign data in Prolog. There are four options for storing such data:
The choice may be guided using the following distinctions
In this section, we outline some examples, covering typical cases. In the first example, we will deal with extending Prolog's data representation with integer sets, represented as bit-vectors. Then, we discuss the outline of the DDE interface.
Integer sets with not-too-far-apart upper- and lower-bounds can be represented using bit-vectors. Common set operations, such as union, intersection, etc., are reduced to simple and’ing and or’ing the bit-vectors. This can be done using Prolog's unbounded integers.
For really demanding applications, foreign representation will
perform better, especially time-wise. Bit-vectors are naturally
expressed using string objects. If the string is wrapped in bitvector/1
,
the lower-bound of the vector is 0 and the upper-bound is not defined;
an implementation for getting and putting the sets as well as the union
predicate for it is below.
#include <SWI-Prolog.h> #define max(a, b) ((a) > (b) ? (a) : (b)) #define min(a, b) ((a) < (b) ? (a) : (b)) static functor_t FUNCTOR_bitvector1; static int get_bitvector(term_t in, int *len, unsigned char **data) { if ( PL_is_functor(in, FUNCTOR_bitvector1) ) { term_t a = PL_new_term_ref(); PL_get_arg(1, in, a); return PL_get_string(a, (char **)data, len); } PL_fail; } static int unify_bitvector(term_t out, int len, const unsigned char *data) { if ( PL_unify_functor(out, FUNCTOR_bitvector1) ) { term_t a = PL_new_term_ref(); PL_get_arg(1, out, a); return PL_unify_string_nchars(a, len, (const char *)data); } PL_fail; } static foreign_t pl_bitvector_union(term_t t1, term_t t2, term_t u) { unsigned char *s1, *s2; int l1, l2; if ( get_bitvector(t1, &l1, &s1) && get_bitvector(t2, &l2, &s2) ) { int l = max(l1, l2); unsigned char *s3 = alloca(l); if ( s3 ) { int n; int ml = min(l1, l2); for(n=0; n<ml; n++) s3[n] = s1[n] | s2[n]; for( ; n < l1; n++) s3[n] = s1[n]; for( ; n < l2; n++) s3[n] = s2[n]; return unify_bitvector(u, l, s3); } return PL_warning("Not enough memory"); } PL_fail; } install_t install() { PL_register_foreign("bitvector_union", 3, pl_bitvector_union, 0); FUNCTOR_bitvector1 = PL_new_functor(PL_new_atom("bitvector"), 1); }
The DDE interface (see section 4.44) represents another common usage of the foreign interface: providing communication to new operating system features. The DDE interface requires knowledge about active DDE server and client channels. These channels contains various foreign data types. Such an interface is normally achieved using an open/close protocol that creates and destroys a handle. The handle is a reference to a foreign data structure containing the relevant information.
There are a couple of possibilities for representing the handle. The
choice depends on responsibilities and debugging facilities. The
simplest approach is to use PL_unify_pointer()
and PL_get_pointer().
This approach is fast and easy, but has the drawbacks of (untyped)
pointers: there is no reliable way to detect the validity of the
pointer, nor to verify that it is pointing to a structure of the desired
type. The pointer may be wrapped into a compound term with arity 1
(i.e., dde_channel(<Pointer>)
), making the
type-problem less serious.
Alternatively (used in the DDE interface), the interface code can maintain a (preferably variable length) array of pointers and return the index in this array. This provides better protection. Especially for debugging purposes, wrapping the handle in a compound is a good suggestion.