lang/plugins.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header file is part of the \aliblong. It does not belong to an \alibmod and is
/// included in any \alibdist. However it can be used only if \alib_enums is part of the
/// distribution.
///
/// \emoji :copyright: 2013-2024 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
#ifndef HPP_ALIB_LANG_PLUGINS
#define HPP_ALIB_LANG_PLUGINS 1
#pragma once
#if !defined(DOXYGEN)
#   include "alib/alib.hpp"
#endif
 
ALIB_ASSERT_MODULE(ENUMS)
 
#include "alib/lang/commonenumdefs.hpp"
#include "alib/enums/bitwise.hpp"
 
#include <vector>
#include <algorithm>
 
namespace alib::lang {
 
//==================================================================================================
/// This class usually is used as a base class for types that need to manage simple plug-ins.
/// Within \alib itself, for example classes \alib{config;Configuration} and
/// \alib{expressions;Compiler} inherit from this class.
///
/// Plug-ins are organized with a prioritization. This means, that plug-ins which are inserted with
/// a higher priority are 'asked' first, and those with a lower value become 'asked' only if higher
/// prioritized plug-ins did not answer.<br>
/// However, a derived class can deviate from this behavior. Using the typical \alib class design,
/// all internal fields are \c protected, hence freely accessible by derived classes.
///
/// \par Availability
///   While this class is located in the core namespace #alib::lang, it is compilable only
///    in case module \alib_enums is included in the \alibdist.
///
/// @tparam TPlugin     The plug-in type that this class manages. This type is publicly exposed as
///                     #PluginType
///                     This type is publicly exposed as #PrioritiesType.
//==================================================================================================
template<typename TPlugin, typename TPriorities>
class Plugin
{
  public:
    /// This exposes the template parameter \p{TPlugin} to the outer world.
    using PluginType=          TPlugin;
 
    /// This exposes the template parameter \p{pTPlugin} to the outer world.
    using PrioritiesType=      TPriorities;
 
  protected:
    /// The priority of this plug-in.
    PrioritiesType              priority;
 
    /// Constructor which is protected, as this is a bace class.
    /// @param pPriority   The priority that this plug-in uses.
    Plugin( PrioritiesType pPriority)
    : priority (pPriority)                                                                        {}
 
  public:
    /// Returns the priority of this plug-in which is set during construction.
    /// @return The priority of this plugin.
    PrioritiesType             GetPriority()                        const  { return priority; }
 
}; //class Plugin
    
//==================================================================================================
/// This class usually is used as a base class for types that need to manage simple plug-ins.
/// Within \alib itself, for example classes \alib{config;Configuration} and
/// \alib{expressions;Compiler} inherit from this class.
///
/// Plug-ins are organized with a prioritization. This means, that plug-ins which are inserted with
/// a higher priority are 'asked' first, and those with a lower value become 'asked' only if higher
/// prioritized plug-ins did not answer.<br>
/// However, a derived class can deviate from this behavior. Using the typical \alib class design,
/// all internal fields are \c protected, hence freely accessible by derived classes.
///
/// @tparam TPlugin     The type of the plug-ins managed. This type is publicly exposed as
///                     #PluginType.
/// @tparam TPriorities The enumeration type providing the default "plug-in slots" and priorities
///                     of the plug-ins managed. This type is publicly exposed as #PrioritiesType.
//==================================================================================================
template<typename TPlugin, typename TPriorities>
class PluginContainer
{
    // #############################################################################################
    // public fields and types
    // #############################################################################################
    public:
 
        /// This exposes the template parameter \p{pTPlugin} to the outer world.
        using PluginType=          TPlugin;
 
        /// This exposes the template parameter \p{pTPlugin} to the outer world.
        using PrioritiesType=      TPriorities;
 
        /// Type definition for elements of the list of plug-ins with their priority.
        struct  Slot
        {
            TPlugin*    plugin;    ///< The plug-in.
            bool        owned;     ///< If \c true, this container is responsible for deleting
                                   ///< the plug-in object.
        };
 
    // #############################################################################################
    // internal fields
    // #############################################################################################
    protected:
 
        /// The plug-ins we have attached in descending priority order.
        std::vector<Slot>           plugins;
 
