Atom.h

Go to the documentation of this file.

/*
 * opencog/atomspace/Atom.h
 *
 * Copyright (C) 2002-2007 Novamente LLC
 * All Rights Reserved
 *
 * Written by Thiago Maia <thiago@vettatech.com>
 *            Andre Senna <senna@vettalabs.com>
 *            Welter Silva <welter@vettalabs.com>
 *
 * 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_ATOM_H
#define _OPENCOG_ATOM_H

#include <memory>
#include <mutex>
#include <set>
#include <string>

#include <boost/signals2.hpp>

#include <opencog/util/exceptions.h>

#include <opencog/atomspace/AttentionValue.h>
#include <opencog/atomspace/ClassServer.h>
#include <opencog/atomspace/TruthValue.h>
#include <opencog/atomspace/types.h>

class AtomUTest;

namespace opencog
{

class Link;
typedef std::shared_ptr<Link> LinkPtr;
typedef std::vector<LinkPtr> IncomingSet; // use vector; see below.
typedef std::weak_ptr<Link> WinkPtr;
typedef std::set<WinkPtr, std::owner_less<WinkPtr> > WincomingSet;
typedef boost::signals2::signal<void (AtomPtr, LinkPtr)> AtomPairSignal;

// We use a std:vector instead of std::set for IncomingSet, because
// virtually all access will be either insert, or iterate, so we get
// O(1) performance. We use std::set for WincomingSet, because we want
// both good insert and good remove performance.  Note that sometimes
// incoming sets can be huge (millions of atoms).

class Atom
    : public std::enable_shared_from_this<Atom>
{
    friend class ::AtomUTest;     // Needs to call setFlag()
    friend class AtomStorage;     // Needs to set _uuid
    friend class AtomTable;       // Needs to call MarkedForRemoval()
    friend class ImportanceIndex; // Needs to call setFlag()
    friend class Handle;          // Needs to view _uuid
    friend class SavingLoading;   // Needs to set _uuid
    friend class TLB;             // Needs to view _uuid
    friend class CreateLink;      // Needs to call getAtomTable();
    friend class DeleteLink;      // Needs to call getAtomTable();

private:
    void setAtomTable(AtomTable *);

    AtomTable *getAtomTable() const { return _atomTable; }

protected:
    UUID _uuid;
    AtomTable *_atomTable;

    Type _type;

    // Byte of bitflags (each bit is a flag, see AtomSpaceDefinites.h)
    char _flags;

    TruthValuePtr _truthValue;
    AttentionValuePtr _attentionValue;

    // Lock, used to serialize changes.
    // This costs 40 bytes per atom.  Tried using a single, global lock,
    // but there seemed to be too much contention for it, so instead,
    // we are using a lock-per-atom, even though this makes the atom
    // kind-of fat.
    std::mutex _mtx;

    Atom(Type t, TruthValuePtr tv = TruthValue::DEFAULT_TV(),
            AttentionValuePtr av = AttentionValue::DEFAULT_AV())
      : _uuid(Handle::UNDEFINED.value()),
        _atomTable(NULL),
        _type(t),
        _flags(0),
        _truthValue(tv),
        _attentionValue(av)
    {}

    struct InSet
    {
        // The incoming set is not tracked by the garbage collector;
        // this is required, in order to avoid cyclic references.
        // That is, we use weak pointers here, not strong ones.
        // std::set<ptr> uses 48 bytes (per atom).  See the README file
        // in this directory for a slightly longer explanation for why
        // weak pointers are needed, and why bdgc cannot be used.
        WincomingSet _iset;
#ifdef INCOMING_SET_SIGNALS
        // Some people want to know if the incoming set has changed...
        // However, these make the atom quite fat, so this is disabled
        // just right now. If users really start clamoring, then we can
        // turn this on.
        AtomPairSignal _addAtomSignal;
        AtomPairSignal _removeAtomSignal;
#endif /* INCOMING_SET_SIGNALS */
    };
    typedef std::shared_ptr<InSet> InSetPtr;
    InSetPtr _incoming_set;
    void keep_incoming_set();
    void drop_incoming_set();

    // Insert and remove links from the incoming set.
    void insert_atom(LinkPtr);
    void remove_atom(LinkPtr);

