GBBopen 1.5 Reference -- start-control-shell

start-control-shell

start-control-shell &rest initargs => result* [Function]

Purpose
Start the Agenda Shell.

Package :agenda-shell

Module :agenda-shell

Arguments and values

initargs		An initialization argument list (see below)
results		(See below)

Returns
One of the following sets of multiple values:

:quiescence—If the control-shell scheduling loop is terminated due to quiescence (that is, no more executable KSAs remain in the queue of pending KSAs)
:stop and (optionally) associated reasons, as multiple values—If one of the following conditions occurs:
- The exit-control-shell function is called.
- A precondition function or KS-execution function returns :stop and, optionally, associated reasons.
Result-values—If the control-shell is terminated by calling exit-control-shell.

Events
A control-shell-started-event is signaled.

Errors
The idle-loop process has not been started on CMUCL. Multiprocessing has not been started on LispWorks.

Detailed syntax
Available initargs are:

awaken-on-event		A generalized boolean (default is `t`)
continue-past-quiescence		A generalized boolean (default is `nil`)
fifo-queue-ordering		A generalized boolean (default is `t`)
hibernate-on-quiescence		A generalized boolean (default is `nil`)
minimum-ksa-execution-rating		A rating (default is `1`)
instance-name		An object naming this control-shell instance (default is `1`)
output-stream		Control-shell output stream (default is `trace-output`)
pause		A generalized boolean (default is `nil`)
print		A generalized boolean (default is `t`)
run-polling-functions		A generalized boolean (default is `t` on non-threaded Common Lisp implementations; `nil` otherwise)
save-executed-ksas		A generalized boolean (default is `nil`)
save-obviated-ksas		A generalized boolean (default is `nil`)
stepping		Control-shell stepping options (default is `nil`)
stepping-stream		Control-shell stepping stream (default is `query-io`)

Description
Many Agenda Shell behaviors can be customized by providing non-default values for the following initargs:

`:awaken-on-event`		A generalized boolean value indicating whether the control shell is to be awakened from hibernation when any event is signaled
`:continue-past-quiescence`		A generalized boolean value indicating whether the control shell loop should continue even when quiescence-event processing has failed to produce any executable KSAs; use with caution, as the control shell will only exit by an explicit call to exit-control-shell
`:fifo-queue-ordering`		A generalized boolean value that indicates a newly rated pending KSA is to be placed ahead of equally rated KSAs (first-in, first out) or after them (last-in, first out)
`:hibernate-on-quiescence`		A generalized boolean value that determines whether the control-shell will hibernate rather than exit when no executable KSA exists; this decision point is never reached when `:continue-past-quiescence` is true
`:minimum-ksa-execution-rating`		The minimum rating value that a pending KSA must have to be executed
`:output-stream`		The stream to be used for control shell output
`:pause`		A generalized boolean that determines whether the control shell should hibernate until awakened at the start of each cycle
`:print`		A generalized boolean that determines whether start, restart, and termination messages are printed by the control shell
`:run-polling-functions`		A generalized boolean that determines whether polling functions (provided by the `:polling-functions` module) are to be run at the start of each control-shell cycle
`:save-executed-ksas`		A generalized boolean that determines whether executed KSA instances are to be saved on the executed-ksas queue
`:save-obviated-ksas`		A generalized boolean that determines whether obviated KSA instances are to be saved on the obviated-ksas queue
`:stepping`		A list of stepping options (see below) indicating the kinds of control-shell stepping that are to be enabled initially, or the symbol `t`, indicating all stepping options are enabled
`:stepping-stream`		The stream to be used for control shell stepping

Stepping options

The supported stepping options and their interpretations are as follows:

`:activation-predicate`		about to execute the activation predicate of a KS
`:ks-activation`		about to create a KS activation
`:ksa-execution`		about to execute a KS activation
`:obviation-predicate`		about to execute the obviation predicate of a KS
`:precondition-function`		about to execute the precondition function of a KS
`:process-event`		about to perform control-shell processing associated with an event
`:quiescence`		about to perform activities triggered by control-shell quiescence
`:retrigger-function`		about to execute the retrigger function of a KS
`:retrigger-function`		about to execute the revalidation predicate of a KS

Examples
Start the Agenda Shell (in this case, without any KSs defined):

  > (start-control-shell)
  ;; Control shell 1 started
  ;; No executable KSAs remain, exiting control shell
  ;; Control shell 1 exited: 2 cycles completed
  ;; Run time: 0 seconds
  ;; Elapsed time: 0 seconds
  :quiescence
  >

Start the Agenda Shell (again without any KSs defined, but with stepping enabled):

  > (start-control-shell :stepping 't)
  ;; Control shell 1 started
  >> CS Step (cycle 1):
     About to signal quiescence... [? entered]
  Stepping commands (follow with <Return>):
     d       Disable this kind of stepping (:quiescence)
     e       Enable another kind of stepping
     f       Evaluate a form
     h or ?  Help (this text)
     q       Quit (disable all stepping and continue)
     s       Show enabled stepping kinds
     x       Exit control shell
     =       Describe the object of interest (bound to ==)
     +       Enable all stepping
     -       Disable all stepping
     <Space> Continue (resume processing)
  >> CS Step (cycle 1):
     About to signal quiescence... [d entered]
  :quiescence stepping disabled
  >> CS Step (cycle 1):
     About to signal quiescence... [q entered]
  All stepping disabled
  ;; No executable KSAs remain, exiting control shell
  ;; Control shell 1 exited: 2 cycles completed
  ;; Run time: 0 seconds
  ;; Elapsed time: 54 seconds
  :quiescence
  >

Note
When a non-nil :run-polling-functions value is supplied to start-control-shell (the default on Common Lisp implementations without threads), run-polling-functions is called at the beginning of every control-shell-cycle and at one-half-second intervals when the Agenda Shell is hibernating due to quiescence.

The GBBopen Project

start-control-shell