Autowiring  1.0.3
A C++ Inversion of Control Framework
AutoPacket Class Reference

A decorator-style processing packet More...

#include <AutoPacket.h>

Inherits enable_shared_from_this< AutoPacket >, and TeardownNotifier.

Public Member Functions

const autowiring::SatCounter * AddRecipient (const autowiring::AutoFilterDescriptor &descriptor)
 Adds a recipient for data associated only with this issuance of the packet. More...
 
template<typename... InArgs, typename... Outputs>
void Call (void(*pfn)(InArgs...), Outputs &...outputs)
 Invokes the specified function as though it were an AutoFilter on this packet More...
 
template<typename Fx , typename... InArgs, typename... Outputs>
void Call (Fx &&fx, void(Fx::*memfn)(InArgs...) const, Outputs &...outputs)
 Invokes a particular member function on the specified function object More...
 
template<typename Fx , typename... Outputs>
void Call (Fx &&fx, Outputs &...outputs)
 Invokes the specified function as though it were an AutoFilter on this packet More...
 
template<class T >
void Decorate (const std::shared_ptr< T > &ptr)
 
template<class T >
void Decorate (const std::shared_ptr< const T > &ptr)
 Decoration method specialized for const shared pointer types More...
 
template<class T >
std::enable_if< !autowiring::is_shared_ptr< T >::value, const T & >::type Decorate (T &&t)
 Decorates this packet with a particular type More...
 
template<class T , class... Ts>
void DecorateImmediate (const T &immed, const Ts &...immeds)
 Subscribers respond to the decoration arguments immediately or never for this packet. Optional argument resolution is forced for any subscriber requiring at least one argument of this method More...
 
template<class T , typename... Args>
const T & Emplace (Args &&...args)
 Decorates this packet with a particular type T, forwarding the arguments to the constructor of T. More...
 
void ForwardAll (const std::shared_ptr< AutoPacket > &recipient) const
 Shares all broadcast data from this packet with the recipient packet More...
 
template<class T >
const T & Get (int tshift=0) const
 Detects the desired type, or throws an exception if such a type cannot be found More...
 
template<class T >
bool Get (const T *&out, int tshift=0) const
 Determines whether this pipeline packet contains an entry of the specified type More...
 
template<class T >
bool Get (const std::shared_ptr< T > *&out, int tshift=0) const
 Shared pointer specialization of const T*&, used to obtain the underlying shared pointer for some type T More...
 
template<class T >
bool Get (std::shared_ptr< const T > &out, int tshift=0) const
 Shared pointer specialization, used to obtain the underlying shared pointer for some type T More...
 
template<class T >
std::unique_ptr< const T *[]> GetAll (int tshift=0) const
 Returns a null-terminated buffer containing all decorations More...
 
template<class T >
std::unique_ptr< std::shared_ptr< const T >[]> GetAllShared (int tshift=0) const
 Shared variant of GetAll More...
 
std::shared_ptr< CoreContextGetContext (void) const
 Get the context of this packet (The context of the AutoPacketFactory that created this context)
 
t_decorationMap GetDecorations (void) const
 
size_t GetDecorationTypeCount (void) const
 
template<class T >
T && GetRvalue (int tshift=0) const
 
template<class T >
std::shared_ptr< T > && GetRvalueShared (int tshift=0)
 
template<class T >
const autowiring::SatCounter & GetSatisfaction (void) const
 
template<class T >
const std::shared_ptr< const T > * GetShared (int tshift=0) const
 
template<class T >
bool Has (int tshift=0) const
 
template<typename T >
size_t HasPublishers (void) const
 
Returns
Zero if there are no publishers, otherwise the number of publishers

 
template<typename T >
bool HasSubscribers (void) const
 
Returns
True if the indicated type has been requested for use by some consumer

 
bool IsUnsatisfiable (const auto_id &id) const
 
template<class T >
void MarkUnsatisfiable (void)
 Marks the named decoration as unsatisfiable More...
 
template<class Fx >
const autowiring::SatCounter * operator+= (Fx &&fx)
 Convenience overload, identical in behavior to AddRecipient More...
 
template<class Fx >
const AutoPacketoperator+= (Fx &&fx) const
 Convenience overload, provided to allow the attachment of receive-only filters to a const AutoPacket More...
 
template<class T >
void RemoveDecoration (void)
 Remove decorations on this packet with a particular type More...
 
void RemoveRecipient (const autowiring::SatCounter &recipient)
 Removes a previously added packet recipient The user is responsible to free the memeory for recipient. TODO: seems like a bad design, need refactor More...
 