private:
    bool isMarkedForRemoval() const;

    bool getFlag(int) const;

    void setFlag(int, bool);

    void markForRemoval();

    void unsetRemovalFlag();

    void chgVLTI(int unit);

public:

    virtual ~Atom();

    inline Type getType() const { return _type; }

    bool isType(Type t, bool subclass) const
    {
        Type at(getType());
        if (not subclass) return t == at;
        return classserver().isA(at, t);
    }

    inline Handle getHandle() {
        return Handle(shared_from_this());
    }

    AttentionValuePtr getAttentionValue();

    void setAttentionValue(AttentionValuePtr);

    AttentionValue::sti_t getSTI()
    {
        return getAttentionValue()->getSTI();
    }

    AttentionValue::lti_t getLTI()
    {
        return getAttentionValue()->getLTI();
    }

    AttentionValue::vlti_t getVLTI()
    {
        return getAttentionValue()->getVLTI();
    }

    void setSTI(AttentionValue::sti_t stiValue)
    {
        /* Make a copy */
        AttentionValuePtr old_av = getAttentionValue();
        AttentionValuePtr new_av = createAV(
            stiValue,
            old_av->getLTI(),
            old_av->getVLTI());
        setAttentionValue(new_av);
    }

    void setLTI(AttentionValue::lti_t ltiValue)
    {
        AttentionValuePtr old_av = getAttentionValue();
        AttentionValuePtr new_av = createAV(
            old_av->getSTI(),
            ltiValue,
            old_av->getVLTI());
        setAttentionValue(new_av);
    }

    void incVLTI() { chgVLTI(+1); }

    void decVLTI() { chgVLTI(-1); }

    TruthValuePtr getTruthValue();

    void setTruthValue(TruthValuePtr);

    void merge(TruthValuePtr);

    inline Handle tvmerge(TruthValuePtr tv) {
        merge(tv);
        return Handle(shared_from_this());
    }

    size_t getIncomingSetSize();

    IncomingSet getIncomingSet();

    template <typename OutputIterator> OutputIterator
    getIncomingSet(OutputIterator result)
    {
        if (NULL == _incoming_set) return result;
        std::lock_guard<std::mutex> lck(_mtx);
        // Sigh. I need to compose copy_if with transform. I could
        // do this wih boost range adaptors, but I don't feel like it.
        auto end = _incoming_set->_iset.end();
        for (auto w = _incoming_set->_iset.begin(); w != end; w++)
        {
            Handle h(w->lock());
            if (h) { *result = h; result ++; }
        }
        return result;
    }

    template<class T>
    inline bool foreach_incoming(bool (T::*cb)(const Handle&), T *data)
    {
        // We make a copy of the set, so that we don't call the
        //callback with locks held.
        IncomingSet vh(getIncomingSet());

        for (const LinkPtr& lp : vh)
            if ((data->*cb)(Handle(lp))) return true;
        return false;
    }

    template <typename OutputIterator> OutputIterator
    getIncomingSetByType(OutputIterator result,
                         Type type, bool subclass = false)
    {
        if (NULL == _incoming_set) return result;
        std::lock_guard<std::mutex> lck(_mtx);
        // Sigh. I need to compose copy_if with transform. I could
        // do this wih boost range adaptors, but I don't feel like it.
        auto end = _incoming_set->_iset.end();
        for (auto w = _incoming_set->_iset.begin(); w != end; w++)
        {
            Handle h(w->lock());
            if (h and h->isType(type, subclass)) {
                *result = h;
                result ++;
            }
        }
        return result;
    }

    IncomingSet getIncomingSetByType(Type type, bool subclass = false);

    virtual std::string toString(std::string indent = "") = 0;
    virtual std::string toShortString(std::string indent = "") = 0;

    virtual bool operator==(const Atom&) const = 0;

    virtual bool operator!=(const Atom&) const = 0;


};

} // namespace opencog

#endif // _OPENCOG_ATOM_H