>xabsl   The Extensible Agent Behavior Specification Language

XabslEngine Class Library Reference

 

XabslEngine.h

Go to the documentation of this file.
00001 /** 
00002 * @file XabslEngine.h
00003 *
00004 * Declaration class Engine
00005 *
00006 * @author <a href="http://www.martin-loetzsch.de">Martin Loetzsch</a>
00007 * @author <a href="http://www.sim.informatik.tu-darmstadt.de/pers/card/risler.html">Max Risler</a>
00008 * @author <a href="http://www.informatik.hu-berlin.de/~juengel">Matthias Jčngel</a>
00009 */
00010 
00011 #ifndef __XabslEngine_h_
00012 #define __XabslEngine_h_
00013 
00014 #include "XabslAgent.h"
00015 #include "XabslOption.h"
00016 #include "XabslCoopState.h"
00017 #include "XabslTeamMessage.h"
00018 
00019 namespace xabsl 
00020 {
00021 
00022 /**
00023 * Executes a behavior that was specified in the Xabsl language.
00024 *
00025 * @author <a href="http://www.martin-loetzsch.de">Martin Loetzsch</a>
00026 * @author <a href="http://www.sim.informatik.tu-darmstadt.de/pers/card/risler.html">Max Risler</a>
00027 * @author <a href="http://www.informatik.hu-berlin.de/~juengel">Matthias Jčngel</a>
00028 */
00029 class Engine : public Symbols
00030 {
00031 public:
00032   /** 
00033   * Constructor 
00034   * @param e Is invoked when there are problems during initialization
00035   * @param pTimeFunction a pointer to a function that returns the system time in ms.
00036   */
00037   Engine(ErrorHandler& e, unsigned (*pTimeFunction)());
00038 
00039   /** Destructor */
00040   ~Engine();
00041 
00042   /** 
00043   * Executes the engine for the selected agent starting from the root option.
00044   * (Including the selected basic behavior)
00045   */
00046   void execute();
00047 
00048   /**
00049   * Reads the intermediate code from an input source and creates the option graph.
00050   * Note that the basic behaviors and symbols have to be registered before that function is 
00051   * called.
00052   */
00053   void createOptionGraph(InputSource& input);
00054 
00055   /** 
00056   * Registers a basic behavior at the engine. 
00057   * This must be done before the intermediate code is read.
00058   * @param basicBehavior A reference to the basic behavior
00059   */
00060   void registerBasicBehavior(BasicBehavior& basicBehavior);
00061 
00062   /** 
00063   * Sets the selected Agent.
00064   * If the last selected agent was different from the new one, 
00065   * the root option is changed depending on the new agent.
00066   * @param name The name of the agent
00067   * @return if the requested agent exists
00068   */
00069   bool setSelectedAgent(const char* name);
00070 
00071   /**
00072   * Resets all active options.
00073   * Next cycle will execute initial state of currently set root option.
00074   */
00075   void reset();
00076 
00077 private:
00078 
00079   /** 
00080   * The time of the start of the current engine execution
00081   */
00082   unsigned timeOfExecutionStart;
00083 
00084   /** The agents of the engine */
00085   NamedArray<Agent*> agents;
00086 
00087   /** The selected agent */
00088   Agent* selectedAgent;
00089 
00090   /** The options of the engine */
00091   NamedArray<Option*> options;
00092 
00093   /** The actions for the execution of the start of the option graph */
00094   Array<Action*> rootActions;
00095 
00096   /** The registered basic behaviors of the engine */
00097   NamedArray<BasicBehavior*> basicBehaviors;
00098 
00099   /** Is invoked when there are problems during initialization */
00100   ErrorHandler& errorHandler;
00101 
00102   /** 
00103   * A recursive function that is used to check for loops in the option graph.
00104   * @param currentOption The option to be checked
00105   * @param currentOptionTree An array of the currently traced option tree
00106   * @param currentLength The length of the current option tree array
00107   * @param maxSize maximum allowed size of the array
00108   * @return If true, then a loop was detected.
00109   */
00110   bool checkForLoops(Option* currentOption, ActionBehavior* currentOptionTree[], int currentLength, int maxSize);
00111 
00112   /** A recursive function that generates a list of actions referenced from a starting option 
00113   * This is used by checkForLoops.
00114   * @param actionToAdd The option whose referenced actions are to be added to the current array
00115   * @param currentOptionTree An array to which the referenced options are to be added 
00116   * @param currentLength The current length of the array. Actions will be appended at the end of the array. currentLength will increase accordingly.
00117   * @param maxSize maximum allowed size of the array
00118   */
00119   void addActions(ActionBehavior* actionToAdd, ActionBehavior* currentOptionTree[], int& currentLength, int maxSize);
00120 
00121   /** 
00122   * Rescursively count the number of actions referenced from an option
00123   * @param option A pointer to the option for which the referenced options are counted.
00124   * @return Number of actions */
00125   int countActions(Option* option);
00126 
00127   /** If true, the engine was successfully initialized */
00128   bool initialized;
00129 
00130   /** A pointer to a function that returns the system time in ms. */
00131   unsigned (*pTimeFunction)();
00132 
00133   /** Arrays containing internal symbol values */
00134   NamedArray<double> internalDecimalSymbols;
00135   NamedArray<bool> internalBooleanSymbols;
00136   NamedArray<int> internalEnumeratedSymbols;
00137 
00138   /** Array of states which are used for cooperating agents */
00139   Array<CoopState*> coopStates;
00140 
00141   /** Priority value of the agent, used for solving conflicts in cooperative state assignment */
00142   int agentPriority;
00143 
00144   /** Number of execution cycles that is required for synchonization with other agents, i.e time from sending a message until answer is received */
00145   int synchronizationTicks;
00146 
00147 public:
00148   //!@name Debugging Interface 
00149   //!@{
00150 
00151   /** Returns the agents of the engine */
00152   const NamedArray<Agent*>& getAgents() const {return agents;}
00153 
00154   /** Return the options of the engine */
00155   const NamedArray<Option*>& getOptions() const {return options;}
00156 
00157   /** Returns the registered basic behaviors of the engine */
00158   const NamedArray<BasicBehavior*>& getBasicBehaviors() const {return basicBehaviors;}
00159 
00160   /**
00161   * Clears the list of actions executed starting the option graph.
00162   */
00163   void clearRootActions();
00164 
00165   /** 
00166   * Adds a given option or basic behavior to the list of actions executed starting the option graph.
00167   * Can be called to test a single option or basic behavior.
00168   * @param name The name of the option or basic behavior
00169   * @param isOption True for an option, false for a basic behavior
00170   * @return When false, the option is not known to the engine
00171   */
00172   bool addRootAction(const char* name, bool isOption = true);
00173 
00174   /** 
00175   * Executes the option graph starting from a given option or basic behavior.
00176   * Can be called to test a single option or basic behavior.
00177   * @param name The name of the option or basic behavior
00178   * @param isOption True for an option, false for a basic behavior
00179   * @return When false, the option is not known to the engine
00180   */
00181   bool setRootAction(const char* name, bool isOption = true);
00182 
00183   /** 
00184   * Sets the root option of the selected agent
00185   */
00186   void setRootAction();
00187 
00188   /** 
00189   * Adds the specified option or basic behavior to the list of root actions.
00190   */
00191   void addRootAction(Behavior* behavior);
00192 
00193   /**
00194   * Adds a decimal output symbol assignment to the list of root actions.
00195   */
00196   bool addRootActionDecimalOutputSymbol(const char* name, double value);
00197 
00198   /**
00199   * Adds a boolean output symbol assignment to the list of root actions.
00200   */
00201   bool addRootActionBooleanOutputSymbol(const char* name, bool value);
00202 
00203   /**
00204   * Adds an enumerated output symbol assignment to the list of root actions.
00205   */
00206   bool addRootActionEnumeratedOutputSymbol(const char* name, const char* value);
00207 
00208   /** 
00209   * Sets the root option to the specified option or basic behavior
00210   */
00211   void setRootAction(Behavior* behavior);
00212 
00213   /** Returns the selected root actions */
00214   const Action* getRootAction(int i) const;
00215 
00216   /** Returns the selected root actions */
00217   Action* getRootAction(int i);
00218 
00219   /** Returns the selected root actions */
00220   const Array<Action*>& getRootActions() const;
00221 
00222   /** Returns the selected root actions */
00223   Array<Action*>& getRootActions();
00224 
00225   /** Returns the name of the selected agent */
00226   const char* getSelectedAgentName() const;
00227 
00228   /** Prepare for processing incoming team messages. This resets previously processed messages. */
00229   void prepareIncomingMessages();
00230 
00231   /** Process an incoming team message from another agent */
00232   void processIncomingMessage(const TeamMessage& message);
00233 
00234   /** Generate the outgoing team message to be sent to other agents */
00235   void generateOutgoingMessage(TeamMessage& message);
00236 
00237   /** Set the number of execution cycles that is required for synchonization with other agents, i.e time from sending a message until answer is received */
00238   void setSynchronizationTicks(int ticks) {synchronizationTicks = ticks;}
00239 
00240   /** Sets the priority value of the agent, used for solving conflicts in cooperative state assignment */
00241   void setAgentPriority(int priority) {agentPriority = priority;}
00242   //!@}
00243 };
00244 
00245 } // namespace
00246 
00247 #endif // __XabslEngine_h_
00248 

Up | Main Page | Generated at Wed Aug 19 17:32:29 2009.