comms::MsgFactory< TMsgBase, TAllMessages, TOptions > Class Template Reference

#include "comms/MsgFactory.h"

Detailed Description

template<typename TMsgBase, typename TAllMessages, typename... TOptions>
class comms::MsgFactory< TMsgBase, TAllMessages, TOptions >

Message factory class.

It is responsible to create message objects given the ID of the message. This class DOESN'T use dynamic memory allocation to store its internal data structures, hence can be used in any bare-metal and other embedded environment.
The types of all messages provided in TAllMessages are analysed at compile time and best "id to message object" mapping strategy is chosen, unless the "dispatch" type forcing options are used (see description below).

Template Parameters

TMsgBase	Common base class for all the messages, smart pointer to this type is returned when allocation of specify message is requested.
TAllMessages	All custom message types, that this factory is capable of creating, bundled in std::tuple<>. The message types must be sorted based on their IDs. Different variants of the same message (reporting same ID, but implemented as different classes) are also supported. However they must follow one another in this std::tuple, i.e. be sorted.
TOptions	Zero or more options. The supported options are: comms::option::app::InPlaceAllocation - Option to specify that custom message objects are NOT allocated using dynamic memory, instead an uninitialised area of memory in private members is used to contain any type of custom message (provided with TAllMessages template parameter) and placement "new" operator is used to initialise requested message in this area. The allocated message objects are returned from createMsg() function wrapped in the smart pointer (variant of std::unique_ptr). If comms::option::app::InPlaceAllocation option is used, then the smart pointer definition contains custom deleter, which will explicitly invoke destructor of the message when the smart pointer is out of scope. It means that it is NOT possible to create new message with this factory if previously allocated one wasn't destructed yet. If comms::option::app::InPlaceAllocation option is NOT used, than the requested message objects are allocated using dynamic memory and returned wrapped in std::unique_ptr without custom deleter. comms::option::app::SupportGenericMessage - Option used to allow allocation of comms::GenericMessage. If such option is provided, the createGenericMsg() member function will be able to allocate comms::GenericMessage object. NOTE, that the base class of comms::GenericMessage type (first template parameter) must be equal to TMsgBase (first template parameter) of this class. comms::option::app::ForceDispatchPolymorphic, comms::option::app::ForceDispatchStaticBinSearch, or comms::option::app::ForceDispatchLinearSwitch - Force a particular dispatch way when creating message object given the numeric ID (see comms::MsgFactory::createMsg()). The dispatch methods are properly described in Advanced Guide to Message Dispatching tutorial page. If none of these options are provided, then the MsgFactory used a default way, which is equivalent to calling comms::dispatchMsgType() (see also Default Way to Dispatch). To inquire what actual dispatch type is used, please use one of the following constexpr member functions: comms::MsgFactory::isDispatchPolymorphic(), comms::MsgFactory::isDispatchStaticBinSearch(), and comms::MsgFactory::isDispatchLinearSwitch()

Precondition

TMsgBase is a base class for all the messages in TAllMessages.

Message type is TAllMessages must be sorted based on their IDs.

If comms::option::app::InPlaceAllocation option is provided, only one custom message can be allocated. The next one can be allocated only after previous message has been destructed.

Inherits comms::details::MsgFactoryBase< TMsgBase, TAllMessages, TOptions... >.

Public Types
using	AllMessages = typename Base::AllMessages
	All messages provided as template parameter to this class.
using	CreateFailureReason = MsgFactoryCreateFailureReason
	Reason for message creation failure.
using	GenericMessage = typename ParsedOptions::GenericMessage
	type of generic message. More...
using	Message = typename Base::Message
	Type of the common base class of all the messages.
using	MsgIdParamType = typename Base::MsgIdParamType
	Type of the message ID when passed as a parameter.
using	MsgIdType = typename Base::MsgIdType
	Type of the message ID.
using	MsgPtr = typename Base::MsgPtr
	Smart pointer to Message which holds allocated message object. More...
using	ParsedOptions = typename Base::ParsedOptions
	Parsed options.

Public Member Functions
bool	canAllocate () const
	Inquiry whether allocation is possible.
MsgPtr	createGenericMsg (MsgIdParamType id, unsigned idx=0U) const
	Allocate and initialise comms::GenericMessage object. More...
MsgPtr	createMsg (MsgIdParamType id, unsigned idx=0U, CreateFailureReason *reason=nullptr) const
	Create message object given the ID of the message. More...
std::size_t	msgCount (MsgIdParamType id) const
	Get number of message types from AllMessages, that have the specified ID. More...

Static Public Member Functions
static constexpr bool	hasForcedDispatch ()
	Compile time inquiry whether factory has forced dispatch method.
static constexpr bool	hasGenericMessageSupport ()
	Compile time inquiry whether factory supports comms::GenericMessage allocation.
static constexpr bool	hasInPlaceAllocation ()
	Compile time inquiry whether factory supports in-place allocation. More...
static constexpr bool	hasUniqueIds ()
	Compile time inquiry whether all the message classes in the TAllMessages bundle have unique IDs.