std::shared_ptr< AutoPacketSuccessor (void)
 Returns the next packet that will be issued by the packet factory in this context relative to this context More...
 
bool Wait (std::condition_variable &cv, const autowiring::AutoFilterArgument *inputs, std::chrono::nanoseconds duration=std::chrono::nanoseconds::max())
 Blocks until the specified descriptor is satisfied More...
 
template<class Fx >
bool Wait (std::condition_variable &cv, Fx &&autoFilter, std::chrono::nanoseconds duration=std::chrono::nanoseconds::max())
 Blocks until the passed lambda function can be called More...
 
template<class... Decorations>
bool Wait (std::condition_variable &cv)
 Delays until the specified decorations are satisfied More...
 
template<class... Args>
bool Wait (std::chrono::nanoseconds duration, std::condition_variable &cv)
 Timed version of Wait More...
 

Static Public Member Functions

static AutoPacketClearCurrent (void)
 Clears the current AutoPacket pointer More...
 
static AutoPacketCurrentPacket (void)
 Retrieves the current packet being processed by an AutoFilter More...
 
static AutoPacketSetCurrent (AutoPacket *apkt)
 Sets the current AutoPacket pointer More...
 

Protected Member Functions

void AddSatCounterUnsafe (autowiring::SatCounter &satCounter)
 Adds all AutoFilter argument information for a recipient More...
 
void Decorate (const AnySharedPointer &ptr, autowiring::DecorationKey key)
 Runtime counterpart to Decorate More...
 
autowiring::DecorationDisposition & DecorateImmediateUnsafe (const autowiring::DecorationKey &key, const void *pvImmed)
 Checks out the decoration named by the specified type information and attaches the specified immediate pointer to it More...
 
void DecorateNoPriors (const AnySharedPointer &ptr, autowiring::DecorationKey key)
 Performs a decoration operation but does not attach priors to successors. More...
 
void DetectCycle (autowiring::SatCounter &satCounter, std::unordered_set< autowiring::SatCounter * > &tempVisited, std::unordered_set< autowiring::SatCounter * > &permVisited)
 Detect cycle in the auto filter graph using DFS
 
const autowiring::DecorationDisposition * GetDisposition (const autowiring::DecorationKey &ti) const
 Retrieves the decoration disposition corresponding to some type More...
 
const autowiring::SatCounter & GetSatisfaction (auto_id subscriber) const
 
size_t HasPublishers (const autowiring::DecorationKey &key) const
 
Returns
Zero if there are no publishers, otherwise the number of publishers

 
bool HasSubscribers (const autowiring::DecorationKey &key) const
 
Returns
True if the indicated type has been requested for use by some consumer

 
bool HasUnsafe (const autowiring::DecorationKey &key) const
 Unsynchronized runtime counterpart to Has More...
 
void MarkSuccessorsUnsatisfiable (autowiring::DecorationKey type)
 Marks timeshifted decorations on successor packets as unsatisfiable More...
 
void MarkUnsatisfiable (const autowiring::DecorationKey &key)
 Marks the specified entry as being unsatisfiable More...
 
void PulseSatisfactionUnsafe (std::unique_lock< std::mutex > lk, autowiring::DecorationDisposition *pTypeSubs[], size_t nInfos)
 Performs a "satisfaction pulse", which will avoid notifying any deferred filters More...
 
void RemoveDecoration (autowiring::DecorationKey key)
 Runtime counterpart to RemoveDecoration More...
 
void RemoveSatCounterUnsafe (const autowiring::SatCounter &satCounter)
 Remove all AutoFilter argument information for a recipient
 
std::shared_ptr< AutoPacketSuccessorUnsafe (void)
 The portion of Successor that must run under a lock More...
 
void UpdateSatisfactionUnsafe (std::unique_lock< std::mutex > lk, const autowiring::DecorationDisposition &disposition)
 Updates subscriber statuses given that the specified type information has been satisfied More...
 

Static Protected Member Functions

static void ThrowMultiplyDecoratedException (const autowiring::DecorationKey &key)
 Throws a formatted runtime error corresponding to the case where a decoration was demanded and more than one such decoration was present More...
 
static void ThrowNotDecoratedException (const autowiring::DecorationKey &key)
 Throws a formatted runtime error corresponding to the case where an absent decoration was demanded More...
 

Detailed Description

A decorator-style processing packet

A processing packet may be decorated with additional types as desired by the user. The pipeline packet is not a type of context; querying the packet for an element of a particular type will look for an element of precisely that type, not an inherited type or a related interface.

Member Function Documentation