    // #############################################################################################
    // Constructor/destructor
    // #############################################################################################
    public:
        //==========================================================================================
        /// Destructor. All plug-ins that were inserted with parameter \p{responsibility} set to
        /// \alib{lang;Responsibility::Transfer} will be deleted.
        //==========================================================================================
                       ~PluginContainer()
        {
            for( auto& slot : plugins )
                if( slot.owned )
                    delete slot.plugin;
        }
 
 
 
    // #############################################################################################
    // interface
    // #############################################################################################
    public:
        //==========================================================================================
        /// Adds the given plug-in to the list of plug-ins.
        ///
        /// @param plugin          The plug-in to insert.
        /// @param responsibility  If \c Responsibility::Transfer, the given plugin will be deleted
        ///                        with destruction of this object.
        ///                        Defaults to \c Responsibility::KeepWithSender which denotes that
        ///                        the life-cycle of the given external buffer is managed elsewhere.
        //==========================================================================================
        void                InsertPlugin( TPlugin* plugin, lang::Responsibility responsibility
                                                           = lang::Responsibility::KeepWithSender )
        {
            ALIB_ASSERT_ERROR( plugin != nullptr, "FSPLUGINS", "Nullptr provided for plugin." )
 
            ALIB_STATIC_ASSERT( Plugin_type_not_virtual,
                                   std::has_virtual_destructor<TPlugin>::value
                                || responsibility == lang::Responsibility::KeepWithSender,
            "Can't take responsibility for plug-in destruction. TPlugin has no virtual destructor.")
 
            // gcc needs this captured, clang warns.
            // Its about the ALIB_CALLER inside ALIB_ASSERT_ERROR
            ALIB_WARNINGS_IGNORE_UNUSED_LAMBDA_CAPTURE
            plugins.insert( std::find_if( plugins.begin(),  plugins.end(),
                                          [plugin,this]( Slot& ppp)
                                          {
                                              ALIB_ASSERT_ERROR( ppp.plugin->GetPriority() != plugin->GetPriority(), "FSPLUGINS",
                                               "PluginContainer::InsertPlugin(): Plug-in with same priority exists" )
 
                                              return ppp.plugin->GetPriority() < plugin->GetPriority();
                                          } ),
 
                            Slot { plugin, responsibility == lang::Responsibility::Transfer }
                          );
            ALIB_WARNINGS_RESTORE
        }
 
 
        //==========================================================================================
        /// Removes the given plug-in from the list of plug-ins.
        ///
        /// Responsibility for deletion of removed plug-ins is passed to the remover in case the
        /// plug-in was inserted with parameter \p{responsibility} set to
        /// \alib{lang;Responsibility::Transfer}.
        ///
        /// @param plugIn  The plug-in to be removed.
        /// @return \c true if the plug-in was removed, else \c false, which indicates that the
        ///         given plug-in was not found.
        //==========================================================================================
        bool                RemovePlugin( TPlugin* plugIn )
        {
            auto it= std::find_if( plugins.begin(), plugins.end(), [plugIn](Slot& pair)
                                                                   {
                                                                       return pair.plugin == plugIn;
                                                                   } );
            if( it != plugins.end() )
            {
                plugins.erase( it );
                return true;
            }
 
            ALIB_WARNING( "PluginContainer::RemovePlugin(): Plug-in not found for removal." )
            return  false;
        }
 
