cog-execute! function is a scheme function that is able to "execute" ExecutionOutputLinks and is part of
(opencog exec) module. This page attempts to explain what
cog-execute! does today. This may change over time.
A FunctionLink is defined (by definition) to be the link type that
cog-execute! knows how to execute. The result of running
cog-execute! must always be an atom (possibly the undefined atom handle, which stands for "void" or "no return value"). At this time, the result of running
cog-execute! is always placed in the same atomspace as its argument (although this is subject to change, when multiple atomspaces are involved; its a bit confusing about what the right behavior should be.)
With regards to the functions behavior on passing a non-FunctionLink, there are two valid options. We could take a hard line: concept nodes are not executable, and thus should throw an error, or we could be lenient: there are some complicated search patterns and bind-links that have to be executed, and when they run and are boiled down to something simpler, it resembles the execution of a concept node. Since we want the complicated thing to "just work", it should not be an error. But again, if the complicated thing is like "execute concept" then the complicated thing is probably buggy, and it would be easier to debug if the error was thrown, instead of being silently ignored. Presently the linient position is taken. Thus, for example:
(cog-execute! (ConceptNode "asdf"))
(cog-execute! (PlusLink (NumberNode "2") (NumberNode "3")))
The word "returns" here has two meanings: the scheme function
cog-execute! literally returns
(NumberNode "5") as it's return value, and also, as a side effect, the atom
(NumberNode "5") is placed into the atomspace. These are two different concepts of "return" that are easy to confuse and conflate with each-other. Be careful.
List of executable atom types
See Category:Executable Atom Types for a full list.