template class Poco::ClassLoader

Overview

The ClassLoader loads C++ classes from shared libraries at runtime. More…

#include <ClassLoader.h>

template <class Base>
class ClassLoader
{
public:
    // typedefs

    typedef AbstractMetaObject<Base> Meta;
    typedef Manifest<Base> Manif;
    typedef void (*InitializeLibraryFunc)();
    typedef void (*UninitializeLibraryFunc)();
    typedef bool (*BuildManifestFunc)(ManifestBase *);
    typedef std::map<std::string, LibraryInfo> LibraryMap;

    // structs

    struct LibraryInfo;

    // classes

    class Iterator;

    // methods

    void
    loadLibrary(
        const std::string& path,
        const std::string& manifest
        );

    void
    loadLibrary(const std::string& path);

    void
    unloadLibrary(const std::string& path);

    const Meta*
    findClass(const std::string& className) const;

    const Meta&
    classFor(const std::string& className) const;

    Base*
    create(const std::string& className) const;

    Base&
    instance(const std::string& className) const;

    bool
    canCreate(const std::string& className) const;

    void
    destroy(
        const std::string& className,
        Base* pObject
        ) const;

    bool
    isAutoDelete(
        const std::string& className,
        Base* pObject
        ) const;

    const Manif*
    findManifest(const std::string& path) const;

    const Manif&
    manifestFor(const std::string& path) const;

    bool
    isLibraryLoaded(const std::string& path) const;

    Iterator
    begin() const;

    Iterator
    end() const;
};

Detailed Documentation

The ClassLoader loads C++ classes from shared libraries at runtime.

It must be instantiated with a root class of the loadable classes. For a class to be loadable from a library, the library must provide a Manifest of all the classes it contains. The Manifest for a shared library can be easily built with the help of the macros in the header file “Foundation/ClassLibrary.h”.

Starting with POCO release 1.3, a class library can export multiple manifests. In addition to the default (unnamed) manifest, multiple named manifests can be exported, each having a different base class.

There is one important restriction: one instance of ClassLoader can only load one manifest from a class library.

Construction

virtual
~ClassLoader()

Destroys the ClassLoader.

Methods

void
loadLibrary(
    const std::string& path,
    const std::string& manifest
    )

Loads a library from the given path, using the given manifest.

Does nothing if the library is already loaded. Throws a LibraryLoadException if the library cannot be loaded or does not have a Manifest. If the library exports a function named “pocoInitializeLibrary”, this function is executed. If called multiple times for the same library, the number of calls to unloadLibrary() must be the same for the library to become unloaded.

void
loadLibrary(const std::string& path)

Loads a library from the given path.

Does nothing if the library is already loaded. Throws a LibraryLoadException if the library cannot be loaded or does not have a Manifest. If the library exports a function named “pocoInitializeLibrary”, this function is executed. If called multiple times for the same library, the number of calls to unloadLibrary() must be the same for the library to become unloaded.

Equivalent to loadLibrary(path, “”).

void
unloadLibrary(const std::string& path)

Unloads the given library.

Be extremely cautious when unloading shared libraries. If objects from the library are still referenced somewhere, a total crash is very likely. If the library exports a function named “pocoUninitializeLibrary”, this function is executed before it is unloaded. If loadLibrary() has been called multiple times for the same library, the number of calls to unloadLibrary() must be the same for the library to become unloaded.

const Meta*
findClass(const std::string& className) const

Returns a pointer to the MetaObject for the given class, or a null pointer if the class is not known.

const Meta&
classFor(const std::string& className) const

Returns a reference to the MetaObject for the given class.

Throws a NotFoundException if the class is not known.

Base*
create(const std::string& className) const

Creates an instance of the given class.

Throws a NotFoundException if the class is not known.

Base&
instance(const std::string& className) const

Returns a reference to the sole instance of the given class.

The class must be a singleton, otherwise an InvalidAccessException will be thrown. Throws a NotFoundException if the class is not known.

bool
canCreate(const std::string& className) const

Returns true if create() can create new instances of the class.

void
destroy(
    const std::string& className,
    Base* pObject
    ) const

Destroys the object pObject points to.

Does nothing if object is not found.

bool
isAutoDelete(
    const std::string& className,
    Base* pObject
    ) const

Returns true if the object is automatically deleted by its meta object.

const Manif*
findManifest(const std::string& path) const

Returns a pointer to the Manifest for the given library, or a null pointer if the library has not been loaded.

const Manif&
manifestFor(const std::string& path) const

Returns a reference to the Manifest for the given library Throws a NotFoundException if the library has not been loaded.

bool
isLibraryLoaded(const std::string& path) const

Returns true if the library with the given name has already been loaded.