Template-based implementation of message chain. More...

#include <mchain_details.hpp>

Inheritance diagram for so_5::mchain_props::mchain_template< Queue, Tracing_Base >:

Public Member Functions
template<typename... Tracing_Args>
	mchain_template (so_5::environment_t &env, mbox_id_t id, const mchain_params_t &params, Tracing_Args &&... tracing_args)
	Initializing constructor.

mbox_id_t	id () const override
	Unique ID of this mbox.

void	subscribe_event_handler (const std::type_index &, abstract_message_sink_t &) override
	Add the message handler.

void	unsubscribe_event_handler (const std::type_index &, abstract_message_sink_t &) noexcept override
	Remove all message handlers.

std::string	query_name () const override
	Get the mbox name.

mbox_type_t	type () const override
	Get the type of message box.

void	do_deliver_message (message_delivery_mode_t delivery_mode, const std::type_index &msg_type, const message_ref_t &message, unsigned int) override
	Deliver message for all subscribers with respect to message limits.

void	set_delivery_filter (const std::type_index &, const delivery_filter_t &, abstract_message_sink_t &) override

void	drop_delivery_filter (const std::type_index &, abstract_message_sink_t &) noexcept override
	Removes delivery filter for message type and subscriber.

extraction_status_t	extract (demand_t &dest, duration_t empty_queue_timeout) override

bool	empty () const override
	Is message chain empty?

std::size_t	size () const override
	Count of messages in the chain.

environment_t &	environment () const noexcept override
	SObjectizer Environment for which the mbox is created.

Public Member Functions inherited from so_5::abstract_message_chain_t
so_5::mbox_t	as_mbox ()
	Cast message chain to message box.

template<typename Exceptions_Control >
void	close (Exceptions_Control, mchain_props::close_mode_t mode) noexcept(noexcept(details::should_terminate_if_throws_t< Exceptions_Control >::value))
	Close the chain.

Protected Member Functions
extraction_status_t	extract (demand_t &dest, select_case_t &select_case) override
	An extraction attempt as a part of multi chain select.

mchain_props::push_status_t	push (const std::type_index &msg_type, const message_ref_t &message, mchain_props::select_case_t &select_case) override
	An attempt to push a new message into the mchain.

void	remove_from_select (select_case_t &select_case) noexcept override
	Removement of mchain from multi chain select.

void	actual_close (close_mode_t mode) override
	Close the chain.

Protected Member Functions inherited from so_5::abstract_message_chain_t
	abstract_message_chain_t ()=default

	~abstract_message_chain_t () noexcept override=default

Protected Member Functions inherited from so_5::abstract_message_box_t
	abstract_message_box_t ()=default

virtual	~abstract_message_box_t () noexcept=default

Protected Member Functions inherited from so_5::atomic_refcounted_t
	atomic_refcounted_t (const atomic_refcounted_t &)=delete

atomic_refcounted_t &	operator= (const atomic_refcounted_t &)=delete

	atomic_refcounted_t () noexcept
	Default constructor.

	~atomic_refcounted_t () noexcept=default
	Destructor.

void	inc_ref_count () noexcept
	Increments reference count.

unsigned long	dec_ref_count () noexcept
	Decrement reference count.

Private Member Functions
void	try_to_store_message_to_queue_ordinary_mode (const std::type_index &msg_type, const message_ref_t &message)
	Actual implementation of pushing message to the queue.

void	try_to_store_message_to_queue_nonblocking_mode (const std::type_index &msg_type, const message_ref_t &message)
	An implementation of storing another message to chain for the case of delated/periodic messages.

extraction_status_t	extract_demand_from_not_empty_queue (demand_t &dest)
	Implementation of extract operation for the case when message queue is not empty.

void	notify_multi_chain_select_ops () noexcept

void	complete_store_message_to_queue (typename Tracing_Base::deliver_op_tracer &tracer, const std::type_index &msg_type, const message_ref_t &message)
	A reusable method with implementation of last part of storing a message into chain.

Private Attributes
environment_t &	m_env
	SObjectizer Environment for which message chain is created.

details::status	m_status = { details::status::open }
	Status of the chain.

const mbox_id_t	m_id
	Mbox ID for chain.

const capacity_t	m_capacity
	Chain capacity.