const autowiring::SatCounter* AutoPacket::AddRecipient ( const autowiring::AutoFilterDescriptor &  descriptor)

Adds a recipient for data associated only with this issuance of the packet.

This method is idempotent. The returned Recipient structure may be used to remove the recipient safely at any point.

Referenced by operator+=().

void AutoPacket::AddSatCounterUnsafe ( autowiring::SatCounter &  satCounter)
protected

Adds all AutoFilter argument information for a recipient

template<typename... InArgs, typename... Outputs>
void AutoPacket::Call ( void(*)(InArgs...)  pfn,
Outputs &...  outputs 
)
inline

Invokes the specified function as though it were an AutoFilter on this packet

Referenced by Call().

template<typename Fx , typename... InArgs, typename... Outputs>
void AutoPacket::Call ( Fx &&  fx,
void(Fx::*)(InArgs...) const  memfn,
Outputs &...  outputs 
)
inline

Invokes a particular member function on the specified function object

template<typename Fx , typename... Outputs>
void AutoPacket::Call ( Fx &&  fx,
Outputs &...  outputs 
)
inline

Invokes the specified function as though it were an AutoFilter on this packet

static AutoPacket* AutoPacket::ClearCurrent ( void  )
inlinestatic

Clears the current AutoPacket pointer

Identical to SetCurrent(nullptr)

static AutoPacket& AutoPacket::CurrentPacket ( void  )
static

Retrieves the current packet being processed by an AutoFilter

It is an error to call this anywhere except from an AutoFilter routine

void AutoPacket::Decorate ( const AnySharedPointer &  ptr,
autowiring::DecorationKey  key 
)
protected

Runtime counterpart to Decorate

Referenced by Decorate(), and Emplace().

template<class T >
void AutoPacket::Decorate ( const std::shared_ptr< T > &  ptr)
inline

Decoration method specialized for shared pointer types

This decoration method has the additional benefit that it will make direct use of the passed shared pointer.

If the passed value is null, the corresponding value will be marked unsatisfiable.

template<class T >
void AutoPacket::Decorate ( const std::shared_ptr< const T > &  ptr)
inline

Decoration method specialized for const shared pointer types

This decoration method has the additional benefit that it will make direct use of the passed shared pointer.

template<class T >
std::enable_if< !autowiring::is_shared_ptr<T>::value, const T& >::type AutoPacket::Decorate ( T &&  t)
inline

Decorates this packet with a particular type

Returns
A reference to the internally persisted object

The Decorate method is unconditional and will install the passed value regardless of whether any subscribers exist.

template<class T , class... Ts>
void AutoPacket::DecorateImmediate ( const T &  immed,
const Ts &...  immeds 
)
inline

Subscribers respond to the decoration arguments immediately or never for this packet. Optional argument resolution is forced for any subscriber requiring at least one argument of this method

Unlike Decorate, the arguments of DecorateImmediate are not copied. Each decoration is only valid for AutoFilters which are valid during this call. If multiple values are specified, all will be simultaneously made valid and then invalidated.

autowiring::DecorationDisposition& AutoPacket::DecorateImmediateUnsafe ( const autowiring::DecorationKey &  key,
const void *  pvImmed 
)
protected

Checks out the decoration named by the specified type information and attaches the specified immediate pointer to it

An immediate checkout differs from a standard checkout in that the internally held decoration is only temporarily available. Thus, callers are either satisfied at the point of decoration, or will not be satisfied for that type.

Referenced by DecorateImmediate().

void AutoPacket::DecorateNoPriors ( const AnySharedPointer &  ptr,
autowiring::DecorationKey  key 
)
protected

Performs a decoration operation but does not attach priors to successors.

template<class T , typename... Args>
const T& AutoPacket::Emplace ( Args &&...  args)
inline

Decorates this packet with a particular type T, forwarding the arguments to the constructor of T.

Returns
A reference to the internally persisted object

The Decorate method is unconditional and will install the passed value regardless of whether any subscribers exist.

void AutoPacket::ForwardAll ( const std::shared_ptr< AutoPacket > &  recipient) const

Shares all broadcast data from this packet with the recipient packet

This method should ONLY be called during the final-call sequence. This method is expected to be used to bridge data to a sibling context. Therefore, only broadcast data will be shared, since pipes between sibling contexts cannot be defined. Furthermore, types that are unsatisfied in this context will not be marked as unsatisfied in the recipient - only present data will be provided.

template<class T >
const T& AutoPacket::Get ( int  tshift = 0) const
inline

Detects the desired type, or throws an exception if such a type cannot be found

Referenced by GetRvalue(), and GetShared().

