Template Class Duct

Class Documentation

template<typename ImplSpec>
class uit::internal::Duct

Performs data transmission between an Inlet and an `Outlet.

Under the hood, a Duct actually wraps a std::variant of three implementation types:

  1. IntraDuct: implementation type that performs transmission between an Inlet and Outlet that reside on the same thread in the same process.

  2. ThreadDuct: implementation type that performs transmission betweeen an Inlet and Outlet that reside on different threads, but are within the same process.

  3. ProcDuct: implementation type that performs transmission between an Inlet and Outlet that reside on different processes. (See note.)

The std::variant template represents a type-safe union. A std::variant instance holds an instance of just one of its alternative types. However, the type which a std::variant instance holds may be freely determined and arbitrarily switched during the lifetime of the instance.

When a Duct is constructed, the IntraDuct implementation is constructed and held by the Duct’s std::variant. An alternate implementation (i.e., a thread-safe or process-safe implementaiton) may be emplaced within the Duct’s std::variant by calling EmplaceDuct. This design enables the Duct’s active implementation to be switched at run-time, even if after the Duct has been already transmitted through. However, when the Duct’s implementation is switched, no attempt is made to transfer state (i.e., pending data) between the destructed implementation and its replacement. All Duct operations are forwarded to the active implementation type within a Duct’s std::variant.

The actual identity of the IntraDuct, ThreadDuct, and ProcDuct implementations are themselves modular and may be specified via the ImplSpec template paramater. You can find available intra-thread, inter-thread, and inter-process implementations within the include/ducts/intra, include/ducts/thread, and include/ducts/proc directories, respectively. You may also supply your own implementations so long as they satisfy the method signatures within this class that are forwarded to the std::variant’s active implementation.

Note

Because processes do not share memory space and inter-process communication code is typically asymmetric between the sender and receiver, the ProcDuct implementation actually corresponds to two distinct implementations: a ProcInletDuct implementaiton and a ProcOutletDuctimplementation. The ProcInletDuct performs the inter-process sending role and the ProcOutletDuct performs the inter-process receiving role. So, in reality a Duct wraps a std::variant of four implementation types.

Note

End users should probably never have to directly instantiate this class. The Conduit, Sink, and Source classes take care of creating a Duct and tying it to an Inlet and/or Outlet. Better yet, the MeshTopology interface allows end users to construct a conduit network in terms of a connection topology and a mapping to assign nodes to threads and processes without having to manually construct Conduits and emplace necessary thread-safe and/or process-safe Duct implementations.

Template Parameters

  • ImplSpec: class with static and typedef members specifying implementation details for the conduit framework. See include/config/ImplSpec.hpp.

Public Types

using uid_t = std::uintptr_t

TODO.

Public Functions

Duct(Duct &other) = default

Copy constructor.

Duct(const Duct &other) = default

Copy constructor.

Duct(Duct &&other) = default

Move constructor.

template<typename ...Args>
Duct(Args&&... args)

Forwarding constructor.

Use std::in_place_t<ImplType> followed by constructor arguments to initialize the Duct with ImplType active.

template<typename WhichDuct, typename ...Args>
void EmplaceImpl(Args&&... args)

TODO.

Template Parameters

  • WhichDuct: TODO

  • Args: TODO

Parameters

  • args: TODO

bool TryPut(const T &val)

TODO.

Return

TODO.

Parameters

  • val: TODO.

template<typename P>
bool TryPut(P &&val)

TODO.

Return

TODO.

Parameters

  • val: TODO.

bool TryFlush()

TODO.

const T &Get() const

TODO.

Return

TODO.

T &Get()

TODO.

Return

TODO.

size_t TryConsumeGets(const size_t requested)

TODO.

Return

number of gets actually consumed.

Parameters

  • count: maximum number of gets to consume.

std::string WhichImplIsActive() const

TODO.

Return

TODO.

emp::optional<bool> HoldsIntraImpl() const

TODO.

Return

TODO.

emp::optional<bool> HoldsThreadImpl() const

TODO.

Return

TODO.

emp::optional<bool> HoldsProcImpl() const

TODO.

Return

TODO.

uid_t GetUID() const

TODO.

Return

TODO.

bool CanStep() const
std::string ToString() const

TODO.

Return

TODO.