SObjectizer-5 Extra
Public Member Functions | Private Member Functions | Private Attributes | List of all members
so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data > Class Template Reference

An interface for definition of async operation. More...

#include <time_unlimited.hpp>

Public Member Functions

 definition_point_t (::so_5::outliving_reference_t< ::so_5::agent_t > owner)
 Initializing constructor. More...
 
 ~definition_point_t ()
 
 definition_point_t (const definition_point_t &)=delete
 
definition_point_toperator= (const definition_point_t &)=delete
 
 definition_point_t (definition_point_t &&)=default
 
definition_point_toperator= (definition_point_t &&)=default
 
definition_point_treserve_completion_handlers_capacity (std::size_t capacity) &
 Reserve a space for storage of completion handlers. More...
 
template<typename... Args>
auto reserve_completion_handlers_capacity (Args &&...args) &&
 Just a proxy for actual version of reserve_completion_handlers_capacity. More...
 
bool is_activable () const noexcept
 Checks if the async operation can be activated. More...
 
template<typename Msg_Target , typename Event_Handler >
definition_point_tcompleted_on (Msg_Target &&msg_target, const ::so_5::state_t &state, Event_Handler &&evt_handler) &
 Add a completion handler for the async operation. More...
 
template<typename... Args>
definition_point_t && completed_on (Args &&...args) &&
 Just a proxy for the main version of completed_on. More...
 
template<typename Activation_Action >
cancellation_point_t< Operation_Data > activate (Activation_Action &&action) &
 Activate async operation with addition starting action. More...
 
cancellation_point_t< Operation_Data > activate () &
 Activate async operation. More...
 
template<typename... Args>
auto activate (Args &&...args) &&
 Just a proxy for actual activate() methods. More...
 

Private Member Functions

void ensure_not_empty () const
 Checks that the definition_point owns async operation data. More...
 

Private Attributes

details::op_shptr_t< Operation_Data > m_op
 Actual operation data. More...
 

Detailed Description

template<typename Operation_Data = details::op_data_t>
class so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >

An interface for definition of async operation.

Object of this type is usually created by make() function and is used for definition of async operation. Completion and timeout handlers are set for async operation by using definition_point object.

Then an user calls activate() method and the definition_point transfers the async operation data into cancellation_point object. It means that after a call to activate() method the definition_point object should not be used. Because it doesn't hold any async operation anymore.

A simple usage without storing the cancellation_point:

class demo : public so_5::agent_t {
...
void initiate_async_op() {
// Create a definition_point for a new async operation...
// ...then set up completion handler(s)...
.completed_on(
*this,
so_default_state(),
&demo::on_first_completion_msg )
.completed_on(
some_external_mbox_,
some_user_defined_state_,
[this](mhood_t<another_completion_msg> cmd) {...})
// ...and now we can activate the operation.
...
}
};
Note
There is no need to hold definition_point object after activation of the async operation. This object can be safely discarded.

A more complex example using cancellation_point for cancelling the operation.

class demo : public so_5::agent_t {
...
// Cancellation point for the async operation.
asyncop::cancellation_point_t<> cp_;
...
void initiate_async_op() {
// Create a definition_point for a new async operation
// and store the cancellation point after activation.
cp_ = asyncop::make(*this)
// ...then set up completion handler(s)...
.completed_on(
*this,
so_default_state(),
&demo::on_first_completion_msg )
.completed_on(
some_external_mbox_,
some_user_defined_state_,
[this](mhood_t<another_completion_msg> cmd) {...})
// ...and now we can activate the operation.
...
}
...
void on_abortion_signal(mhood_t<abort_signal>) {
// The current async operation should be cancelled.
cp_.cancel();
}
};
Note
There are two forms of activate() method. The first one doesn't receive any arguments. It was shown in the examples above. The second one receives the lambda-function as argument. It can be used when some addtional actions should be performed during the activation of the async operation. For example:
void initiate_async_op() {
.completed_on(...)
.completed_on(...)
.activate([this] {
// Several messages must be sent at the start of async op.
so_5::send<first_initial_msg>(some_target, ...);
so_5::send<second_initial_msg>(some_target, ...);
...
});
}
This class is Moveable, but not DefaultConstructible nor Copyable.
Attention
Objects of this class are not thread safe. It means that a definition point should be used only by agent which created it. And the definition point can't be used inside thread-safe event handlers of that agent.
Since
v.1.0.4

Definition at line 53 of file time_unlimited.hpp.

Constructor & Destructor Documentation

◆ definition_point_t() [1/3]

template<typename Operation_Data = details::op_data_t>
so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::definition_point_t ( ::so_5::outliving_reference_t< ::so_5::agent_t >  owner)
inline

Initializing constructor.

Parameters
ownerThe owner of the async operation.

Definition at line 685 of file time_unlimited.hpp.

◆ ~definition_point_t()

template<typename Operation_Data = details::op_data_t>
so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::~definition_point_t ( )
inline

Definition at line 691 of file time_unlimited.hpp.

◆ definition_point_t() [2/3]

template<typename Operation_Data = details::op_data_t>
so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::definition_point_t ( const definition_point_t< Operation_Data > &  )
delete

◆ definition_point_t() [3/3]

template<typename Operation_Data = details::op_data_t>
so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::definition_point_t ( definition_point_t< Operation_Data > &&  )
default

Member Function Documentation

◆ activate() [1/3]

template<typename Operation_Data = details::op_data_t>
template<typename Activation_Action >
cancellation_point_t< Operation_Data > so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::activate ( Activation_Action &&  action) &
inline

Activate async operation with addition starting action.

This method performs two steps:

  1. Activates the async operation.
  2. Calls action lambda-function (or functional object).

