Line data    Source code

       1             : 
       2             : /* Copyright (c) 2013-2015, EPFL/Blue Brain Project
       3             :  *                          Raphael Dumusc <raphael.dumusc@epfl.ch>
       4             :  *                          Stefan.Eilemann@epfl.ch
       5             :  *
       6             :  * This file is part of Lunchbox <https://github.com/Eyescale/Lunchbox>
       7             :  *
       8             :  * This library is free software; you can redistribute it and/or modify it under
       9             :  * the terms of the GNU Lesser General Public License version 2.1 as published
      10             :  * by the Free Software Foundation.
      11             :  *
      12             :  * This library is distributed in the hope that it will be useful, but WITHOUT
      13             :  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
      14             :  * FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
      15             :  * details.
      16             :  *
      17             :  * You should have received a copy of the GNU Lesser General Public License
      18             :  * along with this library; if not, write to the Free Software Foundation, Inc.,
      19             :  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
      20             :  */
      21             : 
      22             : #ifndef LUNCHBOX_PLUGINFACTORY_H
      23             : #define LUNCHBOX_PLUGINFACTORY_H
      24             : 
      25             : #include <lunchbox/types.h>
      26             : #include <lunchbox/algorithm.h> // used inline
      27             : #include <lunchbox/debug.h> // LBTHROW
      28             : #include <lunchbox/dso.h> // used inline
      29             : #include <lunchbox/file.h> // searchDirectory() used inline
      30             : #include <servus/uri.h> // Default template type
      31             : 
      32             : #include <boost/foreach.hpp> // used inline
      33             : #include <boost/lexical_cast.hpp> // used inline
      34             : #include <boost/noncopyable.hpp> // base class
      35             : #include <boost/unordered_map.hpp>
      36             : 
      37             : namespace lunchbox
      38             : {
      39             : 
      40             : /**
      41             :  * Factory for Plugin classes.
      42             :  *
      43             :  * The PluginFactory selects the a plugin for a given InitDataT, based on a
      44             :  * plugin's handles() function. In case a InitDataT can be handled by multiple
      45             :  * plugins, which plugin is chosen is undefined.
      46             :  *
      47             :  * This class has been designed as a singleton to allow for link time plugin
      48             :  * registration, but nothing prevents an application from registering new types
      49             :  * at run time.
      50             :  *
      51             :  * To do the registration of a plugin during the static initialization phase
      52             :  * use the PluginRegisterer.
      53             :  *
      54             :  * Example: @include tests/pluginFactory.cpp
      55             :  *
      56             :  * @version 1.11.0
      57             :  */
      58             : template< class PluginT, class InitDataT = servus::URI >
      59           4 : class PluginFactory : public boost::noncopyable
      60             : {
      61             : public:
      62             :     typedef Plugin< PluginT, InitDataT > PluginHolder;
      63             :     typedef std::vector< PluginHolder > Plugins;
      64             : 
      65             :     /** Get the single class instance. @version 1.11.0 */
      66             :     static PluginFactory& getInstance();
      67             : 
      68             :     /**
      69             :      * Create a plugin instance.
      70             :      * @param initData The initData passed to the plugin constructor.
      71             :      * @return A new PluginT instance. The user is responsible for deleting
      72             :      *         the returned object.
      73             :      * @throws std::runtime_error if no plugin can handle the initData.
      74             :      * @version 1.11.0
      75             :      */
      76             :     PluginT* create( const InitDataT& initData );
      77             : 
      78             :     /** Register a plugin type. @version 1.11.0 */
      79             :     void register_( const Plugin< PluginT, InitDataT >& plugin );
      80             : 
      81             :     /** Deregister a plugin type. @version 1.11.0 */
      82             :     bool deregister( const Plugin< PluginT, InitDataT >& plugin );
      83             : 
      84             :     /** Unregister all plugin types. @version 1.11.0 */
      85             :     void deregisterAll();
      86             : 
      87             :     /** @name Automatic loading of plugin DSOs. */
      88             :     //@{
      89             :     /**
      90             :      * Load all compatible plugin libraries from a directory matching a pattern.
      91             :      *
      92             :      * The pattern is the core name of the library, and is extended by the
      93             :      * system-specific shared library suffix and postfix. The plugin has to
      94             :      * implement the C functions 'int LunchboxPluginGetVersion()' and 'bool
      95             :      * LunchboxPluginRegister()'. Only plugins with the same ABI version as the
      96             :      * given one are registered.
      97             :      *
      98             :      * @param version the current ABI version of the application loading the
      99             :      *                plugins.
     100             :      * @param path the directory to search for plugins.
     101             :      * @param pattern the core pattern of plugin names.
     102             :      * @return the loaded plugins, ownership remains with the PluginFactory.
     103             :      * @version 1.11.0
     104             :      * @sa getLibraryPath()
     105             :      */
     106             :     DSOs load( const int version, const std::string& path,
     107             :                const std::string& pattern );
     108             :     DSOs load( const int version, const Strings& paths,
     109             :                const std::string& pattern );
     110             : 
     111             :     /**
     112             :      * Unload and deregister a previously loaded plugin
     113             :      *
     114             :      * @return true if the plugin was loaded, false on error.
     115             :      * @version 1.11.0
     116             :      */
     117             :     bool unload( DSO* dso );
     118             :     //@}
     119             : 
     120             : private:
     121             :     Plugins _plugins;
     122             : 
     123             :     typedef boost::unordered_map< DSO*, PluginHolder > PluginMap;
     124             :     PluginMap _libraries;
     125             : 
     126             :     void _load( DSOs& result, const int version, const std::string& path,
     127             :                 const std::string& pattern );
     128             : };
     129             : 
     130             : }
     131             : 
     132             : #include "pluginFactory.ipp" // template implementation
     133             : 
     134             : #endif // LUNCHBOX_PLUGINFACTORY_H