AtomTable.h

Go to the documentation of this file.

/*
 * opencog/atomspace/AtomTable.h
 *
 * Copyright (C) 2008-2010 OpenCog Foundation
 * Copyright (C) 2002-2007 Novamente LLC
 * Copyright (C) 2013,2015 Linas Vepstas <linasvepstas@gmail.com>
 * All Rights Reserved
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License v3 as
 * published by the Free Software Foundation and including the exceptions
 * at http://opencog.org/wiki/Licenses
 *
 * 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 Affero General Public License
 * along with this program; if not, write to:
 * Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */

#ifndef _OPENCOG_ATOMTABLE_H
#define _OPENCOG_ATOMTABLE_H

#include <iostream>
#include <set>
#include <vector>

#include <boost/signals2.hpp>

#include <opencog/util/async_method_caller.h>
#include <opencog/util/exceptions.h>
#include <opencog/util/Logger.h>
#include <opencog/util/RandGen.h>

#include <opencog/atomspace/atom_types.h>
#include <opencog/atomspace/AttentionValue.h>
#include <opencog/atomspace/ClassServer.h>
#include <opencog/atomspace/FixedIntegerIndex.h>
#include <opencog/atomspace/ImportanceIndex.h>
#include <opencog/atomspace/IncomingIndex.h>
#include <opencog/atomspace/Link.h>
#include <opencog/atomspace/LinkIndex.h>
#include <opencog/atomspace/Node.h>
#include <opencog/atomspace/NodeIndex.h>
#include <opencog/atomspace/TruthValue.h>
#include <opencog/atomspace/TypeIndex.h>

class AtomTableUTest;

namespace opencog
{
typedef std::set<AtomPtr> AtomPtrSet;

typedef boost::signals2::signal<void (const Handle&)> AtomSignal;
typedef boost::signals2::signal<void (const AtomPtr&)> AtomPtrSignal;
typedef boost::signals2::signal<void (const Handle&,
                                      const AttentionValuePtr&,
                                      const AttentionValuePtr&)> AVCHSigl;
typedef boost::signals2::signal<void (const Handle&,
                                      const TruthValuePtr&,
                                      const TruthValuePtr&)> TVCHSigl;

class AtomSpace;

class AtomTable
{
    friend class SavingLoading;
    friend class ::AtomTableUTest;

private:

    // Single, global mutex for locking the indexes.
    // Its recursive because we need to lock twice during atom insertion
    // and removal: we need to keep the indexes stable while we search
    // them during add/remove.
    static std::recursive_mutex _mtx;

    size_t size;

    // Holds all atoms in the table.  Provides lookup between numeric
    // handle uuid and the actual atom pointer (since they are stored
    // together).  To some degree, this info is duplicated in the Node
    // and LinkIndex below; we have this here for convenience.
    //
    // This also plays a critical role for memory management: this is
    // the only index that actually holds the atom shared_ptr, and thus
    // increments the atom use count in a guaranteed fashion.  This is
    // the one true guaranteee that the atom will not be deleted while
    // it is in the atom table.
    std::unordered_set<Handle, handle_hash> _atom_set;

    TypeIndex typeIndex;
    NodeIndex nodeIndex;
    LinkIndex linkIndex;
    ImportanceIndex importanceIndex;

    async_caller<AtomTable, AtomPtr> _index_queue;
    void put_atom_into_index(AtomPtr&);

    boost::signals2::connection addedTypeConnection;

    void typeAdded(Type);

    AtomSignal _addAtomSignal;
    AtomPtrSignal _removeAtomSignal;

    TVCHSigl _TVChangedSignal;

    AVCHSigl _AVChangedSignal;

    // JUST FOR TESTS:
    bool isCleared() const;

    AtomTable* _environ;
    bool inEnviron(AtomPtr);
    UUID _uuid;

    // The AtomSpace that is holding us (if any). Needed for DeleteLink operation
    AtomSpace* _as;
    AtomTable& operator=(const AtomTable&);
    AtomTable(const AtomTable&);

public:

    AtomTable(AtomTable* parent = NULL, AtomSpace* holder = NULL);
    ~AtomTable();
    UUID get_uuid(void) { return _uuid; }
    AtomSpace* getAtomSpace(void) { return _as; }

    size_t getSize() const;
    size_t getNumNodes() const;
    size_t getNumLinks() const;
    size_t getNumAtomsOfType(Type type, bool subclass = true) const;

    Handle getHandle(Type, std::string) const;
    Handle getHandle(const NodePtr&) const;

    Handle getHandle(Type, const HandleSeq&) const;
    Handle getHandle(const LinkPtr&) const;
    Handle getHandle(const AtomPtr&) const;
    Handle getHandle(Handle&) const;

    static AtomPtr factory(Type atom_type, AtomPtr atom);

public:
    template <typename OutputIterator> OutputIterator
    getHandlesByType(OutputIterator result,
                     Type type,
                     bool subclass = false,
                     bool parent = true) const
    {
        std::lock_guard<std::recursive_mutex> lck(_mtx);
        if (parent && _environ)
            _environ->getHandlesByType(result, type, subclass, parent);
        return std::copy(typeIndex.begin(type, subclass),
                         typeIndex.end(),
                         result);
    }

    template <typename Function> void
    foreachHandleByType(Function func,
                        Type type,
                        bool subclass = false,
                        bool parent = true) const
    {
        std::lock_guard<std::recursive_mutex> lck(_mtx);
        if (parent && _environ)
            _environ->foreachHandleByType(func, type, subclass);
        std::for_each(typeIndex.begin(type, subclass),
                      typeIndex.end(),
             [&](Handle h)->void {
                  (func)(h);
             });
    }

    UnorderedHandleSet getHandlesByAV(AttentionValue::sti_t lowerBound,
                              AttentionValue::sti_t upperBound = AttentionValue::MAXSTI) const
    {
        std::lock_guard<std::recursive_mutex> lck(_mtx);
        return importanceIndex.getHandleSet(this, lowerBound, upperBound);
    }

    void updateImportanceIndex(AtomPtr a, int bin)
    {
        if (a->_atomTable != this) return;
        std::lock_guard<std::recursive_mutex> lck(_mtx);
        importanceIndex.updateImportance(a.operator->(), bin);
    }

    Handle add(AtomPtr, bool async);

    void barrier(void);

    bool holds(Handle& h) const {
        return (NULL != h) and h->getAtomTable() == this;
    }

    inline NodePtr getNode(Handle& h) const {
        h = getHandle(h); // force resolution of uuid into atom pointer.
        return NodeCast(h);
    }

    inline LinkPtr getLink(Handle& h) const {
        h = getHandle(h); // force resolution of uuid into atom pointer.
        return LinkCast(h);
    }

    AtomPtrSet extract(Handle& handle, bool recursive = true);

    Handle getRandom(RandGen* rng) const;

    AtomSignal& addAtomSignal() { return _addAtomSignal; }
    AtomPtrSignal& removeAtomSignal() { return _removeAtomSignal; }

    AVCHSigl& AVChangedSignal() { return _AVChangedSignal; }

    TVCHSigl& TVChangedSignal() { return _TVChangedSignal; }
};

} //namespace opencog

#endif // _OPENCOG_ATOMTABLE_H