From 25b33e2ac8104e53ec1f1475b2868d46923370ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADtor=20Santos=20Costa?= Date: Thu, 17 Jun 2010 00:32:52 +0100 Subject: [PATCH] document SWI compatibility stuff --- docs/yap.tex | 205 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 199 insertions(+), 6 deletions(-) diff --git a/docs/yap.tex b/docs/yap.tex index 418315fb2..3bab4daad 100644 --- a/docs/yap.tex +++ b/docs/yap.tex @@ -211,6 +211,7 @@ Subnodes of Library * Read Utilities:: SWI inspired utilities for fast stream scanning. * Red-Black Trees:: Predicates to add, lookup and delete in red-black binary trees. * RegExp:: Regular Expression Manipulation +* shlib:: SWI Prolog shlib library * Splay Trees:: Splay Trees * String I/O:: Writing To and Reading From Strings * System:: System Utilities @@ -4463,6 +4464,19 @@ name is @code{user}. @cnindex file_base_name/2 Give the path a full path @var{FullPath} extract the @var{FileName}. +@item file_name_extension(?@var{Base},?@var{Extension}, ?@var{Name}) +@findex file_name_extension/3 +@snindex file_name_extension/3 +@cnindex file_name_extension/3 + +This predicate is used to add, remove or test filename extensions. The +main reason for its introduction is to deal with different filename +properties in a portable manner. If the file system is +case-insensitive, testing for an extension will be done +case-insensitive too. @var{Extension} may be specified with or +without a leading dot (.). If an @var{Extension} is generated, it +will not have a leading dot. + @item current_stream(@var{F},@var{M},@var{S}) @findex current_stream/3 @syindex current_stream/3 @@ -7972,6 +7986,13 @@ If @code{true} the @code{open/3} builtin performs filename-expansion before opening a file (SICStus Prolog like). If @code{false} it does not (SWI-Prolog like). +@item open_shared_object +@findex open_shared_object (yap_flag/2 option) +@* +If true, @code{open_shared_object/2} and friends are implemented, +providing access to shared libraries (@code{.so} files) or to dynamic link +libraries (@code{.DLL} files). + @item profiling @findex profiling (yap_flag/2 option) @* @@ -8420,6 +8441,7 @@ Library, Extensions, Built-ins, Top * Read Utilities:: SWI inspired utilities for fast stream scanning. * Red-Black Trees:: Predicates to add, lookup and delete in red-black binary trees. * RegExp:: Regular Expression Manipulation +* shlib:: SWI Prolog shlib library * Splay Trees:: Splay Trees * String I/O:: Writing To and Reading From Strings * System:: System Utilities @@ -10684,7 +10706,7 @@ associated with @var{Val}. list @var{L}. @end table -@node RegExp, Splay Trees, Red-Black Trees, Library +@node RegExp, shlib, Red-Black Trees, Library @section Regular Expressions @cindex regular expressions @@ -10815,7 +10837,136 @@ sub-expression. Thus the @code{"b"} has already been claimed before the @end table -@node Splay Trees, String I/O, RegExp, Library +@node shlib, Splay Trees, RegExp, Library +@section SWI-Prolog's shlib library + +@cindex SWI-Compatible foreign file loading +This section discusses the functionality of the (autoload) +@code{library(shlib)}, providing an interface to manage shared +libraries. + +One of the files provides a global function @code{install_mylib()} that +initialises the module using calls to @code{PL_register_foreign()}. Here is a +simple example file @code{mylib.c}, which creates a Windows MessageBox: + +@example +#include +#include + +static foreign_t +pl_say_hello(term_t to) +@{ char *a; + + if ( PL_get_atom_chars(to, &a) ) + @{ MessageBox(NULL, a, "DLL test", MB_OK|MB_TASKMODAL); + + PL_succeed; + @} + + PL_fail; +@} + +install_t +install_mylib() +@{ PL_register_foreign("say_hello", 1, pl_say_hello, 0); +@} +@end example + +Now write a file mylib.pl: + +@example +:- module(mylib, [ say_hello/1 ]). +:- use_foreign_library(foreign(mylib)). +@end example + +The file mylib.pl can be loaded as a normal Prolog file and provides the predicate defined in C. + +@table @code +@item [det]load_foreign_library(:@var{FileSpec}) +@item [det]load_foreign_library(:@var{FileSpec}, +@var{Entry}:atom) +@findex load_foreign_library/1 +@snindex load_foreign_library/1 +@cnindex load_foreign_library/1 +@findex load_foreign_library/2 +@snindex load_foreign_library/2 +@cnindex load_foreign_library/2 + Load a shared object or DLL. After loading the @var{Entry} function is + called without arguments. The default entry function is composed + from @code{install_}, followed by the file base-name. E.g., the + load-call below calls the function @code{install_mylib()}. If the platform + prefixes extern functions with @code{_}, this prefix is added before + calling. + +@example + ... + load_foreign_library(foreign(mylib)), + ... +@end example + + @var{FileSpec} is a specification for + @code{absolute_file_name/3}. If searching the file fails, the plain + name is passed to the OS to try the default method of the OS for + locating foreign objects. The default definition of + @code{file_search_path/2} searches /lib/Yap. + + See also + @code{use_foreign_library/1,2} are intended for use in + directives. + +@item [det]use_foreign_library(+@var{FileSpec}) +@item [det]use_foreign_library(+@var{FileSpec}, +@var{Entry}:atom) +@findex use_foreign_library/1 +@snindex use_foreign_library/1 +@cnindex use_foreign_library/1 +@findex use_foreign_library/2 +@snindex use_foreign_library/2 +@cnindex use_foreign_library/2 + Load and install a foreign library as load_foreign_library/1,2 and + register the installation using @code{initialization/2} with the option + now. This is similar to using: + +@example + :- initialization(load_foreign_library(foreign(mylib))). +@end example + + but using the @code{initialization/1} wrapper causes the library to + be loaded after loading of the file in which it appears is + completed, while @code{use_foreign_library/1} loads the library + immediately. I.e. the difference is only relevant if the remainder + of the file uses functionality of the @code{C}-library. + +@item [det]unload_foreign_library(+@var{FileSpec}) +@item [det]unload_foreign_library(+@var{FileSpec}, +@var{Exit}:atom) +@findex unload_foreign_library/1 +@snindex unload_foreign_library/1 +@cnindex unload_foreign_library/1 +@findex unload_foreign_library/2 +@snindex unload_foreign_library/2 +@cnindex unload_foreign_library/2 + +Unload a shared +object or DLL. After calling the @var{Exit} function, the shared object is +removed from the process. The default exit function is composed from +@code{uninstall_}, followed by the file base-name. + +@item current_foreign_library(?@var{File}, ?@var{Public}) +@findex current_foreign_library/2 +@snindex current_foreign_library/2 +@cnindex current_foreign_library/2 + +Query currently +loaded shared libraries. + +@c @item reload_foreign_libraries +@c @findex reload_foreign_libraries/0 +@c @snindex reload_foreign_libraries/0 +@c @cnindex reload_foreign_libraries/0 +@c Reload all foreign +@c libraries loaded (after restore of a state created using +@c @code{qsave_program/2}). +@end table + +@node Splay Trees, String I/O, shlib, Library @section Splay Trees @cindex splay trees @@ -15782,10 +15933,52 @@ YAP will search for @var{ObjectFiles} in the current directory first. If it cannot find them it will search for the files using the environment variable @code{YAPLIBDIR}, if defined, or in the default library. -In a.out systems YAP by default only reserves a fixed amount of memory -for object code (64 Kbytes in the current version). Should this size -prove inadequate the flag @code{-c n} can be passed to YAP (in the -command line invoking YAP) to force the allocation of @code{n} Kbytes. +YAP also supports the SWI-Prolog interface to loading foreign code: + +@table @code +@item open_shared_object(+@var{File}, -@var{Handle}) +@findex open_shared_object/2 +@snindex open_shared_object/2 +@cnindex open_shared_object/2 + File is the name of a shared object file (called dynamic load + library in MS-Windows). This file is attached to the current process + and @var{Handle} is unified with a handle to the library. Equivalent to + @code{open_shared_object(File, [], Handle)}. See also + load_foreign_library/[1,2]. + + On errors, an exception @code{shared_object}(@var{Action}, + @var{Message}) is raised. @var{Message} is the return value from + dlerror(). + +@item open_shared_object(+@var{File}, -@var{Handle}, +@var{Options}) +@findex open_shared_object/3 +@snindex open_shared_object/3 +@cnindex open_shared_object/3 + As @code{open_shared_object/2}, but allows for additional flags to + be passed. @var{Options} is a list of atoms. @code{now} implies the + symbols are + resolved immediately rather than lazily (default). @code{global} implies + symbols of the loaded object are visible while loading other shared + objects (by default they are local). Note that these flags may not + be supported by your operating system. Check the documentation of + @code{dlopen()} or equivalent on your operating system. Unsupported + flags are silently ignored. + +@item close_shared_object(+@var{Handle}) +@findex close_shared_object/1 +@snindex close_shared_object/1 +@cnindex close_shared_object/1 + Detach the shared object identified by @var{Handle}. + +@item call_shared_object_function(+@var{Handle}, +@var{Function}) +@findex call_shared_object_function/2 +@snindex call_shared_object_function/2 +@cnindex call_shared_object_function/2 + Call the named function in the loaded shared library. The function + is called without arguments and the return-value is + ignored. In SWI-Prolog, normally this function installs foreign + language predicates using calls to @code{PL_register_foreign()}. +@end table @node Save&Rest, YAP4 Notes, Loading Objects, C-Interface @section Saving and Restoring