14 Stand-alone interfaces

Programs written in a language other than Mercury should not make calls to foreign exported Mercury procedures unless the Mercury runtime has been initialised. (In the case where the Mercury runtime has not been initialised, the behaviour of these calls is undefined.) Such programs must also ensure that any module specific initialisation is performed before calling foreign exported procedures in Mercury modules. Likewise, module specific finalisation may need to be performed after all calls to Mercury procedures have been made.

A stand-alone interface provides a mechanism by which non-Mercury programs may initialise (and shut down) the Mercury runtime plus a specified set of Mercury libraries.

A stand-alone interface is created by invoking the compiler with the ‘--generate-standalone-interface’ option. The set of Mercury libraries to be included in the stand-alone interface is given via one of the usual mechanisms for specifying what libraries to link against, e.g. the ‘--ml’ and ‘--mld’ options. (see Libraries). The Mercury standard library is always included in this set.

In C grades, the ‘--generate-standalone-interface’ option causes the compiler to generate an object file that should be linked into the executable. This object file contains two functions: mercury_init() and mercury_terminate(). The compiler also generates a C header file that contains the prototypes of these functions. (This header file may be included in C++ programs.) The roles of the two functions are described below.

• mercury_init()

Prototype:

void mercury_init(int argc, char **argv, void *stackbottom);

Initialise the Mercury runtime, standard library and any other Mercury libraries that were specified when the stand-alone interface was generated. argc and argv are the argument count and argument vector, as would be passed to the function main() in a C program. stackbottom is the address of the base of the stack. In grades that use conservative garbage collection this is used to tell the collector where to begin tracing. This function must be called before any Mercury procedures and must only be called once. It is recommended that the value of stackbottom be set by passing the address of a local variable in the main() function of a program, for example:

    int main(int argc, char **argv) {
        void *dummy;
        mercury_init(argc, argv, &dummy);
        …
    }

Note that the address of the stack base should be word aligned as some garbage collectors rely upon this. (This is why the type of the dummy variable in the above example is void *.) If the value of stackbottom is NULL, then the collector will attempt to determine the address of the base of the stack itself. Note that modifying the argument vector, argv, after the Mercury runtime has been initialised will result in undefined behaviour since the runtime maintains a reference into argv.

• mercury_terminate()

Prototype:

int mercury_terminate(void);

Shut down the Mercury runtime. The value returned by this function is Mercury’s exit status (as set by the predicate ‘io.set_exit_status/3’). This function will also invoke any finalisers contained in the set of libraries for which the stand-alone interface was generated.

The basename of the object and header file are provided as the argument of ‘--generate-standalone-interface’ option.

Stand-alone interfaces are not required if the target language is Java or C#. For those target languages the Mercury runtime will be automatically initialised when the classes or library assemblies containing code generated by the Mercury compiler are loaded.

For an example of using a stand-alone interface see the ‘samples/c_interface/standalone_c’ directory in the Mercury distribution.