const not_empty_notification_func_t	m_not_empty_notificator
	Optional notificator for 'not_empty' condition.

Queue	m_queue
	Chain's demands queue.

std::mutex	m_lock
	Chain's lock.

std::condition_variable	m_underflow_cond
	Condition variable for waiting on empty queue.

std::condition_variable	m_overflow_cond
	Condition variable for waiting on full queue.

std::size_t	m_threads_to_wakeup = { 0 }
	Count of threads sleeping on empty mchain.

select_case_t *	m_select_tail = nullptr
	A queue of multi-chain selects in which this chain is used.

Detailed Description

template<typename Queue, typename Tracing_Base>
class so_5::mchain_props::mchain_template< Queue, Tracing_Base >

Template-based implementation of message chain.

Since: v.5.5.13

Template Parameters

Queue	type of demand queue for message chain.
Tracing_Base	type with message tracing implementation details.

Definition at line 317 of file mchain_details.hpp.

Constructor & Destructor Documentation

◆ mchain_template()

template<typename Queue , typename Tracing_Base >

template<typename... Tracing_Args>

so_5::mchain_props::mchain_template< Queue, Tracing_Base >::mchain_template	(	so_5::environment_t &	env,
		mbox_id_t	id,
		const mchain_params_t &	params,
		Tracing_Args &&...	tracing_args )

inline

Initializing constructor.

Parameters

env	SObjectizer Environment for which message chain is created.
id	Mbox ID for this chain.
params	Chain parameters.
tracing_args	Arguments for Tracing_Base's constructor.

Definition at line 324 of file mchain_details.hpp.

Member Function Documentation

◆ actual_close()

template<typename Queue , typename Tracing_Base >

void so_5::mchain_props::mchain_template< Queue, Tracing_Base >::actual_close ( close_mode_t mode )

inlineoverrideprotectedvirtual

Close the chain.

Attention: This method can throw exception.

Since: v.5.7.3

Parameters

mode	What to do with chain's content.

Implements so_5::abstract_message_chain_t.

Definition at line 581 of file mchain_details.hpp.

◆ complete_store_message_to_queue()

template<typename Queue , typename Tracing_Base >

void so_5::mchain_props::mchain_template< Queue, Tracing_Base >::complete_store_message_to_queue	(	typename Tracing_Base::deliver_op_tracer &	tracer,
		const std::type_index &	msg_type,
		const message_ref_t &	message )

inlineprivate

A reusable method with implementation of last part of storing a message into chain.

Note: Intended to be called from try_to_store_message_to_queue_ordinary_mode() and try_to_store_message_to_queue_nonblocking_mode().

Since: v.5.5.18

Definition at line 894 of file mchain_details.hpp.

◆ do_deliver_message()

template<typename Queue , typename Tracing_Base >

void so_5::mchain_props::mchain_template< Queue, Tracing_Base >::do_deliver_message	(	message_delivery_mode_t	delivery_mode,
		const std::type_index &	msg_type,
		const message_ref_t &	message,
		unsigned int	redirection_deep )

inlineoverridevirtual

Deliver message for all subscribers with respect to message limits.

Since: v.5.5.4

A message delivery from timer thread is somewhat different from an ordinary message delivery. Especially in the case when target mbox is a message chain. If that message chain is full and some kind of overflow reaction is specified (like waiting for some time or throwing an exception) then it can lead to undesired behaviour of the whole application. To take care about these cases a new method is introduced.

Note: Since v.5.6.0 this method is used for deliverance of ordinary messages/signals and for deliverance of enveloped messages.

Parameters

delivery_mode	Can the delivery blocks the current thread?
msg_type	Type of the message to deliver.
message	A message instance to be delivered.
redirection_deep	Current deep of overlimit reaction recursion.

Implements so_5::abstract_message_box_t.

Definition at line 379 of file mchain_details.hpp.

◆ drop_delivery_filter()

template<typename Queue , typename Tracing_Base >

void so_5::mchain_props::mchain_template< Queue, Tracing_Base >::drop_delivery_filter	(	const std::type_index &	msg_type,
		abstract_message_sink_t &	subscriber )

inlineoverridevirtualnoexcept

Removes delivery filter for message type and subscriber.

Since: v.5.5.5

