Release v1.1

Author: arobenko

CMakeLists.txt

@@ -160,7 +160,7 @@ set (DATA_INSTALL_REL_DIR ${CMAKE_INSTALL_DATAROOTDIR}/${INSTALL_NAME})
 set (DATA_INSTALL_DIR ${INSTALL_DIR}/${DATA_INSTALL_REL_DIR})
 set (DOC_INSTALL_DIR ${INSTALL_DIR}/${CMAKE_INSTALL_DATAROOTDIR}/doc)
 set (ICON_INSTALL_DIR ${DATA_INSTALL_DIR}/icon)
-set (CONFIG_INSTALL_REL_DIR ${CMAKE_INSTALL_SYSCONFDIR}/${INSTALL_NAME})
+set (CONFIG_INSTALL_REL_DIR ${CMAKE_INSTALL_DATADIR}/${INSTALL_NAME})
 set (CONFIG_INSTALL_DIR ${INSTALL_DIR}/${CONFIG_INSTALL_REL_DIR})
 
 install (DIRECTORY cmake DESTINATION ${LIB_INSTALL_DIR}/${INSTALL_NAME})

comms/doc/comms.dox

@@ -28,6 +28,9 @@
 /// @namespace comms::traits::units
 /// @brief Namespace for various traits tag classes used in units conversion operations.
 
+/// @namespace comms::traits::dispatch
+/// @brief Namespace for various traits tag classes used in dispatch operations.
+
 /// @namespace comms::units
 /// @brief Namespace containing units conversion operations
 

comms/doc/page_dispatch.dox

@@ -2441,6 +2441,10 @@
 /// third template parameter (which defaults to @b void), can be used to
 /// specify the return type of handling functions.
 ///
+/// @b NOTE, since version @b v1.1 the @b COMMS library supports other
+/// ways to dispatch a message object to its handling function in addition
+/// to one described above. Please read @ref page_dispatch page for more details.
+///
 /// @section page_use_prot_extra_transport Extra Transport Values
 /// Some protocols may use extra values in their transport information, which 
 /// may influence the way how message payload is being read and/or message 

comms/doc/page_use_prot.dox

@@ -27,7 +27,7 @@
 #include "comms/util/Tuple.h"
 #include "comms/util/alloc.h"
 #include "details/MsgFactoryOptionsParser.h"
