Factory for Plugin classes. More...

#include <pluginFactory.h>

Collaboration diagram for lunchbox::PluginFactory< T >:

Public Types
typedef Plugin< T >	PluginT

typedef std::vector< PluginT >	Plugins

Public Member Functions
bool	handles (const typename T::InitDataT &initData)

T *	create (const typename T::InitDataT &initData)
	Create a plugin instance. More...

void	register_ (const PluginT &plugin)
	Register a plugin type. More...

bool	deregister (const PluginT &plugin)
	Deregister a plugin type. More...

void	deregisterAll ()
	Unregister all plugin types. More...

std::string	getDescriptions () const

Automatic loading of plugin DSOs.
void	load (const int version, const std::string &path, const std::string &pattern)
	Load all compatible plugin libraries from a directory matching a pattern. More...

void	load (const int version, const Strings &paths, const std::string &pattern)

Static Public Member Functions
static PluginFactory &	getInstance ()
	Get the single class instance. More...

Detailed Description

template<class T>
class lunchbox::PluginFactory< T >

Factory for Plugin classes.

The PluginFactory selects the a plugin for a given T::InitDataT, based on a plugin's handles() function. In case a InitDataT can be handled by multiple plugins, which plugin is chosen is undefined.

This class has been designed as a singleton to allow for link time plugin registration, but nothing prevents an application from registering new types at run time.

To do the registration of a plugin during the static initialization phase use the PluginRegisterer.

Example:

/* Copyright (c) 2013-2017, EPFL/Blue Brain Project
 *                          Raphael Dumusc <raphael.dumusc@epfl.ch>
 *
 * This file is part of Lunchbox <https://github.com/Eyescale/Lunchbox>
 *
 * This library is free software; you can redistribute it and/or modify it under
 * the terms of the GNU Lesser General Public License version 2.1 as published
 * by the Free Software Foundation.
 *
 * This library is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
 * details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */
#define BOOST_TEST_MODULE PluginFactory
#include <lunchbox/types.h>
struct InitData;
namespace std
{
string to_string(const InitData&);
}
#include <lunchbox/pluginFactory.h>
#include <lunchbox/pluginRegisterer.h>
#include <servus/uri.h>
#include <boost/test/unit_test.hpp>
#define VALID_VALUE 10
#define INVALID_VALUE 0
struct InitData
{
    InitData()
        : uri("test://uri")
    {
    }
    servus::URI uri;
};
namespace std
{
inline std::string to_string(const InitData& data)
{
    return std::to_string(data.uri);
}
}
class PluginInterface
{
public:
    typedef InitData InitDataT;
    typedef PluginInterface InterfaceT;
    virtual ~PluginInterface() {}
    virtual int getValue() = 0;
};
class Plugin : public PluginInterface
{
public:
    explicit Plugin(const InitData&) {}
    static bool handles(const InitData&) { return true; }
    static std::string getDescription() { return "I am a test plugin"; }
    int getValue() final { return VALID_VALUE; }
};
class FalsePlugin : public PluginInterface
{
public:
    explicit FalsePlugin(const InitData&) {}
    static bool handles(const InitData&) { return false; }
    static std::string getDescription() { return "I am a lazy plugin"; }
    int getValue() final { return INVALID_VALUE; }
};
typedef lunchbox::PluginFactory<PluginInterface> PluginFactory;
typedef std::shared_ptr<PluginInterface> PluginInterfacePtr;
PluginInterfacePtr createPlugin()
{
    return PluginInterfacePtr(PluginFactory::getInstance().create(InitData()));
}
BOOST_AUTO_TEST_CASE(throwNoneRegistered)
{
    PluginFactory::getInstance().deregisterAll();
    BOOST_CHECK_THROW(createPlugin(), std::runtime_error);
}
BOOST_AUTO_TEST_CASE(creation)
{
    auto& factory = PluginFactory::getInstance();
    factory.deregisterAll();
    lunchbox::PluginRegisterer<Plugin> registerer;
    PluginInterfacePtr plugin = createPlugin();
    BOOST_CHECK(plugin);
    BOOST_CHECK_EQUAL(plugin->getValue(), VALID_VALUE);
    BOOST_CHECK_EQUAL(factory.getDescriptions(), "I am a test plugin");
}
BOOST_AUTO_TEST_CASE(throwHandlesFailure)
{
    PluginFactory::getInstance().deregisterAll();
    lunchbox::PluginRegisterer<FalsePlugin> registerer;
    BOOST_CHECK_THROW(createPlugin(), std::runtime_error);
}
BOOST_AUTO_TEST_CASE(createCorrectVariant)
{
    auto& factory = PluginFactory::getInstance();
    factory.deregisterAll();
    lunchbox::PluginRegisterer<FalsePlugin> registerer1;
    lunchbox::PluginRegisterer<Plugin> registerer2;
    PluginInterfacePtr plugin = createPlugin();
    BOOST_CHECK(plugin);
    BOOST_CHECK_EQUAL(plugin->getValue(), VALID_VALUE);
    BOOST_CHECK_EQUAL(factory.getDescriptions(),
                      "I am a lazy plugin\n\nI am a test plugin");
}

Version: 1.11.0

Definition at line 56 of file pluginFactory.h.

Member Function Documentation

template<typename T >

T * lunchbox::PluginFactory< T >::create ( const typename T::InitDataT & initData )

Create a plugin instance.

Parameters

initData The initData passed to the plugin constructor.

Returns: A new PluginT instance. The user is responsible for deleting the returned object.

Exceptions

std::runtime_error if no plugin can handle the initData.

Version: 1.11.0

Definition at line 51 of file pluginFactory.ipp.

References LBTHROW.

template<typename T >

bool lunchbox::PluginFactory< T >::deregister ( const PluginT & plugin )

Deregister a plugin type.

Version: 1.11

Definition at line 68 of file pluginFactory.ipp.

template<typename T >

void lunchbox::PluginFactory< T >::deregisterAll ( )

Unregister all plugin types.

Version: 1.11

Definition at line 80 of file pluginFactory.ipp.

template<typename T >

std::string lunchbox::PluginFactory< T >::getDescriptions ( ) const

Returns: the descriptions of all registered plugins.

Version: 1.16

Definition at line 89 of file pluginFactory.ipp.

References lunchbox::PluginFactory< T >::load(), and lunchbox::usort().

Here is the call graph for this function:

template<typename T >

PluginFactory< T > & lunchbox::PluginFactory< T >::getInstance ( )

static

Get the single class instance.

Version: 1.11

Definition at line 25 of file pluginFactory.ipp.

Referenced by lunchbox::PluginRegisterer< T >::PluginRegisterer().

Here is the caller graph for this function:

template<typename T >

bool lunchbox::PluginFactory< T >::handles ( const typename T::InitDataT & initData )

Returns: true if any plugin handles the given parameter.

Version: 1.16

Definition at line 42 of file pluginFactory.ipp.

template<typename T >

void lunchbox::PluginFactory< T >::load	(	const int	version,
		const std::string &	path,
		const std::string &	pattern
	)

Load all compatible plugin libraries from a directory matching a pattern.

The pattern is the core name of the library, and is extended by the system-specific shared library suffix and postfix. The plugin has to implement the C functions 'int LunchboxPluginGetVersion()' and 'bool LunchboxPluginRegister()'. Only plugins with the same ABI version as the given one are registered.

Parameters

version	the current ABI version of the application loading the plugins.
path	the directory to search for plugins.
pattern	the core pattern of plugin names.