Implements so_5::abstract_message_box_t.

Definition at line 417 of file mchain_details.hpp.

◆ empty()

template<typename Queue , typename Tracing_Base >

bool so_5::mchain_props::mchain_template< Queue, Tracing_Base >::empty ( ) const

inlineoverridevirtual

Is message chain empty?

Implements so_5::abstract_message_chain_t.

Definition at line 472 of file mchain_details.hpp.

◆ environment()

template<typename Queue , typename Tracing_Base >

environment_t & so_5::mchain_props::mchain_template< Queue, Tracing_Base >::environment ( ) const

inlineoverridevirtualnoexcept

SObjectizer Environment for which the mbox is created.

Since: v.5.6.0

Reimplemented from so_5::abstract_message_chain_t.

Definition at line 484 of file mchain_details.hpp.

◆ extract() [1/2]

template<typename Queue , typename Tracing_Base >

extraction_status_t so_5::mchain_props::mchain_template< Queue, Tracing_Base >::extract	(	demand_t &	dest,
		duration_t	empty_queue_timeout )

inlinenodiscardoverridevirtual

Implements so_5::abstract_message_chain_t.

Definition at line 424 of file mchain_details.hpp.

◆ extract() [2/2]

template<typename Queue , typename Tracing_Base >

extraction_status_t so_5::mchain_props::mchain_template< Queue, Tracing_Base >::extract	(	demand_t &	dest,
		select_case_t &	select_case )

inlinenodiscardoverrideprotectedvirtual

An extraction attempt as a part of multi chain select.

Attention: This method is a pure virtual since v.5.6.2.

Note: This method is intended to be used by select_case_t.

Since: v.5.5.16

Parameters

dest	Destination for extracted messages.
select_case	Select case to be stored for notification if mchain is empty.

Implements so_5::abstract_message_chain_t.

Definition at line 492 of file mchain_details.hpp.

◆ extract_demand_from_not_empty_queue()

template<typename Queue , typename Tracing_Base >

extraction_status_t so_5::mchain_props::mchain_template< Queue, Tracing_Base >::extract_demand_from_not_empty_queue ( demand_t & dest )

inlineprivate

Implementation of extract operation for the case when message queue is not empty.

Attention: This helper method must be called when chain object is locked in some hi-level method.

Since: v.5.5.16

Definition at line 845 of file mchain_details.hpp.

◆ id()

template<typename Queue , typename Tracing_Base >

mbox_id_t so_5::mchain_props::mchain_template< Queue, Tracing_Base >::id ( ) const

inlineoverridevirtual

Unique ID of this mbox.

Since: v.5.4.0

Reimplemented from so_5::abstract_message_chain_t.

Definition at line 342 of file mchain_details.hpp.

◆ notify_multi_chain_select_ops()

template<typename Queue , typename Tracing_Base >

void so_5::mchain_props::mchain_template< Queue, Tracing_Base >::notify_multi_chain_select_ops ( )

inlineprivatenoexcept

Since: v.5.5.16

Definition at line 872 of file mchain_details.hpp.

◆ push()

template<typename Queue , typename Tracing_Base >

mchain_props::push_status_t so_5::mchain_props::mchain_template< Queue, Tracing_Base >::push	(	const std::type_index &	msg_type,
		const message_ref_t &	message,
		mchain_props::select_case_t &	select_case )

inlinenodiscardoverrideprotectedvirtual

An attempt to push a new message into the mchain.

Unlike do_deliver_message() method the push() doesn't apply the overload reaction if the mchain if full. The select_case is stored to select_cases list instead.

Note: This method is intended to be used by select_case_t.

Since: v.5.7.0

Parameters

msg_type	Type of message/signal to be pushed.
message	Message/signal to be pushed.
select_case	Select case to be stored for notification if mchain is full.

Implements so_5::abstract_message_chain_t.

Definition at line 517 of file mchain_details.hpp.

◆ query_name()

template<typename Queue , typename Tracing_Base >

std::string so_5::mchain_props::mchain_template< Queue, Tracing_Base >::query_name ( ) const

inlineoverridevirtual

Get the mbox name.

Implements so_5::abstract_message_box_t.

Definition at line 364 of file mchain_details.hpp.

◆ remove_from_select()

