Commit d74fe8d1 authored by John Croisant's avatar John Croisant 😸
Browse files

Added Getting Started section about armor parents and children.

parent 78bc3433
......@@ -343,11 +343,62 @@ the correct tag, so by default there is no feedback if a user passes
the wrong pointer types to a function.
## When should an armor be a child of another armor?
> **Section summary:** Creating a parent-child relationship between
> armors helps ensure proper cleanup and prevent certain kinds of
> memory-related bugs.
Sometimes two objects (structs, unions, or arrays) are related to each
other, so that one object "owns" some data, and the other object uses
part of the data. In Jiffi, the object that owns the data is called
the "parent", and the object that uses the data is called the "child".
A common example is an array of structs: the array is the parent
because it owns the data, and each struct is a child of the array
because it uses part of the array's data. Another example is a parent
struct with a field that holds another struct by value, or holds a
pointer to another struct that the parent is responsible for freeing.
There are many possible variations of parent and child, but the
important characteristics of a parent-child relationship in Jiffi are:
1. After the parent's data is freed, its children are no longer valid.
2. A child's data must not be freed except by freeing the parent.
Jiffi supports creating
[parent-child relationships](https://wiki.call-cc.org/eggref/5/jiffi#armor-children)
between armors. This helps prevent crashes and security
vulnerabilities caused by use-after-free bugs:
* The parent armor will not be garbage collected while any child armor
is still using the parent's data (in other words, until all children
have been garbage collected or
[nullified](https://wiki.call-cc.org/eggref/5/jiffi#nullify-armor)).
* If the parent armor
[tracks its children](https://wiki.call-cc.org/eggref/5/jiffi#armor-tracks-children),
all child armors will be nullified if the parent is manually freed
or nullified.
* Calling a [struct freer](https://wiki.call-cc.org/eggref/5/jiffi#struct-freer)
or an [array freer](https://wiki.call-cc.org/eggref/5/jiffi#array-freer)
on the child will only nullify the child armor, not actually free
the data. (Trying to free part of the parent's memory could cause a
crash, or could accidentally free *all* of the parent's memory.)
Internally, creating the relationship modifies the child armor to
store a strong reference to the parent; and, if the parent tracks its
children, modifies the parent armor to store a weak reference to the
child. An armor can have at most one parent, and can have any number
of children.
If you are using multiple SRFI-18 threads, you may need to enable
thread safety on some parent armors, as described in the next section.
## When should I enable armor thread safety?
> If you use multiple SRFI-18 threads to call certain procedures on an
> armor that tracks its children, you should enable thread safety to
> prevent a race condition.
> **Section summary:** If you use multiple SRFI-18 threads to call
> certain procedures on an armor that tracks its children, you should
> enable thread safety to prevent a race condition.
If you use multiple
[SRFI-18](https://wiki.call-cc.org/eggref/5/srfi-18) threads in your
......
......@@ -1402,7 +1402,22 @@ for other reasons, for example when calling a destructor C function.
</enscript>
==== Armor children
==== Armor parents and children
Jiffi supports creating parent-child relationships between armors.
This helps ensure proper cleanup and prevent certain kinds of
memory-related bugs.
See "[[https://gitlab.com/jcroisant/jiffi/blob/main/docs/getting-started.md#when-should-an-armor-be-a-child-of-another-armor|When should an armor be a child of another armor?]]"
in the Getting Started guide for more information.
[[#define-array-accessors|Array accessors]] that return an armor
automatically create a parent-child relationship. For other cases, you
can create the relationship manually with
[[#armor-parent-set|{{armor-parent-set!}}]].
If you are using multiple SFRI-18 threads, you may need to enable
[[#armor-thread-safety|thread safety]] on some parent armors.
===== {{armor-parent}}
......@@ -1453,19 +1468,10 @@ array items in different record types depending on what data type they
are. See the example below for how to do this using an
[[#array-item-pointer-getter|array item pointer getter]].
Creating the parent-child relationship helps prevent crashes and
security vulnerabilities caused by use-after-free bugs:
* It prevents {{parent}} from being garbage collected while {{child}}
is still using {{parent}}'s bare data.
* It prevents [[#struct-freer|struct freers]] and
[[#array-freer|array freers]] from trying to free {{child}}'s
pointer, which could crash or free all of {{parent}}'s bare data.
* It allows {{child}} to be cleaned up properly if {{parent}} is
manually freed or nullified (unless {{parent}} does not
[[#armor-tracks-children|track its children]]).
Creating the parent-child relationship helps ensure proper cleanup and
prevent certain kinds of memory-related bugs.
See "[[https://gitlab.com/jcroisant/jiffi/blob/main/docs/getting-started.md#when-should-an-armor-be-a-child-of-another-armor|When should an armor be a child of another armor?]]"
in the Getting Started guide for more information.
Example:
......@@ -1497,7 +1503,7 @@ Armor instances can optionally perform bookkeeping to keep track of
their children (see [[#armor-parent|{{armor-parent}}]]) so that the
children can be nullified when the armor instance is freed or
nullified. This helps protect against use-after-free bugs.
See "[[https://gitlab.com/jcroisant/jiffi/blob/main/docs/getting-started.md#why-should-i-use-armor|Why should I use armor?]]"
See "[[https://gitlab.com/jcroisant/jiffi/blob/main/docs/getting-started.md#when-should-an-armor-be-a-child-of-another-armor|When should an armor be a child of another armor?]]"
in the Getting Started guide for more information.
{{armor-tracks-children?}} returns {{#t}} if {{armor}} performs
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment