index.hpp File Reference

Go to the source code of this file.

Description

Implementation datastructure for use by the Advice system.

To support the Advice collaboration, it is necessary to match advice requests with existing advice provisions. Each successful match creates an advice solution, resulting in the bound piece of advice (data) to become visible to all the advised entities having placed a matching advice request into the advice system.

This header is intended to be incorporated as part of the advice system implementation (advice.cpp). It is not usable as an external interface. But it is written in a rather self-contained manner, in order to be testable in isolation. To this end, the actual PointOfAdvice entities being organised by this index datastructure remain abstract (defined as template parameter), and are only manipulated through the following functions:

• hash_value(POA)
• POA::getMatcher()
• POA::getSolution()
• POA::setSolution(solution*)

implementation notes

The advice binding index is implemented by two hashtables holding Binding::Matcher entries. Each entry associates a back-link to the corresponding POA (PointOfAdvice), which is assumed to be maintained outside the index. PointOfAdvice is an type-erased interface baseclass. Actually the advice system will have to deal with concrete advice::Request and advice::Provision objects, which are templated to a specific advice type; but this specifically typed context is kept on the interface level (advice.hpp) and the type information is stripped before calling into the actual implementation, so the index can be implemented generic.

While both hashtables are organised by the binding pattern hash, the individual buckets are coded explicitly as ProvisionCluster and RequestCluster – both based on a vector of entries. In case of the provisions, there is a stack-like order, inasmuch additions happen at the back and solutions are always searched starting from the end. Because of the basic structure of a binding match, solutions are possible only between provision/request - clusters with the same hash value (which is based on the predicate symbols within the patterns to match). Thus, in case of changing an existing request or solution, the internal handling is different, depending on the new value to belong or don't belong to the same cluster (hash code). It's possible (for patterns including variables) that an entry leading to a solution with the old provision doesn't match a new provision (and vice versa); thus we'll have to traverse the contents of the whole cluster, find all old solutions, match against the new counterpart and treating those entries not matching with the new value as if they where completely newly added entries. In case we don't find any solution, the entries are supposed to be implemented such as to fall back to an default solution automatically (when receiving a NULL solution)

Note

as of 4/2010 this is an experimental setup and implemented just enough to work out the interfaces. Ichthyo expects this collaboration service to play a central role later at various places within steam-layer.

for now, only the case of a completely constant (ground) pattern is implemented. Later we may consider to extend the binding patterns to allow variables. The mechanics of the index are designed right from start to support this case (and indeed the index could be much simpler if it wasn't to deal with this foreseeable additional complexity: When a pattern contains variables, then even within one bucket of the hashtable there might be non-matching entries. Each individual pair of (provision, request) has to be checked explicitly to determine a match. /////////////////////////TICKET #615

See also

advice.hpp

binding.hpp

advice-index-test.cpp

advice-binding-pattern-test.cpp

advice-basics-test.cpp

Definition in file index.hpp.

#include "lib/error.hpp"
#include "lib/symbol.hpp"
#include "include/logging.h"
#include "lib/iter-adapter-stl.hpp"
#include "lib/format-obj.hpp"
#include "lib/util-foreach.hpp"
#include "lib/util.hpp"
#include "common/advice/binding.hpp"
#include <boost/operators.hpp>
#include <unordered_map>
#include <string>

Classes
struct	Index< POA >::Cluster
struct	Index< POA >::Entry
class	Index< POA >
	Index datastructure for organising advice solutions. More...
struct	Index< POA >::ProvisionCluster
struct	Index< POA >::RequestCluster
struct	SelfCheckFailure

Macros
#define	VERIFY(_CHECK_, DESCRIPTION)

Functions
	LUMIERA_ERROR_DEFINE (INDEX_CORRUPTED, "Advice-Index corrupted")

Namespaces
	lumiera
	Lumiera public interface.

Macro Definition Documentation

VERIFY

#define VERIFY	(		_CHECK_,
			DESCRIPTION
	)

Value:

if (!(_CHECK_))                 \
        throw SelfCheckFailure ((DESCRIPTION));

Definition at line 552 of file index.hpp.