This page describes the operation of the behavior queue.  Details discussed here may also be found in different places throughout this reference.  All this information has been collected in one place for convenience.

The Queue and its Status

The Garcia API maintains a FIFO queue for scheduling the execution of behaviors.  The idle property of the API may be used to determine the status of the queue.  It will be true if no behavior is currently active and no behaviors remain in the queue.

Creating Behaviors

A behavior can be created with a createBehavior or createNamedBehavior call.  After a behavior has been created, it may be scheduled with the queueBehavior routine.  If the queue is empty and no behavior is currently active (i.e. the "idle" property is true), the newly queued behavior will begin execution immediately.  Otherwise, the behavior is added to the queue.

Termination of Behaviors

Garcia behaviors return a status code upon completion.  These codes are defined in the aGarciaDefs.tea file.  The default status code for indicating success is aGARCIA_ERRFLAG_NORMAL, or 0.  A user may specify any number of expected-status codes that also indicate successful completion.  For example, a user may want a behavior to terminate successfully if the front sensors detect something.  If a behavior completes successfully, the memory allocated for the behavior object will be destroyed and the next behavior in the queue will be retrieved.  Then the next behavior will begin execution.

A behavior terminates unsuccessfully if its status code does not match the default value or any specified expected-status codes.  If a behavior is unsuccessful, all remaining behaviors in the queue will be flushed.  When one behavior in a sequence fails, the robot will probably be in a state that prevents execution of the other behaviors.  For example, the robot could have rolled close to a drop-off.  This is why the queue is flushed when an error occurs.

A user may also flush the queue with the flushQueueBehaviors command.  This will terminate any active behavior and empty the queue.  This is necessary if the user's application detects an error condition that the robot can not detect while performing a behavior.  A simple case is terminating an application that has already queued some behaviors.  Without flushing the queue, the robot may still be executing a behavior and rolling around even after the user's application exits.

Callbacks

A user may assign callback objects for a behavior.  These objects define functions that get called when a behavior begins execution or terminates.  To use callbacks, the user must derive classes from the acpCallback base class, dynamically create new callback objects each time a behavior is created, and assign them to the behavior using the execute-callback and completion-callback properties.  The callback objects will be destroyed automatically after they are called.

Execute callbacks enable a user to perform a task when the robot starts a new behavior.  Completion callbacks provide a method for controlling an application based on the outcome of a behavior.  For example, suppose a behavior terminates in response to an IR signal or a stall.  The next step after getting an IR signal may be to seek a beacon.  The next step after sensing a stall may be to back up or try to roll forward again with more power.

The handleCallbacks routine must be called in order to process callback objects.  Typically, an application runs in a tight loop calling this routine.  This loop can poll the idle property to determine when any pending behaviors have terminated.  The application can also access other properties within such a loop.  Once the robot is idle, the program can exit the loop and decide what to do next based on results returned by callback functions.

Sample Code

See the aGarciaApp example in the Garcia download or BrainStem SDK download.  It's a small command line program that illustrates the concepts described here.