template<typename Queue , typename Tracing_Base >

void so_5::mchain_props::mchain_template< Queue, Tracing_Base >::remove_from_select ( select_case_t & select_case )

inlineoverrideprotectedvirtualnoexcept

Removement of mchain from multi chain select.

Attention: This method is a pure virtual and noexcept since v.5.6.2.

Note: This method is intended to be used by select_case_t.

Since: v.5.5.16

Parameters

select_case Select case to be removed from notification queue.

Implements so_5::abstract_message_chain_t.

Definition at line 555 of file mchain_details.hpp.

◆ set_delivery_filter()

template<typename Queue , typename Tracing_Base >

void so_5::mchain_props::mchain_template< Queue, Tracing_Base >::set_delivery_filter	(	const std::type_index &	,
		const delivery_filter_t &	,
		abstract_message_sink_t &	)

inlineoverridevirtual

Attention: Will throw an exception because delivery filter is not applicable to MPSC-mboxes.

Implements so_5::abstract_message_box_t.

Definition at line 406 of file mchain_details.hpp.

◆ size()

template<typename Queue , typename Tracing_Base >

std::size_t so_5::mchain_props::mchain_template< Queue, Tracing_Base >::size ( ) const

inlineoverridevirtual

Count of messages in the chain.

Implements so_5::abstract_message_chain_t.

Definition at line 478 of file mchain_details.hpp.

◆ subscribe_event_handler()

template<typename Queue , typename Tracing_Base >

void so_5::mchain_props::mchain_template< Queue, Tracing_Base >::subscribe_event_handler	(	const std::type_index &	type_index,
		abstract_message_sink_t &	subscriber )

inlineoverridevirtual

Add the message handler.

Parameters

type_index	Message type.
subscriber	Subscriber.

Implements so_5::abstract_message_box_t.

Definition at line 348 of file mchain_details.hpp.

◆ try_to_store_message_to_queue_nonblocking_mode()

template<typename Queue , typename Tracing_Base >

void so_5::mchain_props::mchain_template< Queue, Tracing_Base >::try_to_store_message_to_queue_nonblocking_mode	(	const std::type_index &	msg_type,
		const message_ref_t &	message )

inlineprivate

An implementation of storing another message to chain for the case of delated/periodic messages.

This implementation handles overloaded chains differently:

there is no waiting on overloaded chain (even if such waiting is specified in mchain params);
overflow_reaction_t::throw_exception is replaced by overflow_reaction_t::drop_newest.

These defferences are necessary because the context of timer thread is very special: there can't be any long-time operation (like waiting for free space on overloaded chain) and there can't be an exception about mchain's overflow.

Since: v.5.5.18

Definition at line 777 of file mchain_details.hpp.

◆ try_to_store_message_to_queue_ordinary_mode()

template<typename Queue , typename Tracing_Base >

void so_5::mchain_props::mchain_template< Queue, Tracing_Base >::try_to_store_message_to_queue_ordinary_mode	(	const std::type_index &	msg_type,
		const message_ref_t &	message )

inlineprivate

Actual implementation of pushing message to the queue.

Note: This implementation must be used for ordinary delivery operations. For delivery operations from timer thread another method must be called (see try_to_store_message_to_queue_nonblocking_mode()).

Definition at line 671 of file mchain_details.hpp.

◆ type()

template<typename Queue , typename Tracing_Base >

mbox_type_t so_5::mchain_props::mchain_template< Queue, Tracing_Base >::type ( ) const

inlineoverridevirtual

Get the type of message box.

Since: v.5.5.3

Note: This method is primarily intended for internal usage. It is useful sometimes in subscription-related operations because there is no need to do some actions for MPSC mboxes.

Implements so_5::abstract_message_box_t.

Definition at line 373 of file mchain_details.hpp.

◆ unsubscribe_event_handler()

template<typename Queue , typename Tracing_Base >

void so_5::mchain_props::mchain_template< Queue, Tracing_Base >::unsubscribe_event_handler	(	const std::type_index &	type_index,
		abstract_message_sink_t &	subscriber )

inlineoverridevirtualnoexcept

Remove all message handlers.

Parameters

type_index	Message type.
subscriber	Subscriber.

Implements so_5::abstract_message_box_t.

Definition at line 358 of file mchain_details.hpp.

