ddl.Linker

Authors:
Eric Anderton

License:
BSD Derivative (see source for details)

class LinkModuleException: object.Exception;
Exception class used exclusively by the Linker.

LinkModuleException are generated when the linker cannot resolve a module during the linking process.

DynamicModule reason();
Module that prompted the link exception.

this(DynamicModule reason);
Constructor.

DynamicModule reason the module that prompts the exception


class Linker;
General-Purpose runtime linker for DDL.

protected DynamicLibrary[] libraries;
Library list for libraries used for linking.

The implementation here is deliberately simple -- some would call it brain-dead. The developer is therefore strongly encouraged to subclass this in order to develop more sophisticated linking and library management behaviors.

The order of insertion into the library list is used as a priority scheme when attempting to link new modules into the runtime. The first library added to the linker should be the current in-situ library, should linking to classes and types in the current runtime be a requirement. In any case the next candidates for addition to the linker should be the runtime libraries in no particular order.

The linker will attept to link against the first library first, and so on down the list.

this(LoaderRegistry registry);
The linker uses an LoaderRegistry to handle internal library dependencies automatically, such that the developer can more easily automate linking behavior.

LoaderRegistry registry the LoaderRegistry to use when loading binaries.


LoaderRegistry getRegistry();
Returns:
the current registry

protected void initModule(ModuleInfo m, int skip);
Initalizes a ModuleInfo instance from a DynamicModule.

From here on the provided library

void link(DynamicModule mod, inout ModuleInfo[DynamicModule] moduleSet, bool canSelfResolve = false);
Links a module against the linker's internal cross-reference.

This implementation performs a long search of modules, then discrete symbols in the cross-reference.

The parameter canSelfResolve is passed as 'true' for registraion variants of link routines.

moduleSet a set of modules that need initalization following the link pass.

void link(DynamicLibrary lib);
Links a library against the linker's internal cross-reference.

There is a subtle difference between linking a lib and linking a lib that has been added to the cross-reference. If every module in the lib is merely dependent upon modules that exist in the cross-reference already, then just calling link will do the task. Otherwise, the lib should be added to the cross-reference first, before proceeding with the actual link.

Examples:
		DynamicLibrary lib
;
		Linker linker;

		linker.register(lib
); // add to xref first
		linker.link(lib
); // link in the library and its aggregate modules


DynamicLibrary load(char[] filename, char[] attrStdVersion = "");
Loads a library for the filename.

If the attrStdVersion parameter is supplied this is matched against the "std.version" attribute in the supplied library. If the attribute doesn't exist, and or the attrStdVersion attribute is omitted or set to "", then the library is loaded anyway. Otherwise, should attrStdVersion not match the "std.version" attribute, the method throws an exception.

char[] filename the filename of the library to load
char[] attrStdVersion (optional) value to match to attribute "std.version" in the loaded library.


void register(DynamicLibrary lib);
Registers a library with the linker to be used during link operations.

DynamicLibrary loadAndRegister(char[] filename, char[] attrStdVersion = "");
Loads a DDL library and registers it with this linker.

Returns:
the DynamicLibrary that corresponds to filename

char[] filename the file name of the library to load


DynamicLibrary loadAndLink(char[] filename, char[] attrStdVersion = "");
Loads a DDL library and links it against all registered libraries.

Returns:
the DynamicLibrary that corresponds to filename

char[] filename the file name of the library to load


DynamicLibrary loadLinkAndRegister(char[] filename, char[] attrStdVersion = "");
Loads a DDL library, links it against all registered libraries, and registers it.

Returns:
the DynamicLibrary that corresponds to filename

char[] filename the file name of the library to load