# FairMQ: fair::mq::sdk::BasicTopology< Executor, Allocator > Class Template Reference

fair::mq::sdk::BasicTopology< Executor, Allocator > Class Template Reference

Represents a FairMQ topology. More...

`#include <fairmq/sdk/Topology.h>`

Inheritance diagram for fair::mq::sdk::BasicTopology< Executor, Allocator >:
[legend]
Collaboration diagram for fair::mq::sdk::BasicTopology< Executor, Allocator >:
[legend]

## Public Types

using | Duration = std::chrono::milliseconds
using | ChangeStateCompletionSignature = void(std::error_code, TopologyState)
using | WaitForStateCompletionSignature = void(std::error_code)
using | GetPropertiesCompletionSignature = void(std::error_code, GetPropertiesResult)
using | SetPropertiesCompletionSignature = void(std::error_code, FailedDevices)
Public Types inherited from fair::mq::sdk::AsioBase< Executor, Allocator >
using | ExecutorType = Executor
| Member type of associated I/O executor.
using | AllocatorType = Allocator
| Member type of associated default allocator.

## Public Member Functions

| BasicTopology (DDSTopology topo, DDSSession session)
| (Re)Construct a FairMQ topology from an existing DDS topology More...
| BasicTopology (const Executor &ex, DDSTopology topo, DDSSession session, Allocator alloc=DefaultAllocator())
| (Re)Construct a FairMQ topology from an existing DDS topology More...
| BasicTopology (const BasicTopology &)=delete
| not copyable
BasicTopology & | operator= (const BasicTopology &)=delete
| BasicTopology (BasicTopology &&)=default
| movable
BasicTopology & | operator= (BasicTopology &&)=default
void | SubscribeToStateChanges ()
void | SendSubscriptionHeartbeats (const std::error_code &ec)
void | UnsubscribeFromStateChanges ()
void | SubscribeToCommands ()
auto | HandleCmd (cmd::StateChangeSubscription const &cmd) -> void
auto | HandleCmd (cmd::StateChangeUnsubscription const &cmd) -> void
auto | HandleCmd (cmd::StateChange const &cmd, DDSChannel::Id const &senderId) -> void
auto | HandleCmd (cmd::TransitionStatus const &cmd) -> void
auto | HandleCmd (cmd::Properties const &cmd) -> void
auto | HandleCmd (cmd::PropertiesSet const &cmd) -> void
template<typename CompletionToken >
auto | AsyncChangeState (const TopologyTransition transition, const std::string &path, Duration timeout, CompletionToken &&token)
| Initiate state transition on all FairMQ devices in this topology. More...
template<typename CompletionToken >
auto | AsyncChangeState (const TopologyTransition transition, CompletionToken &&token)
| Initiate state transition on all FairMQ devices in this topology. More...
template<typename CompletionToken >
auto | AsyncChangeState (const TopologyTransition transition, Duration timeout, CompletionToken &&token)
| Initiate state transition on all FairMQ devices in this topology with a timeout. More...
template<typename CompletionToken >
auto | AsyncChangeState (const TopologyTransition transition, const std::string &path, CompletionToken &&token)
| Initiate state transition on all FairMQ devices in this topology with a timeout. More...
auto | ChangeState (const TopologyTransition transition, const std::string &path="", Duration timeout=Duration(0)) -> std::pair< std::error_code, TopologyState >
| Perform state transition on FairMQ devices in this topology for a specified topology path. More...
auto | ChangeState (const TopologyTransition transition, Duration timeout) -> std::pair< std::error_code, TopologyState >
| Perform state transition on all FairMQ devices in this topology with a timeout. More...
auto | GetCurrentState () const -> TopologyState
| Returns the current state of the topology. More...
auto | AggregateState () const -> DeviceState
auto | StateEqualsTo (DeviceState state) const -> bool
template<typename CompletionToken >
auto | AsyncWaitForState (const DeviceState targetLastState, const DeviceState targetCurrentState, const std::string &path, Duration timeout, CompletionToken &&token)
| Initiate waiting for selected FairMQ devices to reach given last & current state in this topology. More...
template<typename CompletionToken >
auto | AsyncWaitForState (const DeviceState targetLastState, const DeviceState targetCurrentState, CompletionToken &&token)
| Initiate waiting for selected FairMQ devices to reach given last & current state in this topology. More...
template<typename CompletionToken >
auto | AsyncWaitForState (const DeviceState targetCurrentState, CompletionToken &&token)
| Initiate waiting for selected FairMQ devices to reach given current state in this topology. More...
auto | WaitForState (const DeviceState targetLastState, const DeviceState targetCurrentState, const std::string &path="", Duration timeout=Duration(0)) -> std::error_code
| Wait for selected FairMQ devices to reach given last & current state in this topology. More...
auto | WaitForState (const DeviceState targetCurrentState, const std::string &path="", Duration timeout=Duration(0)) -> std::error_code
| Wait for selected FairMQ devices to reach given current state in this topology. More...
template<typename CompletionToken >
auto | AsyncGetProperties (DevicePropertyQuery const &query, const std::string &path, Duration timeout, CompletionToken &&token)
| Initiate property query on selected FairMQ devices in this topology. More...
template<typename CompletionToken >
auto | AsyncGetProperties (DevicePropertyQuery const &query, CompletionToken &&token)
| Initiate property query on selected FairMQ devices in this topology. More...
auto | GetProperties (DevicePropertyQuery const &query, const std::string &path="", Duration timeout=Duration(0)) -> std::pair< std::error_code, GetPropertiesResult >
| Query properties on selected FairMQ devices in this topology. More...
template<typename CompletionToken >
auto | AsyncSetProperties (const DeviceProperties &props, const std::string &path, Duration timeout, CompletionToken &&token)
| Initiate property update on selected FairMQ devices in this topology. More...
template<typename CompletionToken >
auto | AsyncSetProperties (DeviceProperties const &props, CompletionToken &&token)
| Initiate property update on selected FairMQ devices in this topology. More...
auto | SetProperties (DeviceProperties const &properties, const std::string &path="", Duration timeout=Duration(0)) -> std::pair< std::error_code, FailedDevices >
| Set properties on selected FairMQ devices in this topology. More...
Duration | GetHeartbeatInterval () const
void | SetHeartbeatInterval (Duration duration)
Public Member Functions inherited from fair::mq::sdk::AsioBase< Executor, Allocator >
auto | GetExecutor () const noexcept -> ExecutorType
| Get associated I/O executor.
auto | GetAllocator () const noexcept -> AllocatorType
| Get associated default allocator.
| AsioBase ()=delete
| NO default ctor.
| AsioBase (Executor ex, Allocator alloc)
| Construct with associated I/O executor.
| AsioBase (const AsioBase &)=delete
| NOT copyable.
AsioBase & | operator= (const AsioBase &)=delete
| AsioBase (AsioBase &&) noexcept=default
| movable
AsioBase & | operator= (AsioBase &&) noexcept=default