Member Data Documentation

◆ m_capacity

template<typename Queue , typename Tracing_Base >

const capacity_t so_5::mchain_props::mchain_template< Queue, Tracing_Base >::m_capacity

private

Chain capacity.

Definition at line 628 of file mchain_details.hpp.

◆ m_env

template<typename Queue , typename Tracing_Base >

environment_t& so_5::mchain_props::mchain_template< Queue, Tracing_Base >::m_env

private

SObjectizer Environment for which message chain is created.

Definition at line 619 of file mchain_details.hpp.

◆ m_id

template<typename Queue , typename Tracing_Base >

const mbox_id_t so_5::mchain_props::mchain_template< Queue, Tracing_Base >::m_id

private

Mbox ID for chain.

Definition at line 625 of file mchain_details.hpp.

◆ m_lock

template<typename Queue , typename Tracing_Base >

std::mutex so_5::mchain_props::mchain_template< Queue, Tracing_Base >::m_lock

private

Chain's lock.

Definition at line 637 of file mchain_details.hpp.

◆ m_not_empty_notificator

template<typename Queue , typename Tracing_Base >

const not_empty_notification_func_t so_5::mchain_props::mchain_template< Queue, Tracing_Base >::m_not_empty_notificator

private

Optional notificator for 'not_empty' condition.

Definition at line 631 of file mchain_details.hpp.

◆ m_overflow_cond

template<typename Queue , typename Tracing_Base >

std::condition_variable so_5::mchain_props::mchain_template< Queue, Tracing_Base >::m_overflow_cond

private

Condition variable for waiting on full queue.

Definition at line 642 of file mchain_details.hpp.

◆ m_queue

template<typename Queue , typename Tracing_Base >

Queue so_5::mchain_props::mchain_template< Queue, Tracing_Base >::m_queue

private

Chain's demands queue.

Definition at line 634 of file mchain_details.hpp.

◆ m_select_tail

template<typename Queue , typename Tracing_Base >

select_case_t* so_5::mchain_props::mchain_template< Queue, Tracing_Base >::m_select_tail = nullptr

private

A queue of multi-chain selects in which this chain is used.

Since: v.5.5.16

Definition at line 661 of file mchain_details.hpp.

◆ m_status

template<typename Queue , typename Tracing_Base >

details::status so_5::mchain_props::mchain_template< Queue, Tracing_Base >::m_status = { details::status::open }

private

Status of the chain.

Definition at line 622 of file mchain_details.hpp.

◆ m_threads_to_wakeup

template<typename Queue , typename Tracing_Base >

std::size_t so_5::mchain_props::mchain_template< Queue, Tracing_Base >::m_threads_to_wakeup = { 0 }

private

Count of threads sleeping on empty mchain.

This value is incremented before sleeping on m_underflow_cond and decremented just after a return from this sleep.

Since: v.5.5.16

Definition at line 653 of file mchain_details.hpp.

◆ m_underflow_cond

template<typename Queue , typename Tracing_Base >

std::condition_variable so_5::mchain_props::mchain_template< Queue, Tracing_Base >::m_underflow_cond

private

Condition variable for waiting on empty queue.

Definition at line 640 of file mchain_details.hpp.

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

mchain_details.hpp

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ mchain_template()

Member Function Documentation

◆ actual_close()

◆ complete_store_message_to_queue()

◆ do_deliver_message()

◆ drop_delivery_filter()

◆ empty()

◆ environment()

◆ extract() [1/2]

◆ extract() [2/2]

◆ extract_demand_from_not_empty_queue()

◆ id()

◆ notify_multi_chain_select_ops()

◆ push()

◆ query_name()

◆ remove_from_select()

◆ set_delivery_filter()

◆ size()

◆ subscribe_event_handler()

◆ try_to_store_message_to_queue_nonblocking_mode()

◆ try_to_store_message_to_queue_ordinary_mode()

◆ type()

◆ unsubscribe_event_handler()

Member Data Documentation

◆ m_capacity

◆ m_env

◆ m_id

◆ m_lock

◆ m_not_empty_notificator

◆ m_overflow_cond

◆ m_queue

◆ m_select_tail

◆ m_status

◆ m_threads_to_wakeup

◆ m_underflow_cond