Commit 643ac0b3 authored by Kunshan Wang's avatar Kunshan Wang

Emphasise what "iref" is and what it can refer to.

IRef refers to any memory location in any parts of the Mu memory,
including both heap, stack and global. The common part about them is
that Mu knows the types (at least the location of reference fields) of
all of them. We use the term "conceptually boxed" and "conceptually
unboxed" to describe the difference between the destination of "iref"
and "uptr": irefs always refer into "conceptually boxed" things (boxed
in the sense that Mu knows their field types (at least reference
fields)). Heap objects are obviously boxed. We can consider each stack
as a huge box, and the entire global space as a huge box. "iref" can
only be obtained from the allocation operations in Mu. But uptrs may
point outside the Mu memory, which can be literally anywhere. They can
even be created by C functions, such as "malloc".
parent 89f15c67
......@@ -25,8 +25,8 @@ Basic Concepts
Mu Memory
---------
There are three kinds of memory in Mu, namely the **heap memory**, the **stack
memory** and the **global memory**. **Mu memory** means one of them.
The **Mu memory** consists of three parts: the **heap memory**, the **stack
memory** and the **global memory**.
Memory is allocated in their respective **allocation units**. Every allocation
unit has a **lifetime** which begins when the allocation unit is created and
......@@ -34,14 +34,15 @@ ends when it is destroyed.
A **memory location** is a region of data storage in the memory which can hold
data values. A memory location has a type and its value can only be of that
type.
NOTE: The Mu memory is defined without mentioning "address". There is no
"size", "alignment" or "offset" of a memory location. The relation between a
memory location and an address is only established when pinning (discussed
later). Even when pinned, the address may or may not be the canonical
address where the location is allocated in Mu. For example, Mu objects can
be replicated.
type. An **internal reference** (the `iref type <type-system.rst#iref>`__)
refers to a memory location in *any* part of the Mu memory.
NOTE about **addresses**: The Mu memory is defined without mentioning
"address". There is no "size", "alignment" or "offset" of a memory location.
The relation between a memory location and an address is only established
when pinning (discussed later). Even when pinned, the address may or may not
be the canonical address where the location is allocated in Mu. For example,
Mu objects can be replicated.
When allocating Mu memory locations (in the heap, stack or global memory),
Mu guarantee the location can hold Mu values of a particular type and, as
......@@ -51,15 +52,38 @@ type.
across page boundary, but it may choose to use locks for atomicity, which,
in practice, is usually a bad idea.
..
NOTE about **iref**, i.e. *internal references*: ``iref<T>`` is a traced
reference type. The destination of ``iref<T>`` must be within the Mu memory.
We can consider both heap objects, stacks and the global memory to be
*"conceptually boxed"* in the sense that Mu knows what type those things
contain (at least finding out the reference fields for GC). We can
straightforwardly think about heap objects as boxes that contain the values.
Although stack cells are, in practice, usually allocated by pushing or
popping, we can consider each stack as a huge box that contains many stack
cells. Similarly, "the entire global memory" can be considered a huge box
that contains all global cells. ``iref`` can only be created or derived from
the allocation site of the respective Mu allocation units, such as the
``NEW``, ``ALLOCA`` instructions and the definitions of ``.global``. So
``iref`` can never come out of thin air.
On the contrary, untraced pointers (the `uptr type <type-system.rst#uptr>`__
and the `ufuncptr type <type-system.rst#ufuncptr>`__) are simply addresses.
They may point outside the Mu memory (for instance, to memory allocated by
``malloc``). The destinations are *"conceptually unboxed"*, in the sense
that Mu assume no knowledge about the destination, and the GC will not trace
them.
..
For C programmers: The word "object" in the C language is the counterpart of
"memory location" in Mu. Mu does not have bit fields and a memory location
is always an "object" in C's sense. In Mu's terminology, the word "object"
is a synonym of "heap object" or "garbage-collected object".
"memory location" in Mu. Mu does not have bit fields, and a Mu memory
location is always an "object" in C's sense. In Mu's terminology, the word
"object" is a synonym of "heap object" or "garbage-collected object".
In C, the word "memory location" must have scalar types, but Mu uses the
word for composite types, too.
term "memory location" for composite types, too.
For a memory location L that represents type T, if c is a member (if applicable)
or a component of T, it also has a memory location which is a **member** or a
......@@ -129,9 +153,9 @@ when unambiguous. It is created when executing the ``NEW`` or ``NEWHYBRID``
instructions or the ``new_fixed`` or ``new_hybrid`` API function. It is
destroyed when the object is collected by the garbage collector.
An allocation unit in the stack memory is called an **alloca cell**. It is
created when executing the ``ALLOCA`` or ``ALLOCAHYBRID`` instruction. It is
destroyed when the stack frame containing it is destroyed.
An allocation unit in the stack memory is called an **alloca cell** or **stack
cell**. It is created when executing the ``ALLOCA`` or ``ALLOCAHYBRID``
instruction. It is destroyed when the stack frame containing it is destroyed.
An allocation unit in the global memory is called a **global cell**. One global
cell is created for every ``.global`` declaration in a bundle submitted to Mu.
......
......@@ -186,6 +186,9 @@ floating point number type, respectively.
.typedef @float = float
.typedef @double = double
.. _uptr:
.. _ufuncptr:
Pointer Types
-------------
......@@ -506,6 +509,8 @@ and ``uptr<void>`` are also allowed, which can refer/point to "anything".
Reference Types and General Reference Types
===========================================
.. _iref:
Reference Types
---------------
......@@ -522,7 +527,8 @@ T
heap objects.
``iref`` is an internal reference type. An ``iref`` value is an internal
reference to a memory location.
reference to a memory location. (NOTE: By definition, a "memory location" is in
the Mu memory, including the heap, stack and global.)
``weakref`` is a weak object reference type. It is the weak variant of ``ref``.
A memory location of ``weakref`` holds a weak reference to a heap object and can
......
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