Commit e5170430 authored by Kunshan Wang's avatar Kunshan Wang

Added notes in response to user feedback.

parent 8fb468bd
......@@ -284,6 +284,8 @@ the return value.
Native Interface
================
.. _pinning:
Object pinning
--------------
......
......@@ -92,6 +92,8 @@ implementation-dependent way. The bytes that represents a Mu value is the
For C programmers: it is similar to the "object representation", but in Mu,
unless a memory location is pinned, it may not be represented in such a way.
.. _pinning:
A Mu memory location can be **pinned**. In this state, it is mapped to a
(contiguous) region of bytes in the native memory which contains the bytes
representation of the value the memory location holds. The beginning of the
......
......@@ -254,6 +254,38 @@ return values are allowed for a particular calling convention.
Aggregate Types
===============
For Java programmers: In Mu, aggregate types are like their C counterparts
rather than Java Objects:
- They are values unless explicitly allocated on the heap. For example,
there can be an SSA variable whose type is ``struct<...>``. Functions can
directly pass ``struct<...>`` values to another function, rather than
passing object references. But the instruction ``NEW`` can allocate such
structs on the heap and returns an ``ref<struct<...>>```.
- They directly contain their members, rather than containing references to
heap objects that contain them. So an ``array<int<64>>`` is an array of
64-bit integers, but ``array<ref<int<64>>>`` is an array where each
element is an object reference, referring to a heap object which contains
just an ``int<64>``. In Mu, there can be nested structs, i.e. one struct
directly contain another, such as ``struct<T1 struct<T2 T3 T4> T5>``.
..
For C programmers: Object layout is implementation-specific. The Mu memory
(including the heap objects, stack and global cells) does not expose
byte-by-byte layout unless a memory location is `pinned
<memory.rst#pinning>`__, and the only way to get ``uptr<T>`` from
``iref<T>`` is by using the `pinning instruction
<common-insts.rst#pinning>`__ or the equivalent API. In this way, unless the
Mu program interacts with native programs, the heap/stack/global is private
to Mu, and the memory manager (GC) has much freedom about the layout.
Currently there is also no pragmas to control the layout of objects in Mu.
There were discussions about allowing such control, but making fields
unaligned may have some very weird consequences. For example, LOAD and STORE
operations may no longer be atomic.
Struct
------
......@@ -467,6 +499,9 @@ heap object which is not the same as any others. This is similar to the ``new
Object()`` expression in Java. ``ref<void>``, ``iref<void>``, ``weakref<void>``
and ``uptr<void>`` are also allowed, which can refer/point to "anything".
For C and Java programmers: When a Mu function does not return values, the
signature of the function should be ``(param type here) -> ()``, i.e. the
list of return types is empty.
Reference Types and General Reference Types
===========================================
......@@ -619,6 +654,18 @@ A ``NULL`` value of a ``funcref`` type does not refer to any function.
function" type in C and LLVM, but it only refer to Mu functions. It is not a
pointer (see the ``ufuncptr`` type). It may be implemented under the hood as
a pointer to a function, which will be an implementation detail.
Unlike C and , Mu does not have "function types", either. If a function is
defined, for example::
.funcdef @factorial VERSION %v1 <@factorial.sig> {
...
}
Then the name ``@factorial``, if used as an SSA variable, has type
``funcref<@factorial.sig>``. *The function itself is not a value.* There is
also no defined ways to get a pointer to the compiled machine code, because
it may not necessarily be compiled.
..
......
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