It an exception is thrown from action then the activated async operation will be cancelled automatically.

Usage example:

class demo : public so_5::agent_t {
public:
...
virtual void so_evt_start() override {
// Set up operation completion handlers...
.completed_on(...)
.completed_on(...)
.completed_on(...)
// And now the operation can be activated.
.activate([this] {
... // Some initial actions like sending a message...
});
...
}
};
Attention
It throws if !is_activable().
If an exception is thrown during the activation procedure then the definition_point will become empty. It means that after an exception from activate() the definition_point object should not be used.
Template Parameters
Activation_ActionA type of lambda-function or functional object to be excecuted on activation of operation.
Parameters
actionA lambda-function or functional object which will be called after creation of all necessary subscriptions and switching to activated status.

Definition at line 875 of file time_unlimited.hpp.

◆ activate() [2/3]

template<typename Operation_Data = details::op_data_t>
cancellation_point_t< Operation_Data > so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::activate ( ) &
inline

Activate async operation.

Usage example:

class demo : public so_5::agent_t {
public:
...
virtual void so_evt_start() override {
// Create an async operation...
// Then set up completion handlers...
->completed_on(...)
.completed_on(...)
.completed_on(...)
// And now the operation can be activated.
.activate();
...
}
};
Attention
It throws if !is_activable().
If an exception is thrown during the activation procedure then the definition_point will become empty. It means that after an exception from activate() the definition_point object should not be used.

Definition at line 928 of file time_unlimited.hpp.

◆ activate() [3/3]

template<typename Operation_Data = details::op_data_t>
template<typename... Args>
auto so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::activate ( Args &&...  args) &&
inline

Just a proxy for actual activate() methods.

Definition at line 936 of file time_unlimited.hpp.

◆ completed_on() [1/2]

template<typename Operation_Data = details::op_data_t>
template<typename Msg_Target , typename Event_Handler >
definition_point_t& so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::completed_on ( Msg_Target &&  msg_target,
const ::so_5::state_t &  state,
Event_Handler &&  evt_handler 
) &
inline

Add a completion handler for the async operation.

Usage example:

class demo : public so_5::agent_t {
...
void initiate_async_op() {
asyncop::make<timeout>(*this)
.completed_on(
*this,
so_default_state(),
&demo::some_event )
.completed_on(
some_mbox_,
some_agent_state_,
[this](mhood_t<some_msg> cmd) {...})
...
.activate(...);
}
};
Note
The completion handler will be stored inside async operation data. Actual subscription for it will be made during activation of the async operation.
Template Parameters
Msg_TargetIt can be a mbox, or a reference to an agent. In the case if Msg_Target if a reference to an agent the agent's direct mbox will be used as message source.
Event_HandlerType of actual handler for message/signal. It can be a pointer to agent's method or lambda (or another type of functional object).
Parameters
msg_targetA source from which a completion message is expected. It msg_target is a reference to an agent then the agent's direct mbox will be used.
stateA state for which that completion handler will be subscribed.
evt_handlerThe completion handler itself.

Definition at line 801 of file time_unlimited.hpp.

◆ completed_on() [2/2]

template<typename Operation_Data = details::op_data_t>
template<typename... Args>
definition_point_t&& so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::completed_on ( Args &&...  args) &&
inline

Just a proxy for the main version of completed_on.

Definition at line 825 of file time_unlimited.hpp.

◆ ensure_not_empty()

template<typename Operation_Data = details::op_data_t>
void so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::ensure_not_empty ( ) const
inlineprivate

Checks that the definition_point owns async operation data.

Definition at line 675 of file time_unlimited.hpp.

◆ is_activable()

template<typename Operation_Data = details::op_data_t>
bool so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::is_activable ( ) const
inlinenoexcept

Checks if the async operation can be activated.

The operation can be activated if the definition_point still holds the operation data (e.g. operation is not activated yet) and there is at least one completion handler for the operation.

Definition at line 754 of file time_unlimited.hpp.

◆ operator=() [1/2]

template<typename Operation_Data = details::op_data_t>
definition_point_t& so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::operator= ( const definition_point_t< Operation_Data > &  )
delete

◆ operator=() [2/2]

template<typename Operation_Data = details::op_data_t>
definition_point_t& so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::operator= ( definition_point_t< Operation_Data > &&  )
default

◆ reserve_completion_handlers_capacity() [1/2]

template<typename Operation_Data = details::op_data_t>
definition_point_t& so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::reserve_completion_handlers_capacity ( std::size_t  capacity) &
inline

Reserve a space for storage of completion handlers.

Usage example:

auto op = asyncop::make(some_agent);
// Reserve space for four completion handlers.
op.reserve_completion_handlers_capacity(4);
op.completed_on(...);
op.completed_on(...);
op.completed_on(...);
op.completed_on(...);
op.activate();
Parameters
capacityA required capacity.

Definition at line 726 of file time_unlimited.hpp.

◆ reserve_completion_handlers_capacity() [2/2]

template<typename Operation_Data = details::op_data_t>
template<typename... Args>
auto so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::reserve_completion_handlers_capacity ( Args &&...  args) &&
inline

Just a proxy for actual version of reserve_completion_handlers_capacity.

Definition at line 740 of file time_unlimited.hpp.

Member Data Documentation

◆ m_op

template<typename Operation_Data = details::op_data_t>
details::op_shptr_t< Operation_Data > so_5::extra::async_op::time_unlimited::definition_point_t< Operation_Data >::m_op
private

Actual operation data.

Note
This pointer can be nullptr after activation or after the content of the object is moved away.

Definition at line 671 of file time_unlimited.hpp.


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