AtomSpace.h

Go to the documentation of this file.

/*
 * opencog/atomspace/AtomSpace.h
 *
 * Copyright (C) 2008-2011 OpenCog Foundation
 * Copyright (C) 2002-2007 Novamente LLC
 * Copyright (C) 2015 Linas Vepstas
 * 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_ATOMSPACE_H
#define _OPENCOG_ATOMSPACE_H

#include <algorithm>
#include <list>
#include <set>
#include <vector>

#include <opencog/atomspace/AtomTable.h>
#include <opencog/atomspace/AttentionBank.h>
#include <opencog/atomspace/AttentionValue.h>
#include <opencog/atomspace/BackingStore.h>
#include <opencog/atomspace/ClassServer.h>
#include <opencog/atomspace/TruthValue.h>
#include <opencog/util/exceptions.h>

namespace opencog
{
class AtomSpace
{
    friend class SavingLoading;
    friend class SQLPersistSCM;
    friend class ::AtomTableUTest;

    AtomSpace& operator=(const AtomSpace&);
    AtomSpace(const AtomSpace&);

    AtomTable atomTable;
    AttentionBank bank;
    BackingStore *backing_store;

    AtomTable& get_atomtable(void) { return atomTable; }
protected:

    void registerBackingStore(BackingStore *);
    void unregisterBackingStore(BackingStore *);

public:
    AtomSpace(AtomSpace* parent = NULL);
    ~AtomSpace();

    inline int get_size() const { return atomTable.getSize(); }
    inline int get_num_nodes() const { return atomTable.getNumNodes(); }
    inline int get_num_links() const { return atomTable.getNumLinks(); }
    inline int get_num_atoms_of_type(Type type, bool subclass = false) const
        { return atomTable.getNumAtomsOfType(type, subclass); }

    void clear();

    Handle add_atom(AtomPtr atom, bool async=false);

    Handle add_node(Type t, const std::string& name = "",
                    bool async = false);

    Handle add_link(Type t, const HandleSeq& outgoing, bool async = false);

    inline Handle add_link(Type t, Handle h)
    {
        return add_link(t, HandleSeq({h}));
    }

    inline Handle add_link(Type t, Handle ha, Handle hb)
    {
        return add_link(t, {ha, hb});
    }

    inline Handle add_link(Type t, Handle ha, Handle hb, Handle hc)
    {
        return add_link(t, {ha, hb, hc});
    }

    inline Handle add_link(Type t, Handle ha, Handle hb, Handle hc, Handle hd)
    {
        return add_link(t, {ha, hb, hc, hd});
    }

    inline Handle add_link(Type t, Handle ha, Handle hb, Handle hc,
                           Handle hd, Handle he)
    {
        return add_link(t, {ha, hb, hc, hd, he});
    }

    inline Handle add_link(Type t, Handle ha, Handle hb, Handle hc,
                           Handle hd, Handle he, Handle hf)
    {
        return add_link(t, {ha, hb, hc, hd, he, hf});
    }

    inline Handle add_link(Type t, Handle ha, Handle hb, Handle hc,
                           Handle hd, Handle he, Handle hf, Handle hg)
    {
        return add_link(t, {ha, hb, hc, hd, he, hf, hg});
    }

    inline Handle add_link(Type t, Handle ha, Handle hb, Handle hc,
                           Handle hd, Handle he, Handle hf, Handle hg,
                           Handle hh)
    {
        return add_link(t, {ha, hb, hc, hd, he, hf, hg, hh});
    }

    inline Handle add_link(Type t, Handle ha, Handle hb, Handle hc,
                           Handle hd, Handle he, Handle hf, Handle hg,
                           Handle hh, Handle hi)
    {
        return add_link(t, {ha, hb, hc, hd, he, hf, hg, hh, hi});
    }

    void barrier(void) {
        atomTable.barrier();
        if (backing_store) backing_store->barrier();
    }

    Handle fetch_atom(Handle h);

    Handle get_atom(Handle);

    void fetch_all_atoms_of_type(Type t) {
        if (NULL == backing_store)
            throw RuntimeException(TRACE_INFO, "No backing store");
        backing_store->loadType(atomTable, t);
    }


    Handle fetch_incoming_set(Handle, bool);

    void store_atom(Handle h);

    bool purge_atom(Handle h, bool recursive = false) {
        return 0 < atomTable.extract(h, recursive).size();
    }

    bool remove_atom(Handle h, bool recursive = false);

    Handle get_node(Type t, const std::string& name = "");
    inline Handle get_handle(Type t, const std::string& str) {
        return get_node(t, str);
    }

    Handle get_link(Type t, const HandleSeq& outgoing);
    Handle get_link(Type t, Handle ha) {
        return get_link(t, HandleSeq({ha}));
    }
    Handle get_link(Type t, Handle ha, Handle hb) {
        return get_link(t, {ha, hb});
    }
    Handle get_link(Type t, Handle ha, Handle hb, Handle hc) {
        return get_link(t, {ha, hb, hc});
    }
    Handle get_link(Type t, Handle ha, Handle hb, Handle hc, Handle hd) {
        return get_link(t, {ha, hb, hc, hd});
    }
    Handle get_handle(Type t, const HandleSeq& outgoing) {
        return get_link(t, outgoing);
    }
    Handle get_handle(Type t, const Handle& ha) {
        return get_handle(t, HandleSeq({ha}));
    }
    Handle get_handle(Type t, const Handle& ha, const Handle& hb) {
        return get_handle(t, HandleSeq({ha, hb}));
    }

    bool is_valid_handle(Handle h) const {
        // The h->get_handle() maneuver below is a trick to get at the
        // UUID of the actual atom, rather than the cached UUID in the
        // handle. Technically, this is not quite right, since, in
        // principle, a handle could have a valid UUID, but the atom
        // pointer is null, because the atom is on disk, in a database,
        // is on a remote server, or has been purged from RAM.  But we
        // have no way of knowing that the situation really is, so it
        // seems like the only thing that can be done here is to resolve
        // the pointer (i.e. make it point to an acutal atom, in RAM,
        // and then check the actual UUID in the atom.
        //
        // The actual resolution is done with the (NULL != h) check,
        // which causes h.operator!=() to run, which fixes up the atom
        // pointer, as needed.
        //
        return (NULL != h) and (h->getHandle() != Handle::UNDEFINED);
    }

    void get_handles_by_type(HandleSeq& appendToHandles,
                             Type type,
                             bool subclass = false) const
    {
        // Get the initial size of the handles vector.
        size_t initial_size = appendToHandles.size();

        // Determine the number of atoms we'll be adding.
        size_t size_of_append = atomTable.getNumAtomsOfType(type, subclass);

        // Now reserve size for the addition. This is faster for large
        // append iterations since appends to the list won't require new
        // allocations and copies whenever the allocated size is exceeded.
        appendToHandles.reserve(initial_size + size_of_append);

        // Now defer to the output iterator call, eating the return.
        get_handles_by_type(back_inserter(appendToHandles), type, subclass);
    }

    template <typename OutputIterator> OutputIterator
    get_handles_by_type(OutputIterator result,
                        Type type,
                        bool subclass = false) const
    {
        return atomTable.getHandlesByType(result, type, subclass);
    }

    /* ----------------------------------------------------------- */
    /* The foreach routines offer an alternative interface
     * to the getHandleSet API.
     */
    template<class T>
    inline bool foreach_handle_of_type(Type atype,
                                       bool (T::*cb)(const Handle&), T *data,
                                       bool subclass = false)
    {
        // First we extract, then we loop. This is to avoid holding
        // the lock for too long. (because we don't know how long
        // the callback will take.)
        std::list<Handle> handle_set;
        // The intended signatue is
        // getHandleSet(OutputIterator result, Type type, bool subclass)
        get_handles_by_type(back_inserter(handle_set), atype, subclass);

        // Loop over all handles in the handle set.
        std::list<Handle>::iterator i = handle_set.begin();
        std::list<Handle>::iterator iend = handle_set.end();
        for (; i != iend; ++i) {
            bool rc = (data->*cb)(*i);
            if (rc) return rc;
        }
        return false;
    }

    /* ----------------------------------------------------------- */
    /* Attentional Focus stuff */

    float get_normalised_STI(Handle h, bool average=true, bool clip=false) const {
        return bank.getNormalisedSTI(h->getAttentionValue(), average, clip);
    }

    float get_normalised_zero_to_one_STI(Handle h, bool average=true, bool clip=false) const {
        return bank.getNormalisedZeroToOneSTI(h->getAttentionValue(), average, clip);
    }

    template <typename OutputIterator> OutputIterator
    get_handles_by_AV(OutputIterator result,
                      AttentionValue::sti_t lowerBound,
                      AttentionValue::sti_t upperBound = AttentionValue::MAXSTI) const
    {
        UnorderedHandleSet hs = atomTable.getHandlesByAV(lowerBound, upperBound);
        return std::copy(hs.begin(), hs.end(), result);
    }

    template <typename OutputIterator> OutputIterator
    get_handle_set_in_attentional_focus(OutputIterator result) const
    {
        return get_handles_by_AV(result, get_attentional_focus_boundary(),
                                 AttentionValue::AttentionValue::MAXSTI);
    }

    AttentionValue::sti_t get_attentional_focus_boundary() const {
        return bank.getAttentionalFocusBoundary();
    }

    AttentionValue::sti_t set_attentional_focus_boundary(
        AttentionValue::sti_t s) {
        return bank.setAttentionalFocusBoundary(s);
    }

    AttentionValue::sti_t get_max_STI(bool average=true) const
    { return bank.getMaxSTI(average); }

    AttentionValue::sti_t get_min_STI(bool average=true) const
    { return bank.getMinSTI(average); }

    void update_min_STI(AttentionValue::sti_t m) { bank.updateMinSTI(m); }

    void update_max_STI(AttentionValue::sti_t m) { bank.updateMaxSTI(m); }
    void update_STI_funds(AttentionValue::sti_t m) { bank.updateSTIFunds(m); }
    void update_LTI_funds(AttentionValue::lti_t m) { bank.updateLTIFunds(m); }
    long get_STI_funds() const { return bank.getSTIFunds(); }
    long get_LTI_funds() const { return bank.getLTIFunds(); }

    /* ----------------------------------------------------------- */
    // ---- Signals

    boost::signals2::connection addAtomSignal(const AtomSignal::slot_type& function)
    {
        return atomTable.addAtomSignal().connect(function);
    }
    boost::signals2::connection removeAtomSignal(const AtomPtrSignal::slot_type& function)
    {
        return atomTable.removeAtomSignal().connect(function);
    }
    boost::signals2::connection AVChangedSignal(const AVCHSigl::slot_type& function)
    {
        return atomTable.AVChangedSignal().connect(function);
    }
    boost::signals2::connection TVChangedSignal(const TVCHSigl::slot_type& function)
    {
        return atomTable.TVChangedSignal().connect(function);
    }
    boost::signals2::connection AddAFSignal(const AVCHSigl::slot_type& function)
    {
        return bank.AddAFSignal().connect(function);
    }
    boost::signals2::connection RemoveAFSignal(const AVCHSigl::slot_type& function)
    {
        return bank.RemoveAFSignal().connect(function);
    }

    /* ----------------------------------------------------------- */
    /* Deprecated and obsolete code */

    template <typename OutputIterator> OutputIterator
    get_handles_by_name(OutputIterator result,
                        const std::string& name,
                        Type type = NODE,
                        bool subclass = true)
    {
        if (name.c_str()[0] == 0)
            return get_handles_by_type(result, type, subclass);

        if (false == subclass) {
            Handle h(get_handle(type, name));
            if (h) *(result++) = h;
            return result;
        }

        classserver().foreachRecursive(
            [&](Type t)->void {
                Handle h(get_handle(t, name));
                if (h) *(result++) = h; }, type);

        return result;
    }

    template <typename OutputIterator> OutputIterator
    get_incoming_set_by_type(OutputIterator result,
                             Handle handle,
                             Type type,
                             bool subclass) const
    {
        return handle->getIncomingSetByType(result, type, subclass);
    }

    HandleSeq get_incoming(Handle h) const {
        HandleSeq hs;
        h->getIncomingSet(back_inserter(hs));
        return hs;
    }

    bool is_node(Handle h) const { return NodeCast(h) != NULL; }
    bool is_link(Handle h) const { return LinkCast(h) != NULL; }

    std::string atom_as_string(Handle h, bool terse = true) const {
        if (terse) return h->toShortString();
        return h->toString();
    }

    const std::string& get_name(Handle h) const {
        static std::string noname;
        NodePtr nnn(NodeCast(h));
        if (nnn) return nnn->getName();
        return noname;
    }

    void set_STI(Handle h, AttentionValue::sti_t stiValue) const {
        h->setSTI(stiValue);
    }

    void set_LTI(Handle h, AttentionValue::lti_t ltiValue) const {
        h->setLTI(ltiValue);
    }

    void inc_VLTI(Handle h) const { h->incVLTI(); }

    void dec_VLTI(Handle h) const { h->decVLTI(); }

    AttentionValue::sti_t get_STI(Handle h) const {
        return h->getAttentionValue()->getSTI();
    }

    AttentionValue::lti_t get_LTI(Handle h) const {
        return h->getAttentionValue()->getLTI();
    }

    AttentionValue::vlti_t get_VLTI(Handle h) const {
        return h->getAttentionValue()->getVLTI();
    }

    const HandleSeq& get_outgoing(Handle h) const {
        static HandleSeq empty;
        LinkPtr lll(LinkCast(h));
        if (lll) return lll->getOutgoingSet();
        return empty;
    }

    Handle get_outgoing(Handle h, Arity idx) const {
        LinkPtr lll = LinkCast(h);
        if (lll) return lll->getOutgoingAtom(idx);
        return Handle::UNDEFINED;
    }

    Arity get_arity(Handle h) const {
        LinkPtr lll(LinkCast(h));
        if (lll) return lll->getArity();
        return 0;
    }

    bool is_source(Handle source, Handle link) const
    {
        LinkPtr l(LinkCast(link));
        if (l) return l->isSource(source);
        return false;
    }

    AttentionValuePtr get_AV(Handle h) const {
        return h->getAttentionValue();
    }

    void set_AV(Handle h, AttentionValuePtr av) const {
        h->setAttentionValue(av);
    }

    Type get_type(Handle h) const {
        return h->getType();
    }

    TruthValuePtr get_TV(Handle h) const
    {
        return h->getTruthValue();
    }

    strength_t get_mean(Handle h) const {
        return h->getTruthValue()->getMean();
    }

    confidence_t get_confidence(Handle h) const {
        return h->getTruthValue()->getConfidence();
    }

    void set_TV(Handle h, TruthValuePtr tv) const {
        h->setTruthValue(tv);
    }
};

} // namespace opencog

namespace std {

ostream& operator<<(ostream&, const opencog::AtomSpace&);

} //namespace std

#endif // _OPENCOG_ATOMSPACE_H