static constexpr bool	isDispatchLinearSwitch ()
	Compile time inquiry whether linear switch dispatch is generated internally to map message ID to actual type. More...
static constexpr bool	isDispatchPolymorphic ()
	Compile time inquiry whether polymorphic dispatch tables are generated internally to map message ID to actual type. More...
static constexpr bool	isDispatchStaticBinSearch ()
	Compile time inquiry whether static binary search dispatch is generated internally to map message ID to actual type. More...

Member Typedef Documentation

GenericMessage

template<typename TMsgBase , typename TAllMessages , typename... TOptions>

using comms::MsgFactory< TMsgBase, TAllMessages, TOptions >::GenericMessage = typename ParsedOptions::GenericMessage

type of generic message.

If supported a variant of comms::GenericMessage, void otherwise

MsgPtr

template<typename TMsgBase , typename TAllMessages , typename... TOptions>

using comms::MsgFactory< TMsgBase, TAllMessages, TOptions >::MsgPtr = typename Base::MsgPtr

Smart pointer to Message which holds allocated message object.

It is a variant of std::unique_ptr, based on whether comms::option::app::InPlaceAllocation option was used.

Member Function Documentation

createGenericMsg()

template<typename TMsgBase , typename TAllMessages , typename... TOptions>

MsgPtr comms::MsgFactory< TMsgBase, TAllMessages, TOptions >::createGenericMsg	(	MsgIdParamType	id,
		unsigned	idx = 0U
	)		const

Allocate and initialise comms::GenericMessage object.

If comms::option::app::SupportGenericMessage option hasn't been provided, this function will return empty MsgPtr pointer. Otherwise the relevant allocator will be used to allocate comms::GenericMessage.

Parameters

[in]	id	ID of the message, will be passed as a parameter to the constructor of the comms::GenericMessage class
	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.

createMsg()

template<typename TMsgBase , typename TAllMessages , typename... TOptions>

MsgPtr comms::MsgFactory< TMsgBase, TAllMessages, TOptions >::createMsg	(	MsgIdParamType	id,
		unsigned	idx = 0U,
		CreateFailureReason *	reason = nullptr
	)		const

Create message object given the ID of the message.

The id to mapping is performed using the chosen (or default) dispatch policy described in the class options.

Parameters

	id	ID of the message.
	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.
[out]	reason	Failure reason in case creation has failed. May be nullptr.

Returns

Smart pointer (variant of std::unique_ptr) to Message type, which is a common base class of all the messages (provided as first template parameter to this class). If comms::option::app::InPlaceAllocation option was used and previously allocated message wasn't de-allocated yet, the empty (null) pointer will be returned.

hasInPlaceAllocation()

template<typename TMsgBase , typename TAllMessages , typename... TOptions>

static constexpr bool comms::MsgFactory< TMsgBase, TAllMessages, TOptions >::hasInPlaceAllocation ( )

staticconstexpr

Compile time inquiry whether factory supports in-place allocation.

Returns

true in case of in-place allocation, false in case of dynamic memory use.

isDispatchLinearSwitch()

template<typename TMsgBase , typename TAllMessages , typename... TOptions>

static constexpr bool comms::MsgFactory< TMsgBase, TAllMessages, TOptions >::isDispatchLinearSwitch ( )

staticconstexpr

Compile time inquiry whether linear switch dispatch is generated internally to map message ID to actual type.

See also

Advanced Guide to Message Dispatching

comms::MsgFactory::isDispatchStaticBinSearch()

comms::MsgFactory::isDispatchLinearSwitch()

isDispatchPolymorphic()

template<typename TMsgBase , typename TAllMessages , typename... TOptions>

static constexpr bool comms::MsgFactory< TMsgBase, TAllMessages, TOptions >::isDispatchPolymorphic ( )

staticconstexpr

Compile time inquiry whether polymorphic dispatch tables are generated internally to map message ID to actual type.

See also

Advanced Guide to Message Dispatching

comms::MsgFactory::isDispatchStaticBinSearch()

comms::MsgFactory::isDispatchLinearSwitch()

isDispatchStaticBinSearch()

template<typename TMsgBase , typename TAllMessages , typename... TOptions>

static constexpr bool comms::MsgFactory< TMsgBase, TAllMessages, TOptions >::isDispatchStaticBinSearch ( )

staticconstexpr

Compile time inquiry whether static binary search dispatch is generated internally to map message ID to actual type.

See also

Advanced Guide to Message Dispatching

comms::MsgFactory::isDispatchPolymorphic()

comms::MsgFactory::isDispatchLinearSwitch()

msgCount()

template<typename TMsgBase , typename TAllMessages , typename... TOptions>

std::size_t comms::MsgFactory< TMsgBase, TAllMessages, TOptions >::msgCount

(

MsgIdParamType

id

)

const

Get number of message types from AllMessages, that have the specified ID.

Parameters

id	ID of the message.

Returns

Number of message classes that report same ID.

---

The documentation for this class was generated from the following file:

• include/comms/MsgFactory.h