Creating a new Mind Agent in C
THIS PAGE IS OBSOLETE.
Attention: Much of the MindAgent infrastructure in the CogServer is a temporary work-around for the lack of thread-safe API's in several parts of the OpenCog embodiment code-base. The MindAgent scheduler is simply a way of allowing multiple independent blocks of code to share one single thread, and thus safely co-exist. If your block of code does not access any of the thread-unsafe API's, then you should not use the scheduler! Instead, just create as many threads as you need, and do whatever you need to do; the OS will take care of the rest.
At this time, Atoms, TruthValues, AttentionValues and the AtomSpace are all thread-safe. The TimeServer, SpaceServer, LearningServer, OAC and PAI are probably not thread-safe. Thus, you only need to use scheduling MindAgents for accessing embodiment code; otherwise, please do not use this infrastructure.
Please note that the MindAgent dispatcher code is extremely simple, and is guaranteed to suffer from various textbook ills, such as deadlocks, priority inversion, stalls. Its not pre-emptive, its not fair, its just a simple loop. Thus, MindAgents should be kept very simple, should run only for very small intervals of time, and should avoid anything that would cause them to sleep or block. If any agent blocks, they all block. No agent can run until the current agent has finished running. This is why threads are encouraged: the 'run' method should be trivial.
This quite long page describes how to set up a simple mind agent in C++ in QT and run it from the Opencog shell.
This page has the following prerequisites:
- A QT project for the Opencog source package (see Using QT Creator for details)
- Basic knowledge of the opencog.conf file (see Understanding the opencog.conf file for details)
- The ability to start the Cogserver (see Starting_cogserver for details)
- The ability to connect to the Cogserver (see Connecting to the Cogserver for details)
- The ability to monitor the cogserver.log file (see Monitoring the cogserver.log file for details)
The OpenCog sources already come with some example modules which we will be using (or copying) to create our own simple agent.
Adding new files in QT
We're going to begin with the OpenCog project in QT, check the prerequisites above if you have not set this up yet. From the folder view in QT, open the folders as shown below to find the example agents.
Select a file inside the 'modules' folder (not the folder itself) and then press Ctrl+N or select 'New file or project' from the 'File' menu at the top. In the window that opens (see below) select 'Files and Classes' in the bottom left and then pick 'C++ Class' on the right. Click 'Choose...' to confirm your selection.
On the next screen just enter a name for your class as shown below (ExampleAgent) and leave the other fields as they are. Click 'Next' to continue.
Important: If you selected the 'Modules' folder, and not a file inside it, QT may select the wrong folder in the last field on this screen. Make sure it ends with '/examples/modules' or you will run into errors later.
Also important: When you type the class name 'ExampleAgent' (capitalized) it will name your files 'exampleagent' (lower case). Be sure to change this to 'ExampleAgent' for both the source and header files as shown below.
Slightly important: By default QT will give the source file a '.cpp' extension. To stay in line with the other example agents, change this to '.cc'
The next screen is just a confirmation screen, which should look like the image below. Click 'Finish' to complete this section.
QT should then return you to the main IDE window and open the .cpp and .h files you just created. Sadly, they are not automatically shown in the folder view, which we will address in the next section.
Edit CMakeLists.txt so QT loads the new files
In order to have QT include our newly created files in the build process and the folder view, we need to edit the CMakeLists.txt file in the 'modules' folder. To open the file simply double click it.
The file should currently look like this:
Edit the file so that it looks like this:
Attentive viewers may have noticed that a bar has appeared at the top offering you to run CMake again. If you have made the changes shown above, click the 'Build now' button to do this. If you get the error '[cmake_check_build_system] Error 1', you may have misplaced one of the brackets, or typed something in the wrong case (it should be 'exampleagent', not 'ExampleAgent').
Copy the source code from the Sample Agent
The next step is to take the sample code from one of the existing examples and copy it into our exampleagent.cc and exampleagent.h files.
Let's start with the .h file. Double click the SampleAgent.h file in the folder view on the left, select all the contents and copy (Ctrl+C) them to the clipboard with Ctrl+C, or by right clicking the selected text and selecting 'Copy' from the popup menu.
Then double click the ExampleAgent.h file to open it, select all the contents, and paste (Ctrl+V) the content of the clipboard into the file.
Next press Ctrl+F to open the 'Replace text' window and enter 'Sample' in the search box and 'Example' in the replace with box. Then click the 'Replace All' button to replace all occurences in the open file exampleagent.h
After that your ExampleAgent.h file should look like this:
Then we need to do the same for the .cc files, so double click the SampleAgent.cc file in the folder view on the left and repeat the process above. This should leave your ExampleAgent.cc file looking like this.
Adding your own code in the Run() function
Feel free to add some code of your own within the Run() function at the bottom of the ExampleAgent.cc file. Since we replaced all the instances of 'Sample' with 'Example', it already has its own logging output now, which is actually sufficient for the purpose of this tutorial. Later tutorials will assume you possess the knowledge in this tutorial so we can focus on the functionality of the mind agent rather than the framework which we are setting up here.
Setting QT to build examples
Since the default build mode that QT loads for the OpenCog project is 'All', it hasn't actually been compiling the files that we have added. To make it do this we have to set up a separate build profile, which calls 'make examples' to specify we want it to build from the CMakeLists.txt in the examples folder, which references the CMakeLists.txt in the modules folder which we edited before and will build our ExampleAgent.
In the left bar of QT, select the 'Projects' button to open the screen below.
Here click the 'Add' button highlighted above and select 'Clone Selected' to copy your current build configuration to a new build configuration. Call it 'examples'.
Then click the 'Details' button under the 'Build Steps' section, and type 'examples' in the field 'additional arguments' as shown below.
Edit the Build Directory path accordingly - see example in the screenshot and before rebuilding, shutdown the opencog server.
In the left bar of QT, select the 'Edit' button to return to the previous view. You may notice that the new build configuration has been automatically selected, as shown in the bottom of the left bar of QT:
Build your new agent
You can now click the hammer icon at the bottom of the left bar in QT to see if you have done everything correctly. If so, you should see the build run all the way to 100% in the bottom panel of QT (Press Alt+4 if this panel has disappeared)
Start the Cogserver
Since we've not only built the 'examples' build configuration, but also the full OpenCog build configuration, we should be able to start the Cogserver now. See Starting_cogserver for details.
Prepare a log tracing window
Before we load our ExampleAgent, we should set up a logging window so we can see what it's doing. See Monitoring the cogserver.log file for details.
Connect to the Cogserver shell
With the Cogserver running, open another terminal window (right click the Terminal icon in your Ubuntu launcher and select 'New window', or press Ctrl+Shift+T in an opened Terminal window for a new tab) so we can connect to the Cogserver. See Connecting to the Cogserver for details.
In your Cogserver tab/windows, enter the 'help' command to see the commands available to you here. It should look something like this:
Load your ExampleAgent
The build process will have created a slightly differently named file for our ExampleAgent, so type the following command to load and start it:
If you did this correctly, the shell will respond with
Now switch back to your logging window to see what is happening. It won't be terribly interesting, but you should see the log file grow after every call to the Run() function in our ExampleAgent with each cycle of the Cogserver (every 5 seconds by default) as shown below:
And that's it! You have created your own agent, built it and loaded it in OpenCog! It doesn't do much yet but we'll be picking that up in the next tutorials. Watch this space!
You could move on to Creating a Mind Agent that does something in C now.
Is this a rhetorical question?
- No, it isn't.