| - Up - | Next >> |
Oz can be very simply extended with new functionality and datatypes implemented in C or C++. This capability is often used to interface Oz to existing libraries: for example, the regex and gdbm modules are implemented in this fashion.
Every extension is presented to the system in the form of a native functor, i. e. a functor which happens to be implemented in C or C++ rather than in Oz.
In this chapter, we define a native functor that exports a next function which returns the next value of a global counter each time it is called.
#include "mozart.h"
static long n;
OZ_BI_define(counter_next,0,1)
{
OZ_RETURN_INT(n++);
}
OZ_BI_end
OZ_C_proc_interface * oz_init_module(void)
{
static OZ_C_proc_interface table[] = {
{"next",0,1,counter_next},
{0,0,0,0}
};
n = 1;
return table;
} OZ_BI_define(counter_next,0,1) indicates that we are defining a procedure counter_next that implements a new builtin which takes 0 input arguments and returns 1 output value. OZ_BI_end is required to finish this definition.
OZ_RETURN_INT(d) is a macro that causes the builtin to return integer d as an Oz integer. This should only be used when the builtin has one unique output value; and it is essentially equivalent to the code sequence:
OZ_out(0)=OZ_int(d);
return PROCEED;Finally procedure oz_init_module implements the native functor: it performs arbitrary initializations and then returns a table of builtins. Each entry in this table consists of (1) the name of the export, (2) the input arity, (3) the output arity, (4) the procedure implementing the builtin. The table must be terminated by an entry whose fields are all zero.
Note that global variable n is explicitly initialized by oz_init_module rather than with a static initializer. Here, it probably makes no difference, but you cannot in general rely on the fact that constructors for global objects will be properly invoked when the native functor is loaded. What actually happens varies from one system to another. The only reliable technique is to perform all initializations in oz_init_module.
You may also define the variable oz_module_name to give your native module a name that can be used when printing the builtins which it exports. This is particularly useful for debugging and for interactively looking at values. For example, you could give it the name "GlobalCounter":
char oz_module_name[] = "GlobalCounter";
We must now make this native module available as a shared object library. First we must compile it and create counter.o:
oztool c++ -c counter.ccThen we must produce a platform specific shared object library:
oztool ld counter.o -o counter.so-`oztool platform` You may find it useful to create a Makefile of the form:
PLATFORM = $(shell oztool platform)
NATIVES = counter
TARGETS = $(addsuffix .so-$(PLATFORM),$(NATIVES))
all: $(TARGETS)
%.so-$(PLATFORM): %.o
oztool ld $< -o $@
%.o: %.cc
oztool c++ -c $< -o $@
oztool is a program that invokes the facility named as its first argument with appropriate options. For example, it is essential to invoke the same C++ compiler and with the same e. g. code generation options as were used for building the Oz emulator; otherwise it will not be possible to dynamically link your library into a running Oz process. Normally, the Oz emulator is compiled without run time information (option -fno-rtti for g++) and without support for C++ exceptions (option -fno-exceptions for g++). oztool c++ automatically invokes the right compiler with the right options. oztool is documented in Chapter 6 of ``Oz Shell Utilities''.
Even more complicated is how to create a DLL from a compiled object file: it varies depending on the system, compiler and linker used. Under Windows, the sequence of necessary incantations is so arcane and highly magical, it could well endanger your sanity. Fortunately oztool ld automatically takes care of the details.
Normally, you will then place the resulting shared object file, e.g. counter.so-linux-i486 on a Linux system, in an installation directory; let's call it install. If your site has several platforms sharing one file system, then you can place all platform specific shared object libraries that you create from counter.cc in the same install directory. They all have distinct names since the platform name is appended.
In an Oz functor, you then write an import of the form:
Cnt at 'install/counter.so{native}'
The '{native}' suffix indicates to the system that this denotes a native functor whose platform independent basename is install/counter.so. The module manager dynamically links the appropriate platform specific shared object library (by appending the platform specific extension to the basename) and makes available the module it defines as the value of Cnt. The body of your functor can invoke {Cnt.next} to get the next value of the global counter.
In the emacs OPI, you can try this out immediately:
declare [M] = {Module.link ['install/counter.so{native}']}
| - Up - | Next >> |