GBBopen 1.5 Reference -- load-blackboard-repository

load-blackboard-repository

load-blackboard-repository pathname &key class-name-translations coalesce-strings confirm-if-not-empty disable-events estimated-peak-forward-references external-format readtable read-eval retain-classes retain-event-functions retain-event-printing => pathname, saved-time, saved-value [Function]

Purpose
Load the blackboard repository (all unit instances and space instances) that has been saved to a file previously by save-blackboard-repository.

Package :gbbopen

Module :gbbopen-core

Arguments and values

pathname		A pathname designator
class-name-translations		An association list (default is `nil`)
coalesce-strings		A generalized boolean (default is `nil`)
confirm-if-not-empty		A generalized boolean (default is true)
disable-events		A generalized boolean (default is `t`)
estimated-peak-forward-references		An integer (default is `default-estimated-peak-forward-references`)
external-format		An external-file-format designator (default is `:default`)
readtable		A readtable (default is `reading-saved/sent-objects-readtable`)
read-eval		A generalized boolean (default is `nil`)
retain-classes		An extended unit-classes specification (see below)
retain-event-functions		A generalized boolean (default is `nil`)
retain-event-printing		A generalized boolean (default is `nil`)
pathname		A pathname
saved-time		A Universal Time
saved-value		An object

Returns
Three values: the pathname of the saved blackboard-repository data file, the time when the blackboard-repository data file was saved, and the save value specified when the repository was saved. If replacing a non-empty blackboard repository is not confirmed, nil is returned.

Events
If disable-events is nil, the following events may be signaled (in order) as unit instances and space instances are deleted prior to loading:

delete-instance-event
unlink-event
instance-removed-from-space-instance-event
instance-deleted-event

Description
If pathname does not specify a file type, the type bb is added to it. Then, (user-homedir-pathname) is used to supply any missing components to pathname.

The class-name-translations association list, if specified, should contain conses of the form:
(class-name . new-class-name)
for any class translations that should occur during repository loading.

If coalesce-strings is true, loaded strings that are equal become shared (eq). This coalescing is performed using a temporary hash table whose initial size can be specified by providing an integer value for coalesce-strings. If a hash table is provided as the value for coalesce-strings, it is used in place of the temporary hash table.

If confirm-if-not-empty is true, the user must confirm loading when the current blackboard repository contains unit instances.

Unit instances that are referenced before they are defined are recorded using a temporary hash table whose initial size can be specified by providing an integer value for estimated-peak-forward-references.

Examples
Load the GBBopen Tutorial Example application (without running it) and then load a blackboard repository that was saved previously:

  > :tutorial-example :noautorun 
     ...
  > (load-blackboard-repository "tutorial")
  ;; 35 temporarily forward-referenced instances (peak count)
  #P"<homedir>/tutorial.bb"
  3429178245
  #<path 1>
  >

Try loading the repository again:

  > (load-blackboard-repository "tutorial")
  The blackboard repository is not empty.
  Continue anyway (the current contents will be deleted) [y or n]? n
  nil
  >

Define a new unit class, new-location, and then load the repository again, translating all location unit instances to new-location unit instances:

  > (define-unit-class new-location (location) ())
  #<standard-unit-class new-location>
  > (load-blackboard-repository "tutorial"
      :class-name-translations '((location . new-location))
      :confirm-if-not-empty nil)
  ;; 35 temporarily forward-referenced instances (peak count)
  #P"<homedir>/tutorial.bb"
  3429178245
  #<path 1>
  > :dsbb

  Space Instance                Contents
  --------------                --------
  known-world                   54 instances (53 new-location; 1 path)

  Unit Class                    Instances
  ----------                    ---------
  control-shell                         1 *
  ks                                    4 +
  ksa-queue                             2 +
  new-location                         53  
  ordered-ksa-queue                     1 +
  path                                  1  
  standard-space-instance               1  
                                ---------
                                       63 instances
  >

The GBBopen Project

load-blackboard-repository