template<class T >
bool AutoPacket::Get ( const T *&  out,
int  tshift = 0 
) const
inline

Determines whether this pipeline packet contains an entry of the specified type

This method is also used by DecorateImmediate to extract pointers to data that is valid ONLY during recursive satisfaction calls.

template<class T >
bool AutoPacket::Get ( const std::shared_ptr< T > *&  out,
int  tshift = 0 
) const
inline

Shared pointer specialization of const T*&, used to obtain the underlying shared pointer for some type T

Parameters
outReceives the requested decoration, or else nullptr
tshiftThe number back to retrieve

This specialization cannot be used to obtain a decoration which has been attached to this packet via DecorateImmediate.

This method will throw an exception if the requested decoration is multiply present on the packet

template<class T >
bool AutoPacket::Get ( std::shared_ptr< const T > &  out,
int  tshift = 0 
) const
inline

Shared pointer specialization, used to obtain the underlying shared pointer for some type T

This method can return an argument of DecorateImmediate as a shared_ptr<T> without a deleter. PROBLEM: This use case implies that holding shared_ptr references to decorations is NOT SAFE.

template<class T >
std::unique_ptr<const T*[]> AutoPacket::GetAll ( int  tshift = 0) const
inline

Returns a null-terminated buffer containing all decorations

Returns
The null-terminated buffer
template<class T >
std::unique_ptr<std::shared_ptr<const T>[]> AutoPacket::GetAllShared ( int  tshift = 0) const
inline

Shared variant of GetAll

Returns
The null-terminated buffer
t_decorationMap AutoPacket::GetDecorations ( void  ) const
Returns
A copy of the decoration dispositions collection (this is really an implementation-detail-based description of the parameters of all relevant filters, including lambdas appended to this packet).

This is a diagnostic method, users are recommended to avoid the use of this routine where possible

size_t AutoPacket::GetDecorationTypeCount ( void  ) const
Returns
The number of distinct decoration types on this packet (this is really an implementation-detail-based count of the parameters of all relevant filters, including lambdas appended to this packet).
const autowiring::DecorationDisposition* AutoPacket::GetDisposition ( const autowiring::DecorationKey &  ti) const
protected

Retrieves the decoration disposition corresponding to some type

Returns
The disposition, if the decoration exists and is satisfied, otherwise nullptr

Referenced by Get().

template<class T >
T&& AutoPacket::GetRvalue ( int  tshift = 0) const
inline
Returns
The Rvalue decoration for the specified type and time shift, or throws an exception if such a type cannot be found
template<class T >
std::shared_ptr<T>&& AutoPacket::GetRvalueShared ( int  tshift = 0)
inline
Returns
The Rvalue shared pointer decoration for the specified type and time shift, or throws an exception is such a type cannot be found
const autowiring::SatCounter& AutoPacket::GetSatisfaction ( auto_id  subscriber) const
protected
Returns
A reference to the satisfaction counter for the specified type

If the type is not a subscriber GetSatisfaction().GetType() == nullptr will be true

template<class T >
const autowiring::SatCounter& AutoPacket::GetSatisfaction ( void  ) const
inline
Returns
A reference to the satisfaction counter for the specified type

If the type is not a subscriber GetSatisfaction().GetType() == nullptr will be true

Referenced by GetSatisfaction().

template<class T >
const std::shared_ptr<const T>* AutoPacket::GetShared ( int  tshift = 0) const
inline
Returns
The shared pointer decoration for the specified type and time shift, or nullptr if no such decoration exists
template<class T >
bool AutoPacket::Has ( int  tshift = 0) const
inline
Returns
True if this packet posesses one or more instances of a decoration of the specified type

Although "AutoPacket &" and "const AutoPacket&" argument types will be satisfied, the AutoPacket does not "have" these types.

bool AutoPacket::HasUnsafe ( const autowiring::DecorationKey &  key) const
protected

Unsynchronized runtime counterpart to Has

Referenced by Has().

bool AutoPacket::IsUnsatisfiable ( const auto_id &  id) const
Returns
True if the specified type is unsatisfiable
void AutoPacket::MarkSuccessorsUnsatisfiable ( autowiring::DecorationKey  type)
protected

Marks timeshifted decorations on successor packets as unsatisfiable

void AutoPacket::MarkUnsatisfiable ( const autowiring::DecorationKey &  key)
protected

Marks the specified entry as being unsatisfiable

template<class T >
void AutoPacket::MarkUnsatisfiable ( void  )
inline

Marks the named decoration as unsatisfiable

Marking a decoration as unsatisfiable immediately causes any filters with an input of the form std::shared_ptr<const T> to be called, if the remainder of their inputs are available.

