From OpenCog
Jump to: navigation, search

In OpenCog, a Handle is a reference a particular Atom. In C++ code, a Handle is a smart pointer pointing to the actual C++ atom that it references; thus, all Atom methods can be called by using the operator-> on the Handle.

Implementation details

The below describes how Handles actually work in the current atomspace. User's don't need to know any of this to use handles; this info is for maintainers.

In the current implementation, handles are 'smart pointers'. When you create a handle, the use count on some atom increases. When you destroy a handle the use-count decreases. If the use count on an atom goes to zero, the atom is deleted. When you assign, the use-count on the old atom decreases, the use-count on the new atom increases. If you assign an atom to itself, nothing happens.

The handle is a struct, with one members: the actual pointer to the actual atom. You can view these explicitly. so:

Handle h;
Atom* ap = h.operator->();
logger().info("The pointer is %p\n", ap);

A handle with a null pointer is the 'invalid handle'.


Handles use the C++ AtomPtr class to perform reference counting and memory management. Recall that reference counting is mathematically "dual" to garbage collection. Here, "dual" in the sense of category theory, a reversal of arrows. See David F. Bacon, Perry Cheng, V.T. Rajan, "A Unified Theory of Garbage Collection" OOPSLA’04, Oct. 24-28, 2004.

AtomPtr itself is a std::shared_ptr<Atom> and a shared_pointer is a class. so AtomPtr::get() returns the actual pointer, but AtomPtr()::use_count() returns the use count. The use count should be between 1 and about 20, maybe even a little more if its a popular atom. It shouldn't be zero, negative, or 3 billion. See std::shared_pointer for details. For example:

Handle h = ...;
long int cnt = h.AtomPtr().use_count();
printf("use count is %d\n", cnt);

All of this works corrently in a multi-threaded, multi-atomspace environment. The AtomSpaceAyncUTest creates a few dozen threads and bangs on various atomspaces with various usage scenarios to test this stuff.

Note, however, that the atomic thread-safety of shared-pointers is subtle. See boost documentation and the cppwisdom "shared_ptr is almost thread safe" article. It affects how shared pointers are used for TruthValues and AttentionValues, or any kind of mutable data, although Handles are not affected, because Handles are not mutable.


For historical reasons, Handles also contain a copy of a 64-bit integer, the UUID. Work is underway to remove this, see github issue #795 and github issue #796

The UUID's are used in persistent storage, and in the REST API, to uniquely identify the atom being worked with. The long-term plan is to have these subsystems assign their own, private UUID's, as needed, rather than relying on the centralized UUID. This change will reduce the size of atoms in the atomspace; it will also increase the power and flexibility of the various subsystems, as they will have greater control over how UUID's get used.

Multiple AtomSpaces

There still are a few buggy/unhandled areas, having to do with out-of-order atom space deletion. If you delete an atomspace that has children, weird stuff will probably happen, culminating in a crash.