chickadee » jiffi » armor-parent-set!

Performs internal bookkeeping to create a parent-child relationship between child and parent. Modifies both child and parent. Returns child.

child and parent must each be an instance of any type defined with define-armor-type. They can be the same type or different types.

You do not need to call this procedure for armors returned by array accessors, because they call this procedure automatically. You only need to call this procedure manually if you use an armor wrapper to wrap part of the parent's bare data.

For example, if you have an array of unions, you might want to wrap array items in different armor types depending on what data type they are. See the example below for how to do this using an array item pointer getter.

Creating the parent-child relationship helps ensure proper cleanup and prevent certain kinds of memory-related bugs. See "When should an armor be a child of another armor?" in the Getting Started guide for more information.

Example:

;; Return an event from the array, wrapped in either a key-event or
;; sensor-event instance, depending on what type of event it is.
(define (event-array-ref/typed array i)
  ;; Use the array item pointer getter to get a bare pointer/locative.
  (let* ((ptr (event-array-ref* array i))
         ;; Wrap ptr in the correct armor type.
         (event (case (event-type ptr)
                   ((key) (wrap-key-event ptr))
                   ((sensor) (wrap-sensor-event ptr)))))
    ;; If array is wrapped in armor, set event's parent and return
    ;; event. Otherwise, just return event.
    (if (armor? array)
        (armor-parent-set! event array)
        event)))