#include "soarkernel.h"
#include "callback.h"
#include "soarapi_datatypes.h"
Go to the source code of this file.
Modifying the Agents Parameters | |
void | soar_cSetSystemParameter (int param, long value) |
soar_cSetSystemParameter -- Set a system parameter for the current agent. More... | |
void | soar_cInitializeDCHistogram (int size, int freq) |
soar_cInitializeDCHistogram -- Prepare an array of time structures which will be used to store the time executing a sets of decision cycles. More... | |
void | soar_cInitializeKTHistogram (int size) |
soar_cInitializeKTHistogram -- Prepare an array of time structures which will be used to store the kernel time executing a each successive decision cycle. More... | |
void | soar_cSetChunkNameLong (bool truly) |
soar_cSetChunkNameLong -- Set long or short chunk names according to the specified parameter. More... | |
int | soar_cSetChunkNameCount (long count) |
soar_cSetChunkNameCount -- Set the chunk count. More... | |
int | soar_cSetChunkNamePrefix (char *prefix) |
soar_cSetChunkNamePrefix -- Set the chunk name prefix. More... | |
void | soar_cSetLearning (enum soar_apiLearningSetting setting) |
soar_cSetLearning -- Adjust the learning settings. More... | |
int | soar_cSetOperand2 (bool turnOn) |
soar_cSetOperand2 -- Toggles from Soar7 to Soar8 execution mode. More... | |
void | soar_cSetWaitSNC (bool wait) |
soar_cSetWaitSNC -- Determine whether Soar should generate explict state-no-change impasses. More... | |
int | soar_cMultiAttributes (char *attr, int value) |
soar_cMultiAttributes -- Modify the multi-attributes setting. More... | |
int | soar_cAttributePreferencesMode (int mode) |
soar_cAttributePreferencesMode -- Determine how preferences for non-context slots should be handled. More... | |
Interaction With Soar | |
This section deals with four main areas of interaction
| |
void | soar_cInitializeSoar (void) |
soar_cInitializeSoar -- Initialize Soar for the very first time. More... | |
int | soar_cReInitSoar (void) |
soar_cReInitSoar -- Reset Soar (and agents) to the initial state. More... | |
void | soar_cCreateAgent (char *agent_name) |
soar_cCreateAgent -- Create a new soar agent with the specified name. More... | |
int | soar_cRun (long n, bool all, enum go_type_enum type, enum soar_apiSlotType slot) |
soar_cRun -- Run the current agent, or all agents for a specified period ... More... | |
void | soar_cStopAllAgents (void) |
soar_cStopAllAgents -- Stops all agents. | |
void | soar_cStopCurrentAgent (char *reason) |
soar_cStopCurrentAgent -- Stops the current agent. More... | |
int | soar_cDestroyAgentByName (char *name) |
soar_cDestroyAgentByName -- Destroy an agent, given its name. More... | |
int | soar_cDestroyAllAgentsWithName (char *name) |
soar_cDestroyAllAgentsWithName -- Destroy a set of agents, given a name. More... | |
void | soar_cDestroyAgentByAddress (psoar_agent delete_agent) |
soar_cDestroyAgentByAddress -- Destroy an agent, given a pointer to it. More... | |
int | soar_cDestroyAgentById (int agent_id) |
soar_cDestroyAgentById -- Destroy an agent, given its unique id. More... | |
void | soar_cQuit (void) |
soar_cQuit -- Quit Soar. More... | |
Modifying Agent Memory | |
This section deals with two areas of the agent:
| |
int | soar_cLoadReteNet (char *filename) |
soar_cLoadReteNet -- Load a Rete Network into the agent from a specified file. More... | |
int | soar_cSaveReteNet (char *filename) |
soar_cSaveReteNet -- Save a Rete Network from the agent into a specified file. More... | |
unsigned long | soar_cAddWme (char *szId, char *szAttr, char *szValue, bool accept, psoar_wme *new_wme) |
soar_cAddWme -- Add a working memory element to the current agent's working memory. More... | |
int | soar_cRemoveWmeUsingTimetag (int num) |
soar_cRemoveWmeUsingTimetag -- Remove a working memory element, given its timetag. More... | |
int | soar_cRemoveWme (psoar_wme wme) |
soar_cRemoveWme -- Remove a working memory element. More... | |
void | soar_cExciseAllProductions (void) |
soar_cExciseAllProductions -- Remove all productions from the agents memory and ReInitialize the agent. More... | |
void | soar_cExciseAllTaskProductions (void) |
soar_cExciseAllTaskProductions -- Remove all but default productions from the agents memory and ReInitialize the agent. More... | |
void | soar_cExciseAllProductionsOfType (byte type) |
soar_cExciseAllProductionsOfType -- Remove all productions of a specific type from the agents memory and ReInitialize the agent. More... | |
int | soar_cExciseProductionByName (char *name) |
soar_cExciseProductionByName -- Remove the production with the specified name. More... | |
Callbacks | |
void | soar_cAddInputFunction (agent *a, soar_callback_fn f, soar_callback_data cb_data, soar_callback_free_fn free_fn, char *name) |
soar_cAddInputFunction -- Adds an input function to the specified agent. More... | |
void | soar_cRemoveInputFunction (agent *a, char *name) |
soar_cRemoveInputFunction -- Remove an input function with the specified name. More... | |
void | soar_cAddOutputFunction (agent *a, soar_callback_fn f, soar_callback_data cb_data, soar_callback_free_fn free_fn, char *output_link_name) |
soar_cAddOutputFunction -- Similar to soar_cAddInputFunction(), but adds a function which is called durnig each output phase. More... | |
void | soar_cRemoveOutputFunction (agent *a, char *name) |
soar_cRemoveOutputFunction -- Remove an output function with the specified name. More... | |
void | soar_cPushCallback (soar_callback_agent a, SOAR_CALLBACK_TYPE type, soar_callback_fn fn, soar_callback_data data, soar_callback_free_fn free_fn) |
soar_cPushCallback -- Push a callback onto the specified callback stack. More... | |
void | soar_cAddCallback (soar_callback_agent a, SOAR_CALLBACK_TYPE type, soar_callback_fn fn, soar_callback_data data, soar_callback_free_fn free_fn, soar_callback_id id) |
soar_cAddCallback -- Add a callback onto the specified callback stack. More... | |
void | soar_cPopCallback (soar_callback_agent a, SOAR_CALLBACK_TYPE type) |
soar_cPopCallback -- Pops off the last callback to be added to the specified callback stack. More... | |
void | soar_cRemoveCallback (soar_callback_agent a, SOAR_CALLBACK_TYPE type, soar_callback_id id) |
soar_cRemoveCallback -- Remove the callback from the specified callback stack which has the specified id. More... | |
void | soar_cAddGlobalCallback (SOAR_GLOBAL_CALLBACK_TYPE type, soar_callback_fn fn, soar_callback_data data, soar_callback_free_fn free_fn, soar_callback_id id) |
soar_cAddGlobalCallback -- Add a callback onto the specified global callback stack. More... | |
void | soar_cRemoveGlobalCallback (SOAR_GLOBAL_CALLBACK_TYPE type, soar_callback_id id) |
soar_cRemoveGlobalCallback -- Remove a callback onto the specified /global/ callback stack. More... | |
void | soar_cListAllCallbacks (soar_callback_agent a, bool monitorable_only) |
soar_cListAllCallbacks -- List the callbacks registered to the agent. More... | |
void | soar_cListAllCallbacksForEvent (soar_callback_agent agent, SOAR_CALLBACK_TYPE type) |
soar_cListAllCallbacksForEvent -- List the all callbacks of a specific type registered to the agent. More... | |
void | soar_cRemoveAllMonitorableCallbacks (soar_callback_agent agent) |
soar_cRemoveAllMonitorableCallbacks -- Remove all of the callbacks (other than PRINT or LOG callbacks) registered to the specified agent. More... | |
void | soar_cRemoveAllCallbacksForEvent (soar_callback_agent agent, SOAR_CALLBACK_TYPE type) |
soar_cRemoveAllCallbacksForEvent -- Remove all of the callbacks of a specified type which have been registered to the specified agent. More... | |
void | soar_cTestAllMonitorableCallbacks (soar_callback_agent the_agent) |
soar_cTestAllMonitorableCallbacks -- Register a simple print function on all the monitorable callback stacks (all but PRINT and LOG). More... | |
SOAR_CALLBACK_TYPE | soar_cCallbackNameToEnum (char *name, bool monitor_only) |
soar_cCallbackNameToEnum -- Return the enumerated type (the callback type) given an event name. More... | |
Etc | |
Miscellanous controls, including:
| |
char* | soar_cGetWmeId (psoar_wme w, char *buff) |
soar_cGetWmeId -- An accessor function for a psoar_wme. More... | |
char* | soar_cGetWmeAttr (psoar_wme w, char *buff) |
soar_cGetWmeAttr -- An accessor function for a psoar_wme. More... | |
char* | soar_cGetWmeValue (psoar_wme w, char *buff) |
soar_cGetWmeValue -- An accessor function for a psoar_wme. More... | |
unsigned long | soar_cGetWmeTimetag (psoar_wme w) |
soar_cGetWmeTimetag -- An accessor function for a psoar_wme. More... | |
unsigned long | soar_cAddIntWme (char *szId, char *szAttr, int value, bool acceptable_preference, psoar_wme *new_wme) |
soar_cAddIntWme -- A wrapper for the soar_cAddWme() function which allows easy addition of a wme whose value is an integer. More... | |
unsigned long | soar_cAddFloatWme (char *szId, char *szAttr, float value, bool acceptable_preference, psoar_wme *new_wme) |
soar_cAddFloatWme -- A wrapper for the soar_cAddWme() function which allows easy addition of a wme whose value is a float. More... | |
void | soar_cInitAgentIterator (soar_apiAgentIterator *ai) |
soar_cInitAgentIterator -- Fill in a soar_apiAgentIterator structure for first use. More... | |
bool | soar_cStepAgentIterator (soar_apiAgentIterator *ai) |
soar_cStepAgentIterator -- Increment an agent iterator srtucture. More... | |
psoar_agent | soar_cGetAgentByName (char *name) |
soar_cGetAgentByName -- Get a pointer to a soar agent. More... | |
int | soar_cGetIdForAgentByName (char *name) |
soar_cGetIdForAgentByName -- Get the unique id of a particular agent. More... | |
bool | soar_cSetCurrentAgentByName (char *name) |
soar_cSetCurrentAgentByName -- Set the 'current agent'. More... | |
void | soar_cSetCurrentAgent (psoar_agent agent) |
soar_cSetCurrentAgent -- Set the 'current agent'. More... | |
psoar_agent | soar_cGetCurrentAgent () |
soar_cGetCurrentAgent -- Get the 'current agent'. More... | |
char* | soar_cGetAgentInputLinkId (psoar_agent a, char *buff) |
soar_cGetAgentInputLinkId -- * An accessor function for a psoar_agent. More... | |
char* | soar_cGetAgentOutputLinkId (psoar_agent a, char *buff) |
soar_cGetAgentOutputLinkId -- * An accessor function for a psoar_agent. More... | |
int | soar_cGetAgentId (psoar_agent a) |
soar_cGetAgentId -- * An accessor function for a psoar_agent. More... | |
void | print (char *format,...) |
print -- Print a given string using the agent's current print function. More... |
Copyright (c) 1995-1999 Carnegie Mellon University, University of Michigan, University of Southern California/Information Sciences Institute. All rights reserved.
The Soar consortium proclaims this software is in the public domain, and is made available AS IS. Carnegie Mellon University, The University of Michigan, and The University of Southern California/Information Sciences Institute make no warranties about the software or its performance, implied or otherwise. All rights reserved.
Conventions: Above each function is a short description of what it does. The arguments and return values are also explained as well as side effects of calling the function.
Each argument is described an arrow of some sort is placed between the argument's name and its description. This arrow indicates what role the argument plays, and may be one of:
|
print -- Print a given string using the agent's current print function.
This function invokes the current agent's top level |
|
soar_cAddCallback -- Add a callback onto the specified callback stack. Unlike soar_cPushCallback(), this function is also designed for callback which will be registered for a longer term. Each callback must have an id string which is assumed to be unique within the specified callback stack. This string is used later, for removal.
|
|
soar_cAddFloatWme -- A wrapper for the soar_cAddWme() function which allows easy addition of a wme whose value is a float.
|
|
soar_cAddGlobalCallback -- Add a callback onto the specified global callback stack. Unlike soar_cAddCallback(), this function adds to an agent independent callback stack. Note that this does not add the callback to each agent's callback stack, but rather specifies a new set of callback stacks which are agent-independent.
|
|
soar_cAddInputFunction -- Adds an input function to the specified agent.
This is called during each input phase. This function is really just a wrapper for the more general soar_cAddCallback() using the
|
|
soar_cAddIntWme -- A wrapper for the soar_cAddWme() function which allows easy addition of a wme whose value is an integer.
|
|
soar_cAddOutputFunction -- Similar to soar_cAddInputFunction(), but adds a function which is called durnig each output phase.
This function is really just a wrapper for the more general soar_cAddCallback() using the
|
|
soar_cAddWme -- Add a working memory element to the current agent's working memory.
|
|
soar_cAttributePreferencesMode -- Determine how preferences for non-context slots should be handled.
|
|
soar_cCallbackNameToEnum -- Return the enumerated type (the callback type) given an event name.
|
|
soar_cCreateAgent -- Create a new soar agent with the specified name.
|
|
soar_cDestroyAgentByAddress -- Destroy an agent, given a pointer to it.
|
|
soar_cDestroyAgentById -- Destroy an agent, given its unique id. There is a one to one correspondence between agents and ids. Ids are assigned when an agent is created, in increasing (but cyclical) order. The id of a particular agent can be retrieved using soar_cGetIdForAgentByName(). Although slightly less efficient than using a pointer to the psoar_agent structure itself, the agent id gives increased security by encapsulating all the sensitive agent data from the user of the api.
|
|
soar_cDestroyAgentByName -- Destroy an agent, given its name.
|
|
soar_cDestroyAllAgentsWithName -- Destroy a set of agents, given a name.
|
|
soar_cExciseAllProductions -- Remove all productions from the agents memory and ReInitialize the agent.
|
|
soar_cExciseAllProductionsOfType -- Remove all productions of a specific type from the agents memory and ReInitialize the agent.
|
|
soar_cExciseAllTaskProductions -- Remove all but default productions from the agents memory and ReInitialize the agent.
|
|
soar_cExciseProductionByName -- Remove the production with the specified name.
|
|
soar_cGetAgentByName -- Get a pointer to a soar agent. This function locates a specific agent, and returns a generic pointer to it. Note that the current agent is not affected.
|
|
soar_cGetAgentId -- * An accessor function for a psoar_agent. Returns a string containing the agent's unique integer ID. This integer is in the range 0 ... MAX_SIMULTANEOUS_AGENTS and no two agents have the same identifier.
|
|
soar_cGetAgentInputLinkId -- * An accessor function for a psoar_agent. Returns a string containing the ID of agent's input-link. Note that memory to hold the string has been allocated within this function and must later be freed by the user when it is no longer in use.
|
|
soar_cGetAgentOutputLinkId -- * An accessor function for a psoar_agent. Returns a string containing the ID of agent's output-link. Note that memory to hold the string has been allocated within this function and must later be freed by the user when it is no longer in use.
|
|
soar_cGetCurrentAgent -- Get the 'current agent'.
|
|
soar_cGetIdForAgentByName -- Get the unique id of a particular agent. This function locates a specific agent, and returns its unique identifier.
|
|
soar_cGetWmeAttr -- An accessor function for a psoar_wme. Returns a string containing the Attribute of the specified wme. Note that memory to hold the string has been allocated within this function and must later be freed by the user when it is no longer in use.
|
|
soar_cGetWmeId -- An accessor function for a psoar_wme. Returns a string containing the ID of the specified wme. Note that memory to hold the string has been allocated within this function and must later be freed by the user when it is no longer in use.
|
|
soar_cGetWmeTimetag -- An accessor function for a psoar_wme.
|
|
soar_cGetWmeValue -- An accessor function for a psoar_wme. Returns a string containing the Value of the specified wme. Note that memory to hold the string has been allocated within this function and must later be freed by the user when it is no longer in use.
|
|
soar_cInitAgentIterator -- Fill in a soar_apiAgentIterator structure for first use. This structure is used to facilitate looping through all soar agents beginning with the currently selected agent.
|
|
soar_cInitializeDCHistogram -- Prepare an array of time structures which will be used to store the time executing a sets of decision cycles.
Note that a a seperate timer is used for this. This may be useful when the resolution of the timers is too rough to be useful at the level of a single decision cycle
|
|
soar_cInitializeKTHistogram -- Prepare an array of time structures which will be used to store the kernel time executing a each successive decision cycle.
Unlike the DCHistogram, this one uses the kernel timer, and updates onces per decision cycle
|
|
soar_cInitializeSoar -- Initialize Soar for the very first time. This should be the first Soar related function called, and it should only be called once. |
|
soar_cListAllCallbacks -- List the callbacks registered to the agent.
|
|
soar_cListAllCallbacksForEvent -- List the all callbacks of a specific type registered to the agent.
|
|
soar_cLoadReteNet -- Load a Rete Network into the agent from a specified file.
|
|
soar_cMultiAttributes -- Modify the multi-attributes setting.
|
|
soar_cPopCallback -- Pops off the last callback to be added to the specified callback stack.
This function is used to remove temporary callbacks added with soar_cPushCallback().
|
|
soar_cPushCallback -- Push a callback onto the specified callback stack. This is designed for callbacks that will only be regisstered temporarily becuase they do not have a registration name. As a result, the only way to remove these callbacks is using the soar_cPopCallback() function which can be problematic if other callbacks have been added in the meantime.
|
|
soar_cQuit -- Quit Soar. This function should be called when Soar (or the application it is embedded within is just about to exit).
|
|
soar_cReInitSoar -- Reset Soar (and agents) to the initial state. This function reinitializes Soar by clearing the working memory of all agents and preparing them for a "new" execution. In essence, they are put back into the same state as if Soar were just started, and the agents were newly loaded.
|
|
soar_cRemoveAllCallbacksForEvent -- Remove all of the callbacks of a specified type which have been registered to the specified agent.
|
|
soar_cRemoveAllMonitorableCallbacks -- Remove all of the callbacks (other than PRINT or LOG callbacks) registered to the specified agent.
|
|
soar_cRemoveCallback -- Remove the callback from the specified callback stack which has the specified id.
|
|
soar_cRemoveGlobalCallback -- Remove a callback onto the specified /global/ callback stack.
|
|
soar_cRemoveInputFunction -- Remove an input function with the specified name. Since the name is used to do the removal, it is a good idea if these functions have unique names to begin with!
|
|
soar_cRemoveOutputFunction -- Remove an output function with the specified name. It is critical that the specified name corresponds to the output-link's symbol.
|
|
soar_cRemoveWme -- Remove a working memory element. This is not as safe as removing a wme using its timetag. Typically this should be called only during the input phase.
|
|
soar_cRemoveWmeUsingTimetag -- Remove a working memory element, given its timetag.
|
|
soar_cRun -- Run the current agent, or all agents for a specified period ...
|
|
soar_cSaveReteNet -- Save a Rete Network from the agent into a specified file.
|
|
soar_cSetChunkNameCount -- Set the chunk count. This must be greater than zero, less than max chunks and greater than the current chunk count.
|
|
soar_cSetChunkNameLong -- Set long or short chunk names according to the specified parameter.
|
|
soar_cSetChunkNamePrefix -- Set the chunk name prefix. This is a string which is used to descriminate chunks from user productions.
|
|
soar_cSetCurrentAgent -- Set the 'current agent'. This function changes the agent that will be affected by subsequent API function calls
|
|
soar_cSetCurrentAgentByName -- Set the 'current agent'. This function changes the agent that will be affected by subsequent API function calls
|
|
soar_cSetLearning -- Adjust the learning settings.
|
|
soar_cSetOperand2 -- Toggles from Soar7 to Soar8 execution mode.
|
|
soar_cSetSystemParameter -- Set a system parameter for the current agent.
|
|
soar_cSetWaitSNC -- Determine whether Soar should generate explict state-no-change impasses.
|
|
soar_cStepAgentIterator -- Increment an agent iterator srtucture. This function increments the agent iterator by one, and signals whether more agents still need to be iterated through. Its results are based on the state of the specified agentIterator.
|
|
soar_cStopCurrentAgent -- Stops the current agent.
|
|
soar_cTestAllMonitorableCallbacks -- Register a simple print function on all the monitorable callback stacks (all but PRINT and LOG).
This is helpful to ensure that callbacks are getting issued as expected.
|