AtomSpace CogStorage Client

The code in this git repo allows an AtomSpace to communicate with other AtomSpaces by having them all connect to a common CogServer. The CogServer itself also provides an AtomSpace, which all clients interact with, in common. In ASCII-art:

 +-------------+
 |  CogServer  |
 |    with     |  <-----internet------> Remote AtomSpace A
 |  AtomSpace  |  <---+
 +-------------+      |
                      +-- internet ---> Remote AtomSpace B

Here, AtomSpace A can load/store Atoms (and Values) to the CogServer, as can AtomSpace B, and so these two can share AtomSpace contents however desired.

This provides a simple, straight-forward backend for networking together multiple AtomSpaces so that they can share data. This backend, together with the file-based (RocksDB-based) backend at atomspace-rocks is meant to provide a building-block out of which more complex distributed and/or decentralized AtomSpaces can be built.

This really is decentralized: you can talk to multiple servers at once. There is no particular limit, other than that of bandwidth, response-time, etc. In ASCII-art:

 +-----------+
 |           |  <---internet--> My AtomSpace
 |  Server A |                      ^  ^
 |           |        +-------------+  |
 +-----------+        v                v
                 +----------+   +-----------+
                 |          |   |           |
                 | Server B |   |  Server C |
                 |          |   |           |
                 +----------+   +-----------+

Here's yet another diagram, reflecting the actual usage in the LinkGrammar AtomSpace dictionary. Stacked boxes represent shared-libraries, with shared-library calls going downwards. Note that AtomSpaces start out empty, so the data has to come "from somewhere". In this case, the data comes from another AtomSpace, running remotely (in the demo, its in a Docker container). That AtomSpace in turn loads its data from a RocksStorageNode, which uses RocksDB to work with the local disk drive. The network connection is provided by a CogServer to CogStorageNode pairing.

                                            +----------------+
                                            |  Link Grammar  |
                                            |    parser      |
                                            +----------------+
                                            |   AtomSpace    |
    +-------------+                         +----------------+
    |             |                         |                |
    |  Cogserver  | <<==== Internet ====>>  | CogStorageNode |
    |             |                         |                |
    +-------------+                         +----------------+
    |  AtomSpace  |
    +-------------+
    |    Rocks    |
    | StorageNode |
    +-------------+
    |   RocksDB   |
    +-------------+
    | disk drive  |
    +-------------+

Complex storage network fabrics can be created with the ProxyNode. Basic proxies exist for mirroring, read load-balancing, write buffering, etc.

Example Usage

Well, see the examples directory for details. But, in brief:

• Start the CogServer at "example.com":

$ guile
scheme@(guile-user)> (use-modules (opencog))
scheme@(guile-user)> (use-modules (opencog cogserver))
scheme@(guile-user)> (start-cogserver)
$1 = "Started CogServer"
scheme@(guile-user)> Listening on port 17001

Then create some atoms (if desired)

• On the client machine:

$ guile
scheme@(guile-user)> (use-modules (opencog))
scheme@(guile-user)> (use-modules (opencog persist))
scheme@(guile-user)> (use-modules (opencog persist-cog))
scheme@(guile-user)> (cogserver-open "cog://example.com/")
scheme@(guile-user)> (load-atomspace)

That's it! You've copied the entire AtomSpace from the server to the client! Of course, copying everything is generally a bad idea (well, for example, its slow, when the atomspace is large). More granular load and store is possible; see the examples directory for details.

Status

This is Version 1.2.0. All 27 (13+13+1) unit tests consistently pass. For a general overview, see the wiki documentation for the StorageNode and CogStorageNode.

Changes since January 2025:

• Barriers are now implemented correctly and work reliably. Barriers are fences that ensure all operations that come before are completed, before any operations that come after are started.
• Operations that don't need a reply (e.g. *-store-atom-*) no longer wait for a confirmation reply to be received. This increases throughput significantly.
• Busy-wait spinloops have been replaced by c++-20 std::atomic::wait() which means idle time on congested queues is significantly reduced.
• Cogserver shutdown in unit tests has been fixed. For testing, the unit tests start a cogserver, do TCP/IP I/O to it, and then shut down the cogserver. These tests had been plagued by shutdown issues, where the tests pass but then the cogserver would hang or crash on shutdown. These issues have all been fixed. You can now start and stop cogservers very rapidly, on demand, in a reliable fashion.
• A random assortment of bug fixes and changes, driving by changes in the core AtomSpace.

There is one missing feature, but no one uses it (yet): support for multiple AtomSpaces (aka frames) is missing. Work on adding this was started but is low priority. One unit test works. See the cog-simple directory.

Build

Prerequisites: of course the AtomSpace is needed: https://github.com/opencog/atomspace but so is the base StorageNode API, at https://github.com/opencog/atomspace-storage

Build as below. Note parallel testing works!

mkdir build
cd build
make -j
make -j check ARGS=-j

Design

There are actually two implementations in this repo. One that is "simple", and one that is multi-threaded and concurrent (and so should have a higher throughput). Both "do the same thing", functionally, but differ in network usage, concurrency, etc.

The Simple Backend

This can be found in the opencog/persist/cog-simple directory. The grand-total size of this implementation is less than 500 lines of code. Seriously! This is really a very simple system! Take a look at CogSimpleStorage.h first, and then take a look at CogSimpleIO.cc which does all of the data transfer to/from the cogserver. Finally, CogSimpleStorage.cc provides init and socket I/O.

This backend can be accessed via:

scheme> (use-modules (opencog persist-cog-simple))
scheme> (define cssn (CogSimpleStorageNode "cog://example.com/"))
scheme> (cog-open cssn)

The Production Backend

This backend opens four sockets to the cogserver, and handles requests asynchronously. In other words, requests might be handled out-of-order. If there is some critical code segment that can't tolerate this, use the (barrier) call. It will flush the network buffers, and force a serialization barrier at the remote end. The (barrier) is a 'fence' and not a synchronization checkpoint: it ensures that all reads/writes before the barrier are completed before any that come after are started.

Usage is much like before:

scheme> (use-modules (opencog persist-cog))
scheme> (define csn (CogStorageNode "cog://example.com/"))
scheme> (cog-open csn)

URL's

Supported URL's include:

• cog://example.com/ -- standard internet hostname
• cog://1.2.3.4/ -- standard dotted IPv4 address
• cog://example.com:17001 -- specify the port of the cogserver.