Referenced by DecorateImmediate().

template<class Fx >
const autowiring::SatCounter* AutoPacket::operator+= ( Fx &&  fx)
inline

Convenience overload, identical in behavior to AddRecipient

template<class Fx >
const AutoPacket& AutoPacket::operator+= ( Fx &&  fx) const
inline

Convenience overload, provided to allow the attachment of receive-only filters to a const AutoPacket

void AutoPacket::PulseSatisfactionUnsafe ( std::unique_lock< std::mutex >  lk,
autowiring::DecorationDisposition *  pTypeSubs[],
size_t  nInfos 
)
protected

Performs a "satisfaction pulse", which will avoid notifying any deferred filters

A satisfaction pulse will call any AutoFilter instances which are satisfied by the decoration of the passed decoration types.

Referenced by DecorateImmediate().

void AutoPacket::RemoveDecoration ( autowiring::DecorationKey  key)
protected

Runtime counterpart to RemoveDecoration

template<class T >
void AutoPacket::RemoveDecoration ( void  )
inline

Remove decorations on this packet with a particular type

void AutoPacket::RemoveRecipient ( const autowiring::SatCounter &  recipient)

Removes a previously added packet recipient The user is responsible to free the memeory for recipient. TODO: seems like a bad design, need refactor

static AutoPacket* AutoPacket::SetCurrent ( AutoPacket apkt)
static

Sets the current AutoPacket pointer

Referenced by ClearCurrent().

std::shared_ptr<AutoPacket> AutoPacket::Successor ( void  )

Returns the next packet that will be issued by the packet factory in this context relative to this context

std::shared_ptr<AutoPacket> AutoPacket::SuccessorUnsafe ( void  )
protected

The portion of Successor that must run under a lock

static void AutoPacket::ThrowMultiplyDecoratedException ( const autowiring::DecorationKey &  key)
staticprotected

Throws a formatted runtime error corresponding to the case where a decoration was demanded and more than one such decoration was present

Referenced by Get(), and GetRvalueShared().

static void AutoPacket::ThrowNotDecoratedException ( const autowiring::DecorationKey &  key)
staticprotected

Throws a formatted runtime error corresponding to the case where an absent decoration was demanded

Referenced by Get(), GetRvalue(), and GetRvalueShared().

void AutoPacket::UpdateSatisfactionUnsafe ( std::unique_lock< std::mutex >  lk,
const autowiring::DecorationDisposition &  disposition 
)
protected

Updates subscriber statuses given that the specified type information has been satisfied

Parameters
lkThe unique_lock used to control the synchronization level
dispositionThe decoration that was just updated

This method results in a call to the AutoFilter method on any subscribers which are satisfied by this decoration. This method must be called with m_lock held.

bool AutoPacket::Wait ( std::condition_variable &  cv,
const autowiring::AutoFilterArgument *  inputs,
std::chrono::nanoseconds  duration = std::chrono::nanoseconds::max() 
)

Blocks until the specified descriptor is satisfied

Parameters
cvA condition variable used to perform the wait
inputsThe inputs whose satisfaction state is to be considered
durationThe amount of time to wait. If set to std::chrono::nanoseconds::max, this method will block indefinitely
Returns
False if a timeout occurred, true otherwise

This method considers the arguments described by "inputs" and will block until all decorations that are needed by this filter have been satisfied on this packet. When this function returns, the specified filter will have been called.

Referenced by Wait().

template<class Fx >
bool AutoPacket::Wait ( std::condition_variable &  cv,
Fx &&  autoFilter,
std::chrono::nanoseconds  duration = std::chrono::nanoseconds::max() 
)
inline

Blocks until the passed lambda function can be called

Parameters
cvA condition variable that can be signalled when the wait condition has expired
autoFilterThe filter to be blocked on
durationThe maximum amount of time to wait
Returns
True on success, false if a timeout occurred

This method will invoke the passed autoFilter function once all of its arguments are present on the packet this routine generates internally. This method will not return until the specified autoFilter is called. If the autoFilter cannot be called because the required decorations are not present on the packet on teardown, this method will throw an exception.

The passed autoFilter routine must not attach any decorations to the packet, nor may it accept a non-const AutoFilter as an input argument.

template<class... Decorations>
bool AutoPacket::Wait ( std::condition_variable &  cv)
inline

Delays until the specified decorations are satisfied

template<class... Args>
bool AutoPacket::Wait ( std::chrono::nanoseconds  duration,
std::condition_variable &  cv 
)
inline

Timed version of Wait


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