## Detailed Description

### template<typename Executor, typename Allocator>
class fair::mq::sdk::BasicTopology< Executor, Allocator >

Represents a FairMQ topology.

Template Parameters

  Executor | Associated I/O executor
  Allocator | Associated default allocator

Thread Safety
  Distinct objects: Safe.
  Shared objects: Safe.

## Constructor & Destructor Documentation

## BasicTopology() [1/2]

template<typename Executor , typename Allocator >

fair::mq::sdk::BasicTopology< Executor, Allocator >::BasicTopology | ( | DDSTopology | topo,
|  | DDSSession | session
| ) |  |

inline

(Re)Construct a FairMQ topology from an existing DDS topology

Parameters

  topo | DDSTopology
  session | DDSSession

## BasicTopology() [2/2]

template<typename Executor , typename Allocator >

fair::mq::sdk::BasicTopology< Executor, Allocator >::BasicTopology | ( | const Executor & | ex,
|  | DDSTopology | topo,
|  | DDSSession | session,
|  | Allocator | alloc = `DefaultAllocator()`
| ) |  |

inline

(Re)Construct a FairMQ topology from an existing DDS topology

Parameters

  ex | I/O executor to be associated
  topo | DDSTopology
  session | DDSSession

Exceptions

  RuntimeError |

