11.3.118 load_foreign_resource/1   hookable

Synopsis

load_foreign_resource(:Resource)

Load the foreign resource Resource into Prolog. Relies on the hook predicates foreign_resource/2 and foreign/[2,3].

Arguments

:Resource

file_spec, must be ground

The foreign resource to be loaded. The file extension can be omitted.

Description

load_foreign_resource/1 takes a foreign resource and loads it into Prolog.

The extension can be omitted from the filename given in the Resource argument.

Uses the foreign/[2,3] and foreign_resource/2 facts defined by the user to make the connection between a Prolog procedure and the foreign function. In this context, the resource name is derived from Resource name by deleting any leading path and extension from the absolute file name of Resource.

When loading the foreign resource, it looks for a foreign_resource/2 fact for the resource name. For each symbol in that fact, it looks for a foreign/[2,3] fact that gives the name of the Prolog procedure associated with the foreign symbol and the argument specification.

Contrary to most hook predicates which reside in the user module, load_foreign_resource/1 will look for foreign_resource/2 and foreign/[2,3] facts defined in its source module.

Foreign resources are created with the splfr tool (see The Foreign Resource Linker).

Exceptions

Errors in the specification of foreign/[2,3] and foreign_resource/2 will all be reported when load_foreign_resource/1 is called.

instantiation_error

Resource not ground.

type_error

Resource not an atom, or argument of a declared fact of the wrong type.

domain_error

Invalid argument of foreign/[2,3] fact.

existence_error

Resource does not exist as a foreign resource, or Resource does not have a foreign_resource/2 fact, or declared function does not exist, or declared function does not have a foreign/[2,3] fact.

domain_error

Invalid option to foreign_resource/2.

consistency_error

Function declared twice with clashing declarations.

permission_error

Attempt to redefine built-in predicate.

Examples

library(codesio) contains a foreign resource consisting of three foreign functions, one init function, and one deinit function. The Prolog source file contains the following lines of code:

:- dynamic foreign/2, foreign_resource/2.

foreign(codes_to_stream, '$codes_to_stream'(+codes,-address('SP_stream'))).
foreign(open_buf_stream, '$open_buf_stream'(-address('SP_stream'))).
foreign(stream_to_codes, '$stream_to_codes'(+address('SP_stream'),-term,-term)).

foreign_resource(codesio, [
        init(codesio_init),
        deinit(codesio_deinit),
        codes_to_stream,
        open_buf_stream,
        stream_to_codes
                          ]).

:- load_foreign_resource(library(system(codesio))).

Comments

Note that the foreign declarations are needed by other operations as well and should not be abolished after loading the foreign resource.

See Also

unload_foreign_resource/1, foreign_resource/2, foreign/[2,3], Foreign Resources, Calling C from Prolog.