-#include "details/MsgFactorySelector.h"
+#include "details/MsgFactoryBase.h"
 
 namespace comms
 {
@@ -39,8 +39,7 @@ namespace comms
 ///     embedded environment.@n
 ///     The types of all messages provided in @b TAllMessages are analysed at
 ///     compile time and best "id to message object" mapping strategy is chosen,
-///     whether it is direct access array (with O(1) time complexity) or
-///     sorted array with binary search (with O(log(n)) time complexity).
+///     unless the "dispatch" type forcing options are used (see description below).
 /// @tparam TMsgBase Common base class for all the messages, smart pointer to
 ///     this type is returned when allocation of specify message is requested.
 /// @tparam TAllMessages All custom message types, that this factory is capable
@@ -72,60 +71,88 @@ namespace comms
 ///         the base class of @ref comms::GenericMessage type (first template
 ///         parameter) must be equal to @b TMsgBase (first template parameter)
 ///         of @b this class.
+///     @li @ref comms::option::ForceDispatchPolymorphic, 
+///         @ref comms::option::ForceDispatchStaticBinSearch, or
+///         @ref comms::option::ForceDispatchLinearSwitch - Force a particular
+///         dispatch way when creating message object given the numeric ID
+///         (see @ref comms::MsgFactory::createMsg()). The dispatch methods
+///         are properly described in @ref page_dispatch tutorial page.
+///         If none of these options are provided, then the MsgFactory
+///         used a default way, which is equivalent to calling 
+///         @ref comms::dispatchMsgType() (see also @ref page_dispatch_message_type_default).
+///         To inquire what actual dispatch type is used, please use one
+///         of the following constexpr member functions: 
+///         @ref comms::MsgFactory::isDispatchPolymorphic(),
+///         @ref comms::MsgFactory::isDispatchStaticBinSearch(), and
+///         @ref comms::MsgFactory::isDispatchLinearSwitch()
 /// @pre TMsgBase is a base class for all the messages in TAllMessages.
 /// @pre Message type is TAllMessages must be sorted based on their IDs.
 /// @pre If comms::option::InPlaceAllocation option is provided, only one custom
 ///     message can be allocated. The next one can be allocated only after previous
 ///     message has been destructed.
 /// @headerfile comms/MsgFactory.h
 template <typename TMsgBase, typename TAllMessages, typename... TOptions>
-class MsgFactory
+class MsgFactory : private details::MsgFactoryBase<TMsgBase, TAllMessages, TOptions...>
 {
+    using Base = details::MsgFactoryBase<TMsgBase, TAllMessages, TOptions...>;
     static_assert(TMsgBase::InterfaceOptions::HasMsgIdType,
         "Usage of MsgFactory requires Message interface to provide ID type. "
         "Use comms::option::MsgIdType option in message interface type definition.");
 
-    using Factory = typename
-        details::MsgFactorySelector<TMsgBase, TAllMessages, TOptions...>::Type;
-
 public:
     /// @brief Parsed options
-    using ParsedOptions = typename Factory::ParsedOptions;
+    using ParsedOptions = typename Base::ParsedOptions;
 
     /// @brief Type of the common base class of all the messages.
-    using Message = TMsgBase;
+    using Message = typename Base::Message;
 
     /// @brief Type of the message ID when passed as a parameter.
-    using MsgIdParamType = typename Message::MsgIdParamType;
+    using MsgIdParamType = typename Base::MsgIdParamType;
 
     /// @brief Type of the message ID.
-    using MsgIdType = typename Message::MsgIdType;
+    using MsgIdType = typename Base::MsgIdType;
 
     /// @brief Smart pointer to @ref Message which holds allocated message object.
     /// @details It is a variant of std::unique_ptr, based on whether
     ///     comms::option::InPlaceAllocation option was used.
-    using MsgPtr = typename Factory::MsgPtr;
+    using MsgPtr = typename Base::MsgPtr;
 
     /// @brief All messages provided as template parameter to this class.
-    using AllMessages = TAllMessages;
+    using AllMessages = typename Base::AllMessages;
+
+#ifdef FOR_DOXYGEN_DOC_ONLY
+    // @brief Reason for message creation failure
+    enum class CreateFailureReason
+    {
+        None, ///< No reason
+        InvalidId, ///< Invalid message id
+        AllocFailure, ///< Allocation of the object has failied
+        NumOfValues ///< Number of available values, must be last
+    };
+#else // #ifdef FOR_DOXYGEN_DOC_ONLY
+    using CreateFailureReason = typename Base::CreateFailureReason;
+#endif // #ifdef FOR_DOXYGEN_DOC_ONLY
 
     /// @brief Create message object given the ID of the message.
+    /// @details The id to mapping is performed using the chosen (or default) 
+    ///     @b dispatch policy described in the class options.
     /// @param id ID of the message.
-    /// @param idx Relative index of the message with the same ID. In case
+    /// @param idx Relative index (or offset) of the message with the same ID. In case
     ///     protocol implementation contains multiple distinct message types
     ///     that report same ID value, it must be possible to choose the
     ///     relative index of such message from the first message type reporting
     ///     the same ID. This parameter provides such an ability. However,
     ///     most protocols will implement single message class for single ID.
     ///     For such implementations, use default value of this parameter.
+    /// @param[out] reason Failure reason in case creation has failed. May be nullptr.
     /// @return Smart pointer (variant of std::unique_ptr) to @ref Message type,
     ///     which is a common base class of all the messages (provided as
     ///     first template parameter to this class). If comms::option::InPlaceAllocation
     ///     option was used and previously allocated message wasn't de-allocated
     ///     yet, the empty (null) pointer will be returned.
-    MsgPtr createMsg(MsgIdParamType id, unsigned idx = 0) const
+    MsgPtr createMsg(MsgIdParamType id, unsigned idx = 0, CreateFailureReason* reason = nullptr) const
     {
-        return factory_.createMsg(id, idx);
+        return Base::createMsg(id, idx, reason);
     }
 
     /// @brief Allocate and initialise @ref comms::GenericMessage object.
@@ -136,26 +163,59 @@ class MsgFactory
     ///     constructor of the @ref comms::GenericMessage class
     MsgPtr createGenericMsg(MsgIdParamType id) const
     {
-        return factory_.createGenericMsg(id);
+        return Base::createGenericMsg(id);
     }
 
+    /// @brief Inquiry whether allocation is possible
+    bool canAllocate() const
+    {
+        return Base::canAllocate();
+    }
     /// @brief Get number of message types from @ref AllMessages, that have the specified ID.
     /// @param id ID of the message.
     /// @return Number of message classes that report same ID.
     std::size_t msgCount(MsgIdParamType id) const
     {
-        return factory_.msgCount(id);
+        return Base::msgCount(id);
     }
 
-    /// @brief Compile time knowldege inquiry whether all the message classes in the
+    /// @brief Compile time inquiry whether all the message classes in the
     ///     @b TAllMessages bundle have unique IDs.
     static constexpr bool hasUniqueIds()
     {
-        return Factory::hasUniqueIds();
+        return Base::hasUniqueIds();
+    }
+
+    /// @brief Compile time inquiry whether polymorphic dispatch tables are 
+    ///     generated internally to map message ID to actual type.
+    /// @see @ref page_dispatch
+    /// @see @ref comms::MsgFactory::isDispatchStaticBinSearch()
+    /// @see @ref comms::MsgFactory::isDispatchLinearSwitch()
+    static constexpr bool isDispatchPolymorphic()
+    {
+        return Base::isDispatchPolymorphic();
+    }
+
+    /// @brief Compile time inquiry whether static binary search dispatch is 
+    ///     generated internally to map message ID to actual type.
+    /// @see @ref page_dispatch
+    /// @see @ref comms::MsgFactory::isDispatchPolymorphic()
+    /// @see @ref comms::MsgFactory::isDispatchLinearSwitch()
+    static constexpr bool isDispatchStaticBinSearch()
+    {
+        return Base::isDispatchStaticBinSearch();
+    }
+
+    /// @brief Compile time inquiry whether linear switch dispatch is 
+    ///     generated internally to map message ID to actual type.
+    /// @see @ref page_dispatch
+    /// @see @ref comms::MsgFactory::isDispatchStaticBinSearch()
+    /// @see @ref comms::MsgFactory::isDispatchLinearSwitch()
+    static constexpr bool isDispatchLinearSwitch()
+    {
+        return Base::isDispatchLinearSwitch();
     }
 
-private:
-    Factory factory_;
 };
 
 

comms/include/comms/MsgFactory.h

@@ -25,6 +25,8 @@
 #include "protocols.h"
 #include "units.h"
 #include "version.h"
+#include "dispatch.h"
+#include "field_cast.h"
 
 #include "Message.h"
 #include "EmptyHandler.h"

comms/include/comms/comms.h

@@ -0,0 +1,91 @@
+//
+// Copyright 2019 (C). Alex Robenko. All rights reserved.
+//
+
+// This library is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program 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 General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+#pragma once
+
+#include <type_traits>
+#include <limits>
+
+#include "comms/Message.h"
+#include "comms/MessageBase.h"
+#include "comms/util/Tuple.h"
+#include "comms/details/message_check.h"
+#include "comms/CompileControl.h"
+
+namespace comms
+{
+
+namespace details
+{
+
+template <typename TMessage>
+class DispatchMsgIdRetrieveHelper
+{
+public:
+    static_assert(TMessage::hasMsgIdType(), "Message interface class must define its id type");
+    using MsgIdParamType = typename TMessage::MsgIdParamType;
+    using MsgIdType = typename TMessage::MsgIdType;
+
+    static MsgIdParamType doGetId()
+    {
+        using Tag = 
+            typename std::conditional<
+                messageHasStaticNumId<TMessage>(),
+                HasStaticIdTag,
+                typename std::conditional<
+                    comms::isMessage<TMessage>() && TMessage::hasGetId(),
+                    HasDynamicIdTag,
+                    NoIdTag
+                >::type
+            >::type;
+
+        static_assert(!std::is_same<Tag, NoIdTag>::value, "Must be able to retrieve ID");
+        return doGetIdInternal(Tag());
+    }
+
+private:
+    struct HasStaticIdTag {};
+    struct HasDynamicIdTag {};
+    struct NoIdTag {};
+    
+    static MsgIdParamType doGetIdInternal(HasStaticIdTag)
+    {
+        static_assert(comms::isMessageBase<TMessage>(), "Must be actual message");
+        static_assert(messageHasStaticNumId<TMessage>(), "Message must define static numeric ID");
+
+        return TMessage::doGetId();
+    }      
+
+    static MsgIdParamType doGetIdInternal(HasDynamicIdTag)
+    {
+        static_assert(comms::isMessage<TMessage>(), "Must be actual message");
+        static_assert(TMessage::hasGetId(), "Message interface must be able to return id polymorphically");
+
+        static const MsgIdType Id = TMessage().getId();
+        return Id;
+    }        
+};
+
+template <typename TMessage>
+auto dispatchMsgGetMsgId() -> decltype(DispatchMsgIdRetrieveHelper<TMessage>::doGetId())
+{
+    return DispatchMsgIdRetrieveHelper<TMessage>::doGetId();
+}
+
+} // namespace details
+
+} // namespace comms