## Member Function Documentation

## AsyncChangeState() [1/4]

template<typename Executor , typename Allocator >
template<typename CompletionToken >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::AsyncChangeState | ( | const TopologyTransition | transition,
|  | const std::string & | path,
|  | Duration | timeout,
|  | CompletionToken && | token
| ) |  |

inline

Initiate state transition on all FairMQ devices in this topology.

Parameters

  transition | FairMQ device state machine transition
  path | Select a subset of FairMQ devices in this topology, empty selects all
  timeout | Timeout in milliseconds, 0 means no timeout
  token | Asio completion token

Template Parameters

  CompletionToken | Asio completion token type

Exceptions

  std::system_error |

Usage examples
  With lambda:
  topo.AsyncChangeState(
  fair::mq::sdk::TopologyTransition::InitDevice,
  std::chrono::milliseconds(500),
  [](std::error_code ec, TopologyState state) {
  if (!ec) {
  // success
  } else if (ec.category().name() == "fairmq") {
  switch (static_cast<fair::mq::ErrorCode>(ec.value())) {
  case fair::mq::ErrorCode::OperationTimeout:
  // async operation timed out
  case fair::mq::ErrorCode::OperationCanceled:
  // async operation canceled
  case fair::mq::ErrorCode::DeviceChangeStateFailed:
  // failed to change state of a fairmq device
  default:
  }
  }
  }
  );
  With future:
  auto fut = topo.AsyncChangeState(fair::mq::sdk::TopologyTransition::InitDevice,
  std::chrono::milliseconds(500),
  asio::use_future);
  try {
  fair::mq::sdk::TopologyState state = fut.get();
  // success
  } catch (const std::system_error& ex) {
  auto ec(ex.code());
  if (ec.category().name() == "fairmq") {
  switch (static_cast<fair::mq::ErrorCode>(ec.value())) {
  case fair::mq::ErrorCode::OperationTimeout:
  // async operation timed out
  case fair::mq::ErrorCode::OperationCanceled:
  // async operation canceled
  case fair::mq::ErrorCode::DeviceChangeStateFailed:
  // failed to change state of a fairmq device
  default:
  }
  }
  }
  With coroutine (C++20, see https://en.cppreference.com/w/cpp/language/coroutines):
  try {
  fair::mq::sdk::TopologyState state = co_await
  topo.AsyncChangeState(fair::mq::sdk::TopologyTransition::InitDevice,
  std::chrono::milliseconds(500),
  asio::use_awaitable);
  // success
  } catch (const std::system_error& ex) {
  auto ec(ex.code());
  if (ec.category().name() == "fairmq") {
  switch (static_cast<fair::mq::ErrorCode>(ec.value())) {
  case fair::mq::ErrorCode::OperationTimeout:
  // async operation timed out
  case fair::mq::ErrorCode::OperationCanceled:
  // async operation canceled
  case fair::mq::ErrorCode::DeviceChangeStateFailed:
  // failed to change state of a fairmq device
  default:
  }
  }
  }

## AsyncChangeState() [2/4]

template<typename Executor , typename Allocator >
template<typename CompletionToken >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::AsyncChangeState | ( | const TopologyTransition | transition,
|  | CompletionToken && | token
| ) |  |

inline

Initiate state transition on all FairMQ devices in this topology.

Parameters

  transition | FairMQ device state machine transition
  token | Asio completion token

Template Parameters

  CompletionToken | Asio completion token type

Exceptions

  std::system_error |

## AsyncChangeState() [3/4]

template<typename Executor , typename Allocator >
template<typename CompletionToken >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::AsyncChangeState | ( | const TopologyTransition | transition,
|  | Duration | timeout,
|  | CompletionToken && | token
| ) |  |

inline

Initiate state transition on all FairMQ devices in this topology with a timeout.

Parameters

  transition | FairMQ device state machine transition
  timeout | Timeout in milliseconds, 0 means no timeout
  token | Asio completion token

Template Parameters

  CompletionToken | Asio completion token type

Exceptions

  std::system_error |

## AsyncChangeState() [4/4]

template<typename Executor , typename Allocator >
template<typename CompletionToken >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::AsyncChangeState | ( | const TopologyTransition | transition,
|  | const std::string & | path,
|  | CompletionToken && | token
| ) |  |

inline

Initiate state transition on all FairMQ devices in this topology with a timeout.

Parameters

  transition | FairMQ device state machine transition
  path | Select a subset of FairMQ devices in this topology, empty selects all
  token | Asio completion token

Template Parameters

  CompletionToken | Asio completion token type

Exceptions

  std::system_error |

## AsyncGetProperties() [1/2]

template<typename Executor , typename Allocator >
template<typename CompletionToken >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::AsyncGetProperties | ( | DevicePropertyQuery const & | query,
|  | const std::string & | path,
|  | Duration | timeout,
|  | CompletionToken && | token
| ) |  |

inline

Initiate property query on selected FairMQ devices in this topology.

Parameters

  query | Key(s) to be queried (regex)
  path | Select a subset of FairMQ devices in this topology, empty selects all
  timeout | Timeout in milliseconds, 0 means no timeout
  token | Asio completion token

Template Parameters

  CompletionToken | Asio completion token type

Exceptions

  std::system_error |

## AsyncGetProperties() [2/2]

template<typename Executor , typename Allocator >
template<typename CompletionToken >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::AsyncGetProperties | ( | DevicePropertyQuery const & | query,
|  | CompletionToken && | token
| ) |  |

inline

Initiate property query on selected FairMQ devices in this topology.

Parameters

  query | Key(s) to be queried (regex)
  token | Asio completion token

Template Parameters

  CompletionToken | Asio completion token type

Exceptions

  std::system_error |

## AsyncSetProperties() [1/2]

template<typename Executor , typename Allocator >
template<typename CompletionToken >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::AsyncSetProperties | ( | const DeviceProperties & | props,
|  | const std::string & | path,
|  | Duration | timeout,
|  | CompletionToken && | token
| ) |  |

inline

Initiate property update on selected FairMQ devices in this topology.

Parameters

  props | Properties to set
  path | Select a subset of FairMQ devices in this topology, empty selects all
  timeout | Timeout in milliseconds, 0 means no timeout
  token | Asio completion token

Template Parameters

  CompletionToken | Asio completion token type

Exceptions

  std::system_error |

## AsyncSetProperties() [2/2]

template<typename Executor , typename Allocator >
template<typename CompletionToken >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::AsyncSetProperties | ( | DeviceProperties const & | props,
|  | CompletionToken && | token
| ) |  |

inline

Initiate property update on selected FairMQ devices in this topology.

Parameters

  props | Properties to set
  token | Asio completion token

Template Parameters

  CompletionToken | Asio completion token type

Exceptions

  std::system_error |

## AsyncWaitForState() [1/3]

template<typename Executor , typename Allocator >
template<typename CompletionToken >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::AsyncWaitForState | ( | const DeviceState | targetLastState,
|  | const DeviceState | targetCurrentState,
|  | const std::string & | path,
|  | Duration | timeout,
|  | CompletionToken && | token
| ) |  |

inline

Initiate waiting for selected FairMQ devices to reach given last & current state in this topology.

Parameters

  targetLastState | the target last device state to wait for
  targetCurrentState | the target device state to wait for
  path | Select a subset of FairMQ devices in this topology, empty selects all
  timeout | Timeout in milliseconds, 0 means no timeout
  token | Asio completion token

Template Parameters

  CompletionToken | Asio completion token type

Exceptions

  std::system_error |

## AsyncWaitForState() [2/3]

template<typename Executor , typename Allocator >
template<typename CompletionToken >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::AsyncWaitForState | ( | const DeviceState | targetLastState,
|  | const DeviceState | targetCurrentState,
|  | CompletionToken && | token
| ) |  |

inline

Initiate waiting for selected FairMQ devices to reach given last & current state in this topology.

Parameters

  targetLastState | the target last device state to wait for
  targetCurrentState | the target device state to wait for
  token | Asio completion token

Template Parameters

  CompletionToken | Asio completion token type

Exceptions

  std::system_error |

## AsyncWaitForState() [3/3]

template<typename Executor , typename Allocator >
template<typename CompletionToken >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::AsyncWaitForState | ( | const DeviceState | targetCurrentState,
|  | CompletionToken && | token
| ) |  |

inline

Initiate waiting for selected FairMQ devices to reach given current state in this topology.

Parameters

  targetCurrentState | the target device state to wait for
  token | Asio completion token

Template Parameters

  CompletionToken | Asio completion token type

Exceptions

  std::system_error |

## ChangeState() [1/2]

template<typename Executor , typename Allocator >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::ChangeState | ( | const TopologyTransition | transition,
|  | const std::string & | path = `""`,
|  | Duration | timeout = `Duration(0)`
| ) |  | -> std::pair<std::error_code, TopologyState>

inline

Perform state transition on FairMQ devices in this topology for a specified topology path.

Parameters

  transition | FairMQ device state machine transition
  path | Select a subset of FairMQ devices in this topology, empty selects all
  timeout | Timeout in milliseconds, 0 means no timeout

Exceptions

  std::system_error |

## ChangeState() [2/2]

template<typename Executor , typename Allocator >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::ChangeState | ( | const TopologyTransition | transition,
|  | Duration | timeout
| ) |  | -> std::pair<std::error_code, TopologyState>

inline

Perform state transition on all FairMQ devices in this topology with a timeout.

Parameters

  transition | FairMQ device state machine transition
  timeout | Timeout in milliseconds, 0 means no timeout

Exceptions

  std::system_error |

## GetCurrentState()

template<typename Executor , typename Allocator >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::GetCurrentState | ( |  | ) | const -> TopologyState

inline

Returns the current state of the topology.

Returns
  map of id : DeviceStatus

## GetProperties()

template<typename Executor , typename Allocator >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::GetProperties | ( | DevicePropertyQuery const & | query,
|  | const std::string & | path = `""`,
|  | Duration | timeout = `Duration(0)`
| ) |  | -> std::pair<std::error_code, GetPropertiesResult>

inline

Query properties on selected FairMQ devices in this topology.

Parameters

  query | Key(s) to be queried (regex)
  path | Select a subset of FairMQ devices in this topology, empty selects all
  timeout | Timeout in milliseconds, 0 means no timeout

Exceptions

  std::system_error |

## SetProperties()

template<typename Executor , typename Allocator >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::SetProperties | ( | DeviceProperties const & | properties,
|  | const std::string & | path = `""`,
|  | Duration | timeout = `Duration(0)`
| ) |  | -> std::pair<std::error_code, FailedDevices>

inline

Set properties on selected FairMQ devices in this topology.

Parameters

  props | Properties to set
  path | Select a subset of FairMQ devices in this topology, empty selects all
  timeout | Timeout in milliseconds, 0 means no timeout

Exceptions

  std::system_error |

## WaitForState() [1/2]

template<typename Executor , typename Allocator >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::WaitForState | ( | const DeviceState | targetLastState,
|  | const DeviceState | targetCurrentState,
|  | const std::string & | path = `""`,
|  | Duration | timeout = `Duration(0)`
| ) |  | -> std::error_code

inline

Wait for selected FairMQ devices to reach given last & current state in this topology.

Parameters

  targetLastState | the target last device state to wait for
  targetCurrentState | the target device state to wait for
  path | Select a subset of FairMQ devices in this topology, empty selects all
  timeout | Timeout in milliseconds, 0 means no timeout

Exceptions

  std::system_error |

## WaitForState() [2/2]

template<typename Executor , typename Allocator >

auto fair::mq::sdk::BasicTopology< Executor, Allocator >::WaitForState | ( | const DeviceState | targetCurrentState,
|  | const std::string & | path = `""`,
|  | Duration | timeout = `Duration(0)`
| ) |  | -> std::error_code

inline

Wait for selected FairMQ devices to reach given current state in this topology.

Parameters

  targetCurrentState | the target device state to wait for
  path | Select a subset of FairMQ devices in this topology, empty selects all
  timeout | Timeout in milliseconds, 0 means no timeout

Exceptions

  std::system_error |

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

- fairmq/sdk/Topology.h

privacy