Main Page   Compound List   File List   Compound Members   File Members  

callback.h File Reference

Soar Callbacks. More...

Go to the source code of this file.

Compounds

struct  callback_struct

Typedefs

typedef void* soar_callback_agent
 The agent upon which the callback is invoked. More...

typedef char* soar_callback_id
 A callback id is also a string.

typedef void* soar_callback_data
 Data sent to the callback function each time it is invoked. More...

typedef void* soar_call_data
 Data sent to the callback function. More...

typedef void (* soar_callback_fn )(soar_callback_agent, soar_callback_data, soar_call_data)
 Any callback registered with Soar, must be in this format.


Enumerations

enum  SOAR_CALLBACK_TYPE {
  NO_CALLBACK, SYSTEM_STARTUP_CALLBACK, SYSTEM_TERMINATION_CALLBACK, BEFORE_INIT_SOAR_CALLBACK,
  AFTER_INIT_SOAR_CALLBACK, AFTER_HALT_SOAR_CALLBACK, BEFORE_SCHEDULE_CYCLE_CALLBACK, AFTER_SCHEDULE_CYCLE_CALLBACK,
  BEFORE_DECISION_CYCLE_CALLBACK, AFTER_DECISION_CYCLE_CALLBACK, BEFORE_INPUT_PHASE_CALLBACK, INPUT_PHASE_CALLBACK,
  AFTER_INPUT_PHASE_CALLBACK, BEFORE_PREFERENCE_PHASE_CALLBACK, AFTER_PREFERENCE_PHASE_CALLBACK, BEFORE_WM_PHASE_CALLBACK,
  AFTER_WM_PHASE_CALLBACK, BEFORE_OUTPUT_PHASE_CALLBACK, OUTPUT_PHASE_CALLBACK, AFTER_OUTPUT_PHASE_CALLBACK,
  BEFORE_DECISION_PHASE_CALLBACK, AFTER_DECISION_PHASE_CALLBACK, WM_CHANGES_CALLBACK, CREATE_NEW_CONTEXT_CALLBACK,
  POP_CONTEXT_STACK_CALLBACK, CREATE_NEW_ATTRIBUTE_IMPASSE_CALLBACK, REMOVE_ATTRIBUTE_IMPASSE_CALLBACK, PRODUCTION_JUST_ADDED_CALLBACK,
  PRODUCTION_JUST_ABOUT_TO_BE_EXCISED_CALLBACK, FIRING_CALLBACK, RETRACTION_CALLBACK, SYSTEM_PARAMETER_CHANGED_CALLBACK,
  PRINT_CALLBACK, LOG_CALLBACK, ASK_CALLBACK, WAIT_CALLBACK,
  NUMBER_OF_CALLBACKS
}
enum  SOAR_GLOBAL_CALLBACK_TYPE {
  NO_GLOBAL_CALLBACK, GLB_CREATE_AGENT, GLB_AGENT_CREATED, GLB_DESTROY_AGENT,
  NUMBER_OF_GLOBAL_CALLBACKS
}


Detailed Description

Soar Callbacks.

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.

Id:
callback.h,v 1.6 2001/05/08 18:36:06 swallace Exp

Each agent has a separate callback table. The table has one entry per callback type and the entry is a pointer to a list. The list contains installed callbacks, one callback per list cons cell.


Typedef Documentation

typedef void * soar_call_data
 

Data sent to the callback function.

This content of this data is determined solely by the type of callback and the internals of Soar

typedef void * soar_callback_agent
 

The agent upon which the callback is invoked.

Directly castable to either agent * or psoar_agent

typedef void * soar_callback_data
 

Data sent to the callback function each time it is invoked.

This data is available at the time the user registers the callback, and has nothing to do with Soar's internals whatsoever.


Enumeration Type Documentation

enum SOAR_CALLBACK_TYPE
 

Standard (Agent Specific) Callbacks

All callback functions installed by the user must use the function soar_add_callback. The type signature of all callback functions is the same and has the following form:

