make-duplicate-instance

Purpose
Create a duplicate instance of instance.

Method signatures

Package   :gbbopen-tools (re-exported by :gbbopen)

Module   :gbbopen-tools (the unit-instance and space-instance methods are added by :gbbopen-core)

Arguments and values

Returns
Two values: the (newly created) duplicate instance and a list of the slots that were duplicated or explicitly initialized.

Events
When a unit instance is duplicated, events are signaled in the following sequence:

1. An update-nonlink-slot-event or link-event is signaled for each initialized slot in the duplicated unit instance. A link-event is also signaled for each inverse pointer from an existing unit instance to the (newly created) duplicate unit instance.
2. An add-instance-to-space-instance-event is signaled for each space instance on which the duplicate unit instance is added.
3. A create-instance-event is signaled.

Errors
Use of an initialization argument that has not been declared as valid.

Description
Slot initialization during instance duplication behaves as follows, regardless of whether the slots are local or shared:

• If an initarg in initargs specifies a value for a slot, that value is stored into the slot.
• All slots that are still unbound at this point and that are not named in unduplicated-slot-names or in the list of slot-names returned from calling unduplicated-slot-names on instance are set to the value of the slot in instance.
• Any slots indicated by slot-names that are still unbound at this point are initialized according to their :initform forms.

Specifying a :instance-name initialization argument causes that value to be used as the instance name of the newly created unit instance instead of the instance-name counter value associated with the unit class (if the :use-global-instance-name-counter class option is nil or was not specified for the unit class) or the global instance-name counter value (if the :use-global-instance-name-counter class option is true for the unit class).

A :space-instances initialization argument must be provided when duplicating a space instance.

See also
    change-class
    delete-instance
    describe-instance
    initial-class-instance-number
    instance-name-of
    make-instance
    make-space-instance
    next-class-instance-number
    unduplicated-slot-names

Examples
Create some simple duplicate instances:

  > (define-class foo () 
       ((a :initform 1)
        (b :initform 2)))
  #<standard-class foo>
  > (defparameter *x* (make-instance 'foo :a 11 :b 12))
  *x*
  > :ds *x*
  #<foo #x110fe6ea> is an instance of #<standard-class foo>:
   The following slots have :instance allocation:
    a   11
    b   12
  > :ds (make-duplicate-instance *x* nil :a -1)
  #<foo #x110ff93a> is an instance of #<standard-class foo>:
   The following slots have :instance allocation:
    a   -1
    b   12
  > :ds (make-duplicate-instance *x* '(b) :a -1)
  #<foo #x11104542> is an instance of #<standard-class foo>:
   The following slots have :instance allocation:
    a   -1
    b   2
  > :ds (make-duplicate-instance *x* '(b))
  #<foo #x11108c82> is an instance of #<standard-class foo>:
   The following slots have :instance allocation:
    a   11
    b   2
  > (make-duplicate-instance *x* nil)
  #<foo @ #x1110a0e2>
  (#<standard-effective-slot-definition b>
   #<standard-effective-slot-definition a>)
  >

Create a duplicate of the hyp 419 unit instance:

  > (make-duplicate-instance (find-instance-by-name 19 'hyp) nil)
  #<hyp 681 (1835 4791) 0.85 [5..35]>
  >

make-duplicate-instance