System.Plugins.DynamicLoader

A module that implements dynamic loading. You can load and use GHC object files and packages dynamically at runtime.

Documentation

data DynamicModule

dm_path :: DynamicModule -> FilePath

data DynamicPackage

dp_path :: DynamicPackage -> FilePath

addDLL :: String -> IO ()

Dynamically load a shared library (DLL or .so). A shared library can't be unloaded using this interface, if you need it use System.Posix.DynamicLinker instead.

loadModule :: String -> Maybe FilePath -> Maybe String -> IO DynamicModule

Load a module given its name (for instance Data.FiniteMap), maybe a path to the base directory and maybe a file extension. If no such path is given the current working directory is used and if no file suffix is given "o" is used.

If we have our module hierarchy in /usr/lib/modules and we want to load the module Foo.Bar located in /usr/lib/modules/Foo/Bar.o we could issue the command:

loadModule "Foo.Bar" (Just "/usr/lib/modules") Nothing

If our current directory was /tmp and we wanted to load the module Foo located in the file /tmp/Foo.obj we would write:

loadModule "Foo" Nothing (Just "obj")

If it cannot load the object it will throw an exception.

loadModuleFromPath :: FilePath -> Maybe FilePath -> IO DynamicModule

Load a module given its full path and maybe a base directory to use in figuring out the module's hierarchical name. If no base directory is given, it is set to the current directory.

For instance if one wants to load module Foo.Bar located in /usr/modules/Foo/Bar.o one would issue the command:

loadModuleFromPath "/usr/modules/Foo/Bar.o" (Just
"/usr/modules")

If it cannot load the object it will throw an exception.

loadPackage :: String -> Maybe FilePath -> Maybe String -> Maybe String -> IO DynamicPackage

Load a GHC package such as "base" or "text". Takes the package name, maybe a path to the packages, maybe a package prefix and maybe a package suffix.

Path defaults to the current directory, package prefix to "HS" and package suffix to "o".

This function also loads accompanying cbits-packages. I.e. if you load the package base located in /usr/modules using HS and o as prefix and suffix, loadPackage will also look for the file /usr/modules/HSbase_cbits.o and load it if present.

If it fails to load a package it will throw an exception. You will need to resolve functions before you use any functions loaded.

loadPackageFromPath :: FilePath -> IO DynamicPackage

Load a GHC package such as "base" or "text". Takes the full path to the package.

This function also loads accompanying cbits-packages. I.e. if you load the package /usr/modules/HSbase.o it will deduce that o is the suffix and loadPackageFromPath will then also look for the file /usr/modules/HSbase_cbits.o and load it if present.

If it fails to load a package it will throw an exception. You will need to resolve functions before you use any functions loaded.

unloadModule :: DynamicModule -> IO ()

Unload a previously loaded module. If it cannot unload it an exception will be thrown.

unloadPackage :: DynamicPackage -> IO ()

Unload a package (such as base) and its cbits-package (if any). Throws an exception if any unloading fails.

loadFunction :: DynamicModule -> String -> IO a

Load a function from a given module. If the function can't be found an exception will be thrown. You should have called resolveFunctions before you call this.

Beware that this function isn't type-safe in any way!

loadQualifiedFunction :: String -> IO a

Load a function from package (or module) given the fully qualified name (e.g. Data.FiniteMap.emptyFM). If the function can't be found an exception will be thrown. You should have called resolveFunctions before you call this.

You must take care that you load the function qualified with the name of the module it's defined in! You can for instance not load Data.Bool.not because it is only reexported in that module (from GHC.Base).

Beware that this function isn't type-safe in any way!

resolveFunctions :: IO ()

Resolve all loaded functions. Should be called before any functions are loaded. If it is unable to resolve all functions it will throw an exception.