my_callback_fn(agent * a, soar_callback_data scd, soar_call_data call_data);

where "a" is a pointer to the agent structure for the agent in which the callback was invoked, "scd" is the data structure given in the installation when soar_add_callback was called, and "call_data" is the data relevant to this particular call. To use the "call_data" parameter, it should first be cast to the appropriate type, which is mentioned below. Since only the "call_data" argument varies for all callbacks, only that argument will be mentioned in the following.

SYSTEM_STARTUP_CALLBACK
This function is called only once, at system startup time. It can be used to set up any Soar I/O routines and install any interface commands. This function is called after most of the system has been initialized, but before any agent initialization file is loaded. The "call_data" argument is given as NULL.
SYSTEM_TERMINATION_CALLBACK
This function is called only once, just before the system exits back to the shell. The "call_data" parameter is of type "bool" which is TRUE if the system is exiting normally, and FALSE if the exit is happening because some fatal error situation was detected. Typically, this routine should do any final cleanup (closing files, etc.) necessary.
BEFORE_INIT_SOAR_CALLBACK
This function is called just before any init-soar is done. (This includes not only the init-soar command, but also excise-task and excise-all, which do an init-soar.) The "call_data" argument is given as NULL.
AFTER_INIT_SOAR_CALLBACK
This function is called just after any init-soar is done. (This includes not only the init-soar command, but also excise-task and excise-all, which do an init-soar.) The "call_data" argument is given as NULL.
AFTER_HALT_SOAR_CALLBACK
This function is called after Soar halts; i.e., after the preference phase in which the RHS function "halt" is executed. The "call_data" argument is given as NULL.
BEFORE_SCHEDULE_CYCLE_CALLBACK
This function is called just before the agent is scheduled. The "call_data" argument is given as NULL.
AFTER_SCHEDULE_CYCLE_CALLBACK
This function is called just after the agent is scheduled. The "call_data" argument is given as NULL.
BEFORE_DECISION_CYCLE_CALLBACK
This function is called at the start of each decision cycle. The "call_data" argument is given as NULL.
AFTER_DECISION_CYCLE_CALLBACK
This function is called at the end of each decision cycle. The "call_data" argument is given as NULL.
BEFORE_INPUT_PHASE_CALLBACK
This function is called at the start of each input phase. This is called even if the input cycle is effectively null because there is no top state. The "call_data" argument is given as NULL.
INPUT_PHASE_CALLBACK
This function is called during each input phase. The "call_data" argument contains the input mode currently being used.
AFTER_INPUT_PHASE_CALLBACK
This function is called at the end of each input phase. This is called even if the input cycle is effectively null because there is no top state. The "call_data" argument is given as NULL.
BEFORE_PREFERENCE_PHASE_CALLBACK
This function is called at the start of each preference phase. The "call_data" argument is given as NULL.
AFTER_PREFERENCE_PHASE_CALLBACK
This function is called at the end of each preference phase. The "call_data" argument is given as NULL.
BEFORE_WM_PHASE_CALLBACK
This function is called at the start of each working memory phase. The "call_data" argument is given as NULL.
AFTER_WM_PHASE_CALLBACK
This function is called at the end of each working memory phase. The "call_data" argument is given as NULL.
BEFORE_OUTPUT_PHASE_CALLBACK
This function is called at the start of each Soar output cycle. This is called even if the output cycle is effectively null because there is no top state. The "call_data" argument is given as NULL.
OUTPUT_PHASE_CALLBACK
This function is called during each Soar output cycle. The "call_data" argument is a structure which contains both the output mode being used and the list of output wmes.
AFTER_OUTPUT_PHASE_CALLBACK
This function is called at the end of each Soar output cycle. This is called even if the output cycle is effectively null because there is no top state. The "call_data" argument is given as NULL.
BEFORE_DECISION_PHASE_CALLBACK
This function is called at the start of each decision phase. The "call_data" argument is given as NULL.
AFTER_DECISION_PHASE_CALLBACK
This function is called at the end of each decision phase. The "call_data" argument is given as NULL.
WM_CHANGES_CALLBACK
This function is called just before changes are made to working memory. The pre-callback hook function passed two arguments to the corresponding hook function. However, the "call_data" argument is given as NULL, in this callback. The wmes_being_added and wmes_being_removed can be retrieved from the agent structure already being passed.
CREATE_NEW_CONTEXT_CALLBACK
This function is called after a new goal context is created. The "call_data" argument is a pointer to a "Symbol" which is the new goal identifier. This goal identifier is equal to the agent variable bottom_goal.
POP_CONTEXT_STACK_CALLBACK
This function is called just before the context stack is popped. The "call_data" argument is a pointer to a "Symbol" which is the identifier of the goal about to be removed. This goal identifier is equal to the aget variable bottom_goal. If the stack is popped k levels at once, this routine is called k times in bottom-up order.
CREATE_NEW_ATTRIBUTE_IMPASSE_CALLBACK
This function is called just after an attribute impasse is created. The "call_data" argument is a pointer to a "slot" which is the impassed slot.
REMOVE_ATTRIBUTE_IMPASSE_CALLBACK
This function is called just before an attribute impasse is removed. The "call_data" argument is a pointer to a "slot" which is the impassed slot.
PRODUCTION_JUST_ADDED_CALLBACK
This function is called just after a production (including chunks and justifications) is added to the system. The "call_data" argument is a pointer to a "production" which is the production just added.
PRODUCTION_JUST_ABOUT_TO_BE_EXCISED_CALLBACK
This function is called just before a production (including chunks and justifications) is excised from the system. The "call_data" argument is a pointer to a "production" which is the production just about to be removed.
FIRING_CALLBACK
This function is called after every production firing. The "call_data" argument is a pointer to an "instantiation" which is the newly created instantiation.
RETRACTION_CALLBACK
This function is called before every production retraction. The "call_data" argument is a pointer to an "instantiation" which is the instantiation about to be retracted.
SYSTEM_PARAMETER_CHANGED_CALLBACK
This function is called after any change to one of the agent system parameters (e.g., learn on/off). See soarkernel.h for a list of these system parameters. The "call_data" argument is an "int" which indicates which system parameter is being changed. This function should examine the new value of the parameter by looking at the appropriate agent variable. (For most parameters, this means looking at the sysparams[] array.)
INIT_LAPSE_DURATION_CALLBACK
This function is called upon agent (re-initialization). The "call_data" argument is a "long" which indicates the time since the last lapse. It should be modified by the callback to indicate how long of an attention lapse should occur.

