Line data    Source code

       1             : 
       2             : /* Copyright (c) 2013-2017, 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/algorithm.h> // used inline
      26             : #include <lunchbox/debug.h>     // LBTHROW
      27             : #include <lunchbox/dso.h>       // used inline
      28             : #include <lunchbox/file.h>      // searchDirectory() used inline
      29             : #include <lunchbox/plugin.h>    // member
      30             : #include <lunchbox/types.h>
      31             : #include <servus/uri.h> // Default template type
      32             : 
      33             : #include <unordered_map>
      34             : 
      35             : namespace lunchbox
      36             : {
      37             : /**
      38             :  * Factory for Plugin classes.
      39             :  *
      40             :  * The PluginFactory selects the a plugin for a given T::InitDataT, based on a
      41             :  * plugin's handles() function. In case a InitDataT can be handled by multiple
      42             :  * plugins, which plugin is chosen is undefined.
      43             :  *
      44             :  * This class has been designed as a singleton to allow for link time plugin
      45             :  * registration, but nothing prevents an application from registering new types
      46             :  * at run time.
      47             :  *
      48             :  * To do the registration of a plugin during the static initialization phase
      49             :  * use the PluginRegisterer.
      50             :  *
      51             :  * Example: @include tests/pluginFactory.cpp
      52             :  *
      53             :  * @version 1.11.0
      54             :  */
      55             : template <class T>
      56             : class PluginFactory
      57             : {
      58             : public:
      59             :     typedef Plugin<T> PluginT;
      60             :     typedef std::vector<PluginT> Plugins;
      61             : 
      62             :     /** Get the single class instance. @version 1.11 */
      63             :     static PluginFactory& getInstance();
      64             : 
      65             :     /** @return true if any plugin handles the given parameter. @version 1.16 */
      66             :     bool handles(const typename T::InitDataT& initData);
      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             :     T* create(const typename T::InitDataT& initData);
      77             : 
      78             :     /** Register a plugin type. @version 1.11 */
      79             :     void register_(const PluginT& plugin);
      80             : 
      81             :     /** Deregister a plugin type. @version 1.11 */
      82             :     bool deregister(const PluginT& plugin);
      83             : 
      84             :     /** Unregister all plugin types. @version 1.11 */
      85             :     void deregisterAll();
      86             : 
      87             :     /** @return the descriptions of all registered plugins. @version 1.16 */
      88             :     std::string getDescriptions() const;
      89             : 
      90             :     /** @name Automatic loading of plugin DSOs. */
      91             :     //@{
      92             :     /**
      93             :      * Load all compatible plugin libraries from a directory matching a pattern.
      94             :      *
      95             :      * The pattern is the core name of the library, and is extended by the
      96             :      * system-specific shared library suffix and postfix. The plugin has to
      97             :      * implement the C functions 'int LunchboxPluginGetVersion()' and 'bool
      98             :      * LunchboxPluginRegister()'. Only plugins with the same ABI version as the
      99             :      * given one are registered.
     100             :      *
     101             :      * @param version the current ABI version of the application loading the
     102             :      *                plugins.
     103             :      * @param path the directory to search for plugins.
     104             :      * @param pattern the core pattern of plugin names.
     105             :      * @version 1.11.0
     106             :      * @sa getLibraryPath()
     107             :      */
     108             :     void load(const int version, const std::string& path,
     109             :               const std::string& pattern);
     110             :     void load(const int version, const Strings& paths,
     111             :               const std::string& pattern);
     112             :     //@}
     113             : 
     114             : private:
     115           1 :     PluginFactory() {}
     116             :     PluginFactory(const PluginFactory&) = delete;
     117             :     PluginFactory(PluginFactory&&) = delete;
     118             :     PluginFactory& operator=(const PluginFactory&) = delete;
     119             :     PluginFactory& operator=(PluginFactory&&) = delete;
     120             : 
     121             : #pragma warning(disable : 4251)
     122             :     Plugins _plugins;
     123             :     typedef std::unordered_map<DSO*, PluginT> PluginMap;
     124             :     PluginMap _libraries;
     125             : #pragma warning(default : 4251)
     126             : 
     127             :     ~PluginFactory();
     128             : };
     129             : }
     130             : 
     131             : #include "pluginFactory.ipp" // template implementation
     132             : 
     133             : #endif // LUNCHBOX_PLUGINFACTORY_H