2.2.1 Context Parameters

When using the lower-level interface, context parameters must be added to many C functions in order for the functions to be used with XSB's multi-threaded engine. In the multi-threaded engine, variables for Prolog's virtual machine, as well as for thread-private data structures are stored in a context structure. This context structure must be passed to any functions that need to access elements of a thread's virtual machine - including many of the functions that are used to exchange data between Prolog and C. We note in passing that when using the multi-threaded engine, a user must ensure that foreign-language functions are thread-safe, by using standard multi-threaded programming techniques, including XSB's mutex predicates (see the Section Predicates for Thread Synchronization in Volume 1 of this manual). On the other hand, in the single-threaded engine virtual machine elements are kept in static variables, so that context parameters are not required.

The lower-level C interface makes use of a set of macros to address the requirements of the different engines. The data exchange functions discussed in this chapter, ptoc_xxx, ctop_xxx, c2p_xxx, p2c_xxx, and p2p_xxx usually, but not always, require information about a threads virtual machine state. If a C function directly or indirectly calls a data interchange function that requires a context parameter, the function must have a context parameter in its declaration, calls, and prototypes in order to be used by the multi-threaded engine. These context parameters have the following forms:

• In function declarations, use the macro CTXTdecl in the code for a function that would otherwise be void, and CTXTdeclc as the first argument in the code for a function with parameters (CTXTdeclc and CTXTdecl are similar, except that macro expansion of CTXTdeclc for the multi-threaded engine includes a comma). The example for minus_one(CTXTdecl) shows use of this macro.

• In function calls use the macro CTXT in the code for a function that would otherwise be void, and CTXTc as the first argument in the code for a function with parameters. As an example, a call to minus_one would have the form minus_one(CTXT).

• In function prototypes use the macro CTXTdecltype in the code for a function that would otherwise be void, and CTXTdecltypec as the first argument in the code for a function with parameters. As an example, a prototype for minus_one would have the form minus_one(CTXTdecltype).

Fortunately, when compiling with the multi-threaded engine, it is easy to determine at compile time whether context parameters are correct. If compilation of a function foo gives an error along the lines of:

 
  foofile.c: In function `foo':
  foofile.c:109: error: `th' undeclared (first use in this function)

Then the declaration of foo omitted a context parameter. If compilation gives an error along the lines of

 
  foofile.c: In function `foo_caller':
  :
  foofile.c:149: error: too few arguments to function `foo'

Then the call to foo may have omitted a context parameter.

Note that context parameters are only necessary if the lower-level interface is used. The higher-level interface automatically generates any context parameters it needs.