        //==========================================================================================
        /// Remove the plug-in at the given \p{idx} from the list of plug-ins.
        ///
        /// Responsibility for deletion of removed plug-ins is passed to the remover in case the
        /// plug-in was inserted with parameter \p{responsibility} set to
        /// \alib{lang;Responsibility::Transfer}.
        ///
        /// @param idx  The index of the plug-in to remove.
        //==========================================================================================
        void                RemovePlugin( integer idx )
        {
            ALIB_ASSERT_WARNING( idx < CountPlugins(),
                 "FSPLUGINS", "PluginContainer::RemovePlugin(): Index out of bounds: ", idx )
            plugins.erase( plugins.begin() + idx );
        }
 
 
        //==========================================================================================
        /// Remove the plug-in with the given priority.
        ///
        /// Responsibility for deletion of removed plug-ins is passed to the remover in case the
        /// plug-in was inserted with parameter \p{responsibility} set to
        /// \alib{lang;Responsibility::Transfer}.
        ///
        /// @param priority  The priority of the plug-in to remove.
        /// @return \c true if the plug-in was removed, else \c false, which indicates that no
        ///         plug-in with the given priority was found.
        //==========================================================================================
        TPlugin*            RemovePlugin( TPriorities priority )
        {
            TPlugin* plugin= nullptr;
            plugins.erase( std::remove_if(  plugins.begin(), plugins.end(),
                                            [priority, &plugin](Slot& entry)
                                            {
                                                if( entry.priority == priority)
                                                {
                                                    plugin= entry.plugin;
                                                    return true;
                                                }
                                                return false;
                                            } ),
                           plugins.end() );
 
            ALIB_ASSERT_WARNING( plugin, "FSPLUGINS",
                                 "PluginContainer::RemovePlugin(): No Plug-in was removed " )
 
            return  plugin;
        }
 
 
        //==========================================================================================
        /// Checks if any plug-in is attached. This is useful if optional configuration objects
        /// are used. In case no plug-in was attached (by a third party), the effort to declare and
        /// search a variable can be omitted.
        /// @return \c true if this object has any plugin set, \c false otherwise.
        //==========================================================================================
        bool                HasPlugins()
        {
            return CountPlugins() > 0;
        }
 
        //==========================================================================================
        /// Returns the number of plug-ins attached.
        /// @return The quantity of attached plug-ins.
        //==========================================================================================
        integer             CountPlugins()
        {
            return static_cast<integer>(plugins.size());
        }
 
        //==========================================================================================
        /// Returns the plug-in with the given internal number. Valid numbers are
        /// 0..[#CountPlugins]. No internal checks for valid plug-in numbers are made.
        ///
        /// @param number The number of the plug-in requested.
        /// @return The plug-in requested.
        //==========================================================================================
        TPlugin*            GetPlugin( integer number )
        {
            return plugins[size_t(number)].plugin;
        }
 
        //==========================================================================================
        /// Returns the priority of the plug-in with the given internal number. Valid numbers are
        /// 0..[#CountPlugins]. No internal checks for valid plug-in numbers are made.
        ///
        /// @param number The number of the plug-in requested.
        /// @return The priortiy of the plug-in.
        //==========================================================================================
        TPriorities         GetPriority( integer number )
        {
            return plugins[size_t(number)].priority;
        }
 
 
        //==========================================================================================
        /// Returns the plug-in with the given priority. If the plug-in does not exist, \c nullptr
        /// is returned.
        ///
        /// @param priority The priority of the plug-in to return.
        /// @return The plug-in requested or \c nullptr if not available.
        //==========================================================================================
        TPlugin*            GetPlugin( TPriorities priority )
        {
            auto it = std::find_if( plugins.begin(), plugins.end(),
                                    [priority](Slot& pair) { return pair.priority == priority; } );
            if( it != plugins.end() )
                return it->plugin;
            return nullptr;
        }
 
        //==========================================================================================
        /// Same as #GetPlugin, but converts the plug-in found to the template type, which has
        /// to be explicitly provided with the invocation of this method.
        ///
        /// A type-check is performed using standard C++ \c dynamic_cast mechanics.
        /// If the plugin has a different type, \c nullptr is returned.
        ///
        /// @tparam TPluginType The type of the plugin to search.
        /// @param priority The priority of the plug-in to return.
        /// @return The plug-in of requested type and priority. \c nullptr if not available.
        //==========================================================================================
        template<typename TPluginType>
        TPluginType*        GetPluginTypeSafe( TPriorities priority )
        {
            return dynamic_cast<TPluginType*>( GetPlugin( priority ) );
        }
 
        //==========================================================================================
        /// Searches the list of plug-ins for the first found with type \p{TPluginType}.
        ///
        /// @tparam TPluginType The type of the plugin to search.
        /// @return The plug-in of requested type. \c nullptr if not available.
        //==========================================================================================
        template<typename TPluginType>
        TPluginType*        GetPluginTypeSafe()
        {
            TPluginType* cast= nullptr;
            for( auto& ppp : plugins )
                if( (cast= dynamic_cast<TPluginType*>( ppp.plugin )) != nullptr )
                    break;
 
            return cast;
        }
 
}; // class PluginContainer
 
} // namespace [alib::lang]
 
#endif // HPP_ALIB_LANG_PLUGINS