enum SOAR_GLOBAL_CALLBACK_TYPE
 

Global (Agent Independent) Callbacks

All global callback functions installed by the user must use the function soar_add_global_callback. The type signature of all callback functions is the same as that used for agent-dependent callbacks and has the following form:

my_callback_fn(agent * a, soar_callback_data scd, soar_call_data call_data);

however, in some situations, the argument "a" may be NULL, whereas this will never be a case in a normal (agent-dependent) callback. All other parameter, mock those in a normal callback function. Below, arguments are specified for each global callback type:

GLB_CREATE_AGENT
This function is called just prior to the creation of a new agent. Because this is global becuase it is obviously impossible to register a normal callback with an agent which has not yet been created. The parameters passed to the callback function are: a --> NULL call_data --> (char *) agent_name
GLB_AGENT_CREATED
This function is called just after the creation of a new agent. The parameters passed to the callback function are: a --> a pointer to the new agent call_data --> the same as above, a pointer to the new agent
GLB_DESTROY_AGENT
This function is called just before an agent is destroyed. The parameters passed to the callback function are: a --> a pointer to the agent to be destroyed call_data --> the same as above, a pointer to the agent to be destroyed


Generated at Wed Aug 8 09:49:33 2001 for The Soar Application Programming Interface by doxygen1.2.6 written by Dimitri van Heesch, © 1997-2001