ichthyo/LUMIERA.clone
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
LUMIERA.clone/src/proc/mobject/session/placement-index.cpp

662 lines
21 KiB
C++
Raw Blame History

/*
PlacementIndex - tracking individual Placements and their relations
Copyright (C) Lumiera.org
2008, Hermann Vosseler <Ichthyostega@web.de>
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of the
License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
* *****************************************************/
/** @file placement-index.cpp
** Implementation of core session storage structure.
** The PlacementIndex associates IDs to instances, and nested scope structure.
** Moreover, it provides and manages the actual Placement instances (storage),
** considered to be part of the session.
**
** Simple hash based implementation. Seems adequate for now (12/09).
** A main table associates Placement-ID to an Placement \em instance, which is contained
** and managed within this index. A second hashtable allows to reverse lookup the scope
** associations, especially for enumerating the contents of a scope. The latter is done
** by wrapping up an STL iterator range into a "Lumiera Forward Iterator" (adapter).
** Generally speaking, PlacementIndex is an implementation level facility and provides
** the basic/low-level functionality. For example, the PlacementIndexQueryResolver
** provides depth-first exploration of all the contents of an scope, including nested scopes,
** building on top of these scope iterators from PlacementIndex.
**
** PlacementIndex can be seen as the core datastructure of the session. Objects are attached
** to the session by adding (copying) a Placement instance, which is owned and managed by
** the PlacementIndex. Adding this Placement instance creates a new Placement-ID, which
** from then on acts as a shorthand for "the object instance" within the session.
** The actual storage is provided by an embedded TypedAllocationManager instance, which
** is planned (as of 12/09) to be backed later by a memory pool based custom allocator.
**
** @see PlacementRef
** @see PlacementIndex_test
**
*/
#include "proc/mobject/session/placement-index.hpp"
#include "proc/mobject/session/session-impl.hpp"
#include "proc/mobject/session/scope.hpp"
#include "lib/typed-allocation-manager.hpp"
//#include "proc/mobject/mobject.hpp" ///////////////////////TODO necessary?
#include "lib/util-foreach.hpp"
#include "lib/iter-source.hpp"
//#include <boost/format.hpp>
//using boost::str;
#include <boost/lambda/lambda.hpp>
#include <boost/functional/hash.hpp>
#include <boost/noncopyable.hpp>
#include <tr1/unordered_map>
#include <tr1/functional>
#include <tr1/memory>
//#include <algorithm>
#include <string>
//#include <map>
namespace mobject {
namespace session {
using boost::hash;
using boost::noncopyable;
using std::tr1::shared_ptr;
using std::tr1::unordered_map;
using std::tr1::unordered_multimap;
using lib::TypedAllocationManager;
using std::tr1::placeholders::_1;
using std::tr1::function;
using std::tr1::bind;
//using util::contains;
//using std::string;
//using std::map;
using std::make_pair;
using std::pair;
using util::for_each;
using util::has_any;
using namespace lumiera;
LUMIERA_ERROR_DEFINE (NOT_IN_SESSION, "referring to a Placement not known to the current session");
LUMIERA_ERROR_DEFINE (PLACEMENT_TYPE, "requested Placement (pointee) type not compatible with data or context");
LUMIERA_ERROR_DEFINE (NONEMPTY_SCOPE, "Placement scope (still) contains other elements");
/* some type shorthands */
typedef PlacementIndex::PlacementMO PlacementMO;
typedef PlacementIndex::PRef PRef;
typedef PlacementIndex::ID ID;
/**
* Storage and implementation backing the PlacementIndex
* - #placementTab_ is an hashtable mapping IDs to Placement + Scope
* - #scopeTab_ is an reverse association serving to keep track of
* any scope's contents
* - root scope element is stored and maintained explicitly.
*/
class PlacementIndex::Table
{
typedef shared_ptr<PlacementMO> PPlacement;
struct PlacementEntry
{
PPlacement element;
PPlacement scope;
};
// using hashtables to implement the index
typedef PlacementMO::ID PID;
typedef unordered_map<PID, PlacementEntry, hash<PID> > IDTable;
typedef std::tr1::unordered_multimap<PID,PID, hash<PID> > ScopeTable;
typedef pair<ScopeIter, ScopeIter> ScopeContents;
TypedAllocationManager allocator_;
IDTable placementTab_;
ScopeTable scopeTab_;
PPlacement root_;
public:
Table ()
{ }
~Table ()
{
try
{
root_.reset();
clear();
}
catch(lumiera::Error& err)
{
WARN (session, "Problem while purging PlacementIndex: %s", err.what());
lumiera_error(); // discard any error state
} }
size_t
size() const
{
return placementTab_.size();
}
size_t
scope_cnt() const
{
return scopeTab_.size();
}
size_t
element_cnt() const
{
return allocator_.numSlots<PlacementMO>();
}
bool
contains (ID id) const
{
return util::contains(placementTab_, id);
}
PlacementMO&
fetch (ID id) const
{
REQUIRE (contains (id));
PPlacement const& entry = base_entry(id).element;
ENSURE (entry);
ENSURE (id == entry->getID());
return *entry;
}
PlacementMO&
fetchScope (ID id) const
{
REQUIRE (contains (id));
PPlacement const& scope = base_entry(id).scope;
ENSURE (scope);
ENSURE (contains (scope->getID()));
return *scope;
}
PlacementIndex::iterator
queryScopeContents (ID id) const
{
REQUIRE (contains (id));
ScopeContents contents = scopeTab_.equal_range (id);
return iterator (ScopeRangeIter(contents.first, contents.second)
,scopeIndexElementsResolver() );
}
void
clear()
{
INFO (session, "Purging Placement Tables...");
scopeTab_.clear();
placementTab_.clear();
if (root_)
setupRoot (*root_);
}
/** insert a specially configured root entry into
* the yet empty table. Root is it's own scope
*/
void
setupRoot (PlacementMO const& rootDef)
{
REQUIRE (0 == placementTab_.size());
REQUIRE (0 == scopeTab_.size());
REQUIRE (!root_);
root_ = allocator_.create<PlacementMO> (rootDef);
ID rootID = root_->getID();
placementTab_[rootID].element = root_;
placementTab_[rootID].scope = root_;
ENSURE (contains (rootID));
ENSURE (scopeTab_.empty());
ENSURE (1 == size());
}
PlacementMO&
getRootElement()
{
REQUIRE (root_);
REQUIRE (0 < size());
REQUIRE (contains (root_->getID()));
return *root_;
}
/** Store a copy of the given Placement as new instance
* within the index, together with the Scope this Placement
* belongs to.
* @note we discard the specific type info.
* It can be rediscovered later with the help
* of the pointee's vtable
* @see Placement#isCompatible
*/
ID
addEntry (PlacementMO const& newObj, ID scopeID)
{
REQUIRE (contains (scopeID));
PPlacement newEntry = allocator_.create<PlacementMO> (newObj);
ID newID = newEntry->getID();
ASSERT (newID, "invalid");
ASSERT (!contains (newID));
placementTab_[newID].element = newEntry;
placementTab_[newID].scope = placementTab_[scopeID].element;
scopeTab_.insert (make_pair (scopeID, newID));
return newID;
}
bool
removeEntry (ID id)
{
if (!contains (id))
{
ENSURE (!util::contains(scopeTab_, id));
return false;
}
if (util::contains(scopeTab_, id))
throw error::State ("Unable to remove the specified Placement, "
"because it defines an non-empty scope. "
"You need to delete any contents first."
,LUMIERA_ERROR_NONEMPTY_SCOPE); ////////////////TICKET #197
ASSERT (contains (id));
PlacementEntry toRemove = remove_base_entry (id);
remove_from_scope (toRemove.scope->getID(), id);
ENSURE (!util::contains(scopeTab_, id));
ENSURE (!contains (id));
return true;
}
/* == access for self-test == */
typedef lib::IterSource<PID>::iterator IDIter;
PlacementMO* _root_4check () { return root_.get(); }
PlacementMO* _element_4check (ID id){ return base_entry(id).element.get();}
PlacementMO* _scope_4check (ID id) { return base_entry(id).scope.get(); }
IDIter _eachEntry_4check () { return eachMapKey (placementTab_); }
IDIter _eachScope_4check () { return eachDistinctKey (scopeTab_); }
private:
typedef IDTable::const_iterator Slot;
PlacementEntry const&
base_entry (ID key) const
{
Slot pos = placementTab_.find (key);
if (pos == placementTab_.end())
throw error::Logic("lost a Placement expected to be registered in the index.");
return pos->second;
}
PlacementEntry
remove_base_entry (ID key)
{
Slot pos = placementTab_.find (key);
REQUIRE (pos != placementTab_.end());
PlacementEntry dataToRemove (pos->second);
placementTab_.erase(pos);
return dataToRemove;
}
void
remove_from_scope (ID scopeID, ID entryID)
{
typedef ScopeTable::const_iterator Pos;
pair<Pos,Pos> searchRange = scopeTab_.equal_range(scopeID);
Pos pos = searchRange.first;
Pos end = searchRange.second;
for ( ; pos!=end; ++pos)
if (pos->second == entryID)
{
scopeTab_.erase(pos);
return;
}
NOTREACHED();
}
/** Helper for building a scope exploring iterator
* for PlacementIndex: our "reverse index" (#scopeTab_)
* tracks the contents of each scope as pairs (scopeID,elementID).
* After fetching the range of matching entries, whenever the client
* dereferences the iterator, we have to pick up the second ID and
* resolve it through the main index table (placementTab_).
*/
PlacementMO&
resolveScopeIndexElement(pair<PID,PID> const& entry) const
{
ID elemID (entry.second);
ASSERT (contains (elemID));
return fetch (elemID);
}
typedef function<PlacementMO& (pair<PID,PID> const&)> ElementResolver;
mutable ElementResolver elementResolver_;
ElementResolver
scopeIndexElementsResolver() const ///< @return functor for iterator element access
{
if (!elementResolver_)
elementResolver_ = bind (&Table::resolveScopeIndexElement, this, _1 );
return elementResolver_;
}
};
/* ============ PlacementIndex implementation functions ============ */
PlacementIndex::PlacementIndex (PlacementMO const& rootDef)
: pTab_(new Table)
{
INFO (session, "Initialising PlacementIndex...");
pTab_->setupRoot(rootDef);
ENSURE (isValid());
}
PlacementIndex::~PlacementIndex() { }
PlacementMO&
PlacementIndex::getRoot() const
{
return pTab_->getRootElement();
}
size_t
PlacementIndex::size() const
{
ASSERT (0 < pTab_->size());
return pTab_->size() - 1;
}
bool
PlacementIndex::contains (ID id) const
{
return pTab_->contains (id);
}
PlacementMO&
PlacementIndex::find (ID id) const
{
__check_knownID(*this,id);
return pTab_->fetch (id);
}
/** retrieve the Scope information
* registered alongside with the denoted Placement.
* @throw error::Invalid when the given ID isn't registered
* @note root is it's own scope, per definition.
*/
PlacementMO&
PlacementIndex::getScope (ID id) const
{
__check_knownID(*this,id);
return pTab_->fetchScope (id);
}
/** Retrieve all the elements attached to the given entry (scope)
* Each element (Placement) can act as a scope, containing other Placements,
* which will be discovered by this query one level deep (not recursive).
* @return an Lumiera Forward Iterator, yielding the children,
* possibly empty if the denoted element is a leaf.
* @note results are returned in arbitrary order (hashtable)
*/
PlacementIndex::iterator
PlacementIndex::getReferrers (ID id) const
{
__check_knownID(*this, id);
return pTab_->queryScopeContents(id);
}
/** Add a new Placement (Object "instance") into the index.
* Usually this means effectively adding this "Object" to the Session.
* The given Placement is copied into the storage managed within the session.
* This copy within the storage is what will be "the placement of this object".
* It can be discovered as index (Session) content, re-accessed by the ID returned
* from this call and modified in the course of editing the session.
* @param newObj reference placement pointing to the MObject to be added
* @param targetScope ref to a placement already added to the index, serving as
* container "into" which the new placement will be located
* @return placement ID of the newly added Placement
* @note the newly added Placement has an identity of its own.
*/
ID
PlacementIndex::insert (PlacementMO const& newObj, ID targetScope)
{
if (!contains (targetScope))
throw error::Logic ("Specified a non-registered Placement as scope "
"while adding another Placement to the index"
,LUMIERA_ERROR_INVALID_SCOPE); ////////////////TICKET #197
return pTab_->addEntry(newObj, targetScope);
}
/** Remove and discard a Placement (Object "instance") from the index.
* Usually this means removing this Object from the session.
* @return \c true if actually removed an object.
* @throw error::State if the object to be removed is an non-empty scope
*/
bool
PlacementIndex::remove (ID id)
{
if (id == getRoot().getID())
throw error::Fatal ("Request to kill the model root.");
return pTab_->removeEntry (id);
}
void
PlacementIndex::clear()
{
pTab_->clear();
}
/* ====== PlacementIndex validity self-check ====== */
namespace { // self-check implementation helpers...
LUMIERA_ERROR_DEFINE(INDEX_CORRUPTED, "PlacementIndex corrupted");
struct SelfCheckFailure
: error::Fatal
{
SelfCheckFailure (Literal currentTest, string failure)
: error::Fatal (string("Failed test: ")+currentTest+ " : "+failure
,LUMIERA_ERROR_INDEX_CORRUPTED)
{ }
};
boost::lambda::placeholder1_type _1_;
}
/**
* PlacementIndex self-verification code
* Executes all built-in checks automatically
* on object creation.
* @throw SelfCheckFailure
*/
class PlacementIndex::Validator
{
PlacementIndex::Table& tab;
PlacementMO* elm (ID id) { return tab._element_4check (id);}
PlacementMO* sco (ID id) { return tab._scope_4check (id); }
#define VERIFY(_CHECK_, CHECK_ID, DESCRIPTION) \
if (!(_CHECK_)) \
throw SelfCheckFailure (CHECK_ID, (DESCRIPTION));
void
checkRoot (PMO* root)
{
VERIFY ( root, "(0.1) Basics", "Root element missing");
VERIFY ( root->isValid(), "(0.2) Basics", "Root Placement invalid");
VERIFY ( (*root)->isValid(), "(0.3) Basics", "Root MObject self-check failure");
}
void
checkEntry (ID id)
{
VERIFY ( tab.contains(id), "(1.1) Elements", "PlacementIndex main table corrupted");
VERIFY ( elm(id), "(1.2) Elements", "Entry doesn't hold a Placement");
VERIFY ( id==elm(id)->getID(), "(1.3) Elements", "Element stored with wrong ID"); ////////////////TICKET #197
VERIFY ( elm(id)->isValid(), "(1.4) Elements", "Index contains invalid Placement")
VERIFY ( sco(id), "(1.5) Elements", "Entry has undefined scope");
VERIFY ( sco(id)->isValid(), "(1.6) Elements", "Entry has invalid scope");
VERIFY ( tab.contains (sco(id)->getID()),
"(1.7) Elements", "Element associated with an unknown scope");
PMO* theElement = elm(id);
ID theScope (sco(id)->getID());
iterator elementsInScope = tab.queryScopeContents(theScope);
bool properlyRegistered =
true; ////////////////////////////////////////////////////////////////////////////////////////////TICKET #119 need equality on Placements
///has_any (elementsInScope, _1_ == *theElement );
VERIFY ( properlyRegistered, "(1.8) Elements", "Element isn't registered as member of the enclosing scope");
}
void
checkScope (ID id)
{
VERIFY ( tab.contains(id), "(2.1) Scopes", "Scope not registered in main table");
VERIFY ( elm(id), "(2.2) Scopes", "Scope entry doesn't hold a Placement");
VERIFY ( sco(id), "(2.3) Scopes", "Scope entry doesn't hold a containing Scope");
PMO* root = tab._root_4check();
PMO* scope = sco(id);
while (scope && scope != sco(scope->getID()))
scope = sco(scope->getID());
VERIFY ( root==scope, "(2.4) Scopes", "Found a scope not attached below root.");
}
void
checkAllocation ()
{
VERIFY ( 0 < tab.size(), "(4.1) Storage", "Implementation table is empty");
VERIFY ( 0 < tab.element_cnt(),"(4.2) Storage", "No Placement instances allocated");
VERIFY ( tab.size()==tab.scope_cnt(),
"(4.3) Storage", "Number of elements and scope entries disagree");
VERIFY ( tab.size()==tab.element_cnt(),
"(4.4) Storage", "Number of entries doesn't match number of allocated Placement instances");
}
public:
Validator (Table& indexTable)
: tab(indexTable)
{
checkRoot (tab._root_4check());
for_each ( tab._eachEntry_4check(), &Validator::checkEntry, this, _1 );
for_each ( tab._eachScope_4check(), &Validator::checkScope, this, _1 );
}
};//(End) Validator (PlacementIndex self-check implementation)
/** validity self-check, used for sanity checks and the session self-check.
* The following checks are performed (causing at least one full table scan)
* - root element exists and is valid.
* - each element
* - has a known scope
* - is registered as child of it's scope
* - can reach root from each scope
* - element count of the allocator matches table size
*/
bool
PlacementIndex::isValid() const
{
try
{
VERIFY ( pTab_, "(0) Basics" ,"Implementation tables not initialised");
Validator verify(*pTab_);
return true;
}
catch(SelfCheckFailure& failure)
{
lumiera_error();
ERROR (session, "%s", failure.what());
}
return false;
}
#undef VERIFY
}} // namespace mobject::session
Reference in a new issue View git blame Copy permalink