Commit 8432b94d authored by Kunshan Wang's avatar Kunshan Wang

Describe the state of stacks with states of frames.

This is equivalent to what we currently have, but clearer.
parent 5dc38b56
......@@ -80,8 +80,8 @@ Thread and Stack operations
Create a new stack with ``%func`` as the stack-bottom function. ``%func`` must
have signature ``sig``. Returns the stack reference to the new stack.
The new stack is in the state **READY<Ts>**, where *Ts* is the parameter types
of ``%func``.
The stack-bottom frame is in the state **READY<Ts>**, where *Ts* are the
parameter types of ``%func``.
This instruction continues exceptionally if Mu failed to create the stack. The
exception parameter receives NULL.
......@@ -408,9 +408,8 @@ On-stack replacement
- ``push_frame`` creates a new frame on top of the stack ``%stack`` for the Mu
function ``%func``. ``%func`` must have the signature ``sig``.
The return type of ``%func`` must match the expected return type of the
previous frame. If the previous frame is a native frame, the new function must
have the same return type as the previous Mu callee.
The previous top frame must be in the **READY<Ts>** state for some Ts. The
return type of ``%func`` must be *Ts*.
Watchpoint operations
---------------------
......
......@@ -1180,6 +1180,10 @@ TAILCALL:
The ``CALL`` instruction creates a new stack frame for the callee, passes the
arguments in *argList* and starts executing from the entry block of the callee.
The ``CALL`` instruction sets the state of the frame of the caller to
**READY<Ts>** where ``Ts`` is the return types of the callee. The callee frame's
state is **ACTIVE**.
A ``CALL`` instruction *continues normally* when the callee returns. In this
case the results of the ``CALL`` instruction are the return values of the
callee.
......@@ -1213,18 +1217,20 @@ produce results.
The ``CALL`` instruction is an OSR point.
When a stack in the ``READY<Ts>`` state is pausing on a ``CALL`` instruction and
is being re-bound to a thread, it continues normally with the results being the
values received, or continues exceptionally, catching the exception received.
When a stack is rebound and the top frame is pausing on a ``CALL`` instruction,
it continues normally with the results being the values received, or continues
exceptionally, catching the exception received.
NOTE: Such a state can be the result of OSR: Upper frames are popped and the
current callee is forced to return a value provided by the client.
NOTE: This can be the result of OSR: Upper frames are popped and the current
``CALL`` instruction receives values provided by the client, or by other
means of stack binding. See `Threads and Stacks <threads-stacks.rest>`__.
The ``TAILCALL`` instruction replaces the caller's stack frame with a new stack
frame for the callee. The ``TAILCALL`` requires that the callee must have the
same return types as the caller. The caller of the current function becomes the
caller of the function ``TAILCALL`` calls. The ``TAILCALL`` instruction cannot
have any exception clause and is not an OSR point.
frame for the callee. If the frame below the current frame has state
**READY<Ts>**, the callee must have return type ``Ts``. The caller of the
current function becomes the caller of the function ``TAILCALL`` calls. The
``TAILCALL`` instruction cannot have any exception clause and is not an OSR
point. After ``TAILCALL``, the new frame is in the **ACTIVE** state.
NOTE: ``TAILCALL`` is semantically similar to calling a function and
immediately return the returned value, but replaces the current frame. OSR
......@@ -1262,7 +1268,9 @@ the behaviour of undefined functions.
pointer. See ``CCALL`` which calls a native function.
- All parameters are passed by value and parameters are SSA Values. To pass
on-stack data or arrays, use ``alloca`` and pass ``iref``.
- The keep-alive clause is unique to Mu for OSR.
- The keep-alive clause is similar to the experimental intrinsic function
``@llvm.experimental.stackmap`` and ``@llvm.experimental.patchpoint`` in
LLVM.
..
......@@ -1327,6 +1335,9 @@ The ``RET`` instruction returns from the current function with a list of *rv* as
the return values of the current function. The types of *rv* values must match
the return types of the current function.
From the stack's point of view, the ``RET`` instruction removes the current
frame, and resumes the previous frame into the **ACTIVE** state.
``RET rv`` is a syntax sugar of ``RET (rv)``. In order to return from a function
with zero return values, use ``RET ()``.
......@@ -1375,8 +1386,8 @@ exc
| 0x65 | exc |
+------+-----+
The ``THROW`` instruction throws the exception ``exc`` from the current
function. Exceptions in Mu are object references to any type.
The ``THROW`` instruction throws the exception ``exc`` from the current function
to its caller frame. Exceptions in Mu are object references to any type.
For LLVM users: There is no equivalent in LLVM. The ``resume`` instruction
in LLVM continues the propagation of a in-flight exception. This can also be
......@@ -2332,10 +2343,10 @@ produce any results and unconditionally branches to the destination *dis*.
watchpoints.
A ``TRAP`` or an enabled ``WATCHPOINT`` temporarily unbinds the current thread
from the current stack, leaving the stack in the **READY<** *Ts* **>** state,
and transfers the control to a trap handler in the Mu client. When the current
stack is bound again, this instruction may continue normally with results of
types *Ts*, and may continue exceptionally with a Mu exception.
from the current stack, leaving the current frame in the **READY<** *Ts* **>**
state, and transfers the control to a trap handler in the Mu client. When the
current stack is bound again, this instruction may continue normally with
results of types *Ts*, and may continue exceptionally with a Mu exception.
When rebinding to a stack stopping at an enabled ``TRAP`` or ``WATCHPOINT``
instruction, if rebinding (normally) with values, the results of the ``TRAP`` or
......@@ -2550,11 +2561,16 @@ The return values of ``CCALL`` are the return values of the native callee.
``CCALL`` cannot receive exceptions thrown by C++.
``CCALL`` is an OSR point. A stack may enter the ``READY<Rs>`` state, where Rs
are the return types of the callee, with some Mu frames stopping on ``CCALL``
instructions. If the top frame is stopping at this instruction, the value passed
to the stack when rebinding becomes the return value of this instruction.
However, whether a native frame can be popped is implementation-defined.
When executing the ``CCALL`` instruction, the current frame enters the
**READY<Rs>** state, where *Rs* are the return types of the callee. It creates a
native frame which is in the **ACTIVE** state. Upon running from the native
function, the current frame enters the **ACTIVE** state again.
``CCALL`` is an OSR point.
If a stack is rebound and the top frame stops on a ``CCALL`` instruction
(because of OSR), the result values of ``CCALL`` are the values passed normally,
or it receives the exception provided by the rebinding process.
For LLVM users: Mu is not designed to be compatible with C and functions
defined in Mu IR does not use the native C ABI. This instruction is
......@@ -2785,12 +2801,11 @@ and rebinds it to another stack *swappee*.
In the *curStackClause*:
- If the *curStackClause* is ``RET_WITH``, then the swapper will enter the
``READY<Ts>`` state. *Ts1* can be an empty list, in which case it does not
- If the *curStackClause* is ``RET_WITH``, then the current frame will enter the
**READY<Ts>** state. *Ts1* can be an empty list, in which case it does not
expect values.
- If the *curStackClause* is ``KILL_OLD``, then the swapper will enter the
``DEAD`` state.
- If the *curStackClause* is ``KILL_OLD``, then the current stack is killed.
According to the *newStackClause*, values or an exception can be passed to the
*swappee* stack.
......@@ -2798,10 +2813,9 @@ According to the *newStackClause*, values or an exception can be passed to the
See `Thread and Stack <threads-stacks.rest>`__ for more details about the
SWAP-STACK operation.
When a stack in the ``READY<Ts>`` state is pausing on a ``SWAPSTACK``
instruction and is being re-bound to a thread, then it continues normally with
the return value being the value received, or continues exceptionally, catching
the exception received.
When a stack is rebound and the top frame pauses on a ``SWAPSTACK`` instruction
it continues normally with the return value being the value received, or
continues exceptionally, catching the exception received.
The ``SWAPSTACK`` instruction is an OSR point.
......
......@@ -364,10 +364,6 @@ native frames are counted as one between two Mu frames.)
The ``pop_frame`` function has implementation-defined behaviours when popping
native frames.
During OSR, if the top frame is a native frame, the state of the stack is
``READY<Ts>`` where *Ts* are the return types of the previous frame on top of
the native frame.
When rebinding a thread to a stack with a value, and the top frame is on a call
site (native or Mu), the value associated with the rebinding is the return value
of the call.
......
This diff is collapsed.
......@@ -674,20 +674,20 @@ Stack and thread operations
#define MU_REBIND_THROW_EXC 0x02
``new_stack`` creates a new Mu stack with ``func`` as the bottom function.
Returns a stackref to the new stack. The new stack stops in the very beginning
of ``func``, and its state is ``READY<Ts>``, where *Ts* is the parameter types
of ``func``.
Returns a stackref to the new stack. The stack-bottom frame will resume from the
very beginning of ``func`` when resumed, and its state is **READY<Ts>**, where
*Ts* is the parameter types of ``func``.
``new_thread`` creates a new Mu thread and binds it to ``stack``. ``stack`` must
be in the ``READY<Ts>`` state for some types *Ts*. ``*htr`` determines how to
be in the **READY<Ts>** state for some types *Ts*. ``*htr`` determines how to
bind to the stack. Possible values are ``MU_REBIND_PASS_VALUES`` for passing
values and ``MU_REBIND_THROW_EXC`` for throwing an exception. Values are
provided by the ``args`` array. ``nargs`` is the number of values. The types of
values must match *Ts*. The exception is provided by ``*exc``. Returns a
threadref to the new thread.
``kill_stack`` kills the ``stack``. The stack must be in the ``READY<Ts>`` state
for some *Ts*. The stack enters the ``DEAD`` state. If the stack contains
``kill_stack`` kills the ``stack``. The stack must be in the **READY<Ts>** state
for some *Ts*. The stack enters the **DEAD** state. If the stack contains
native frames, the behaviour is implementation-defined.
``func`` and ``stack`` must not be ``NULL``.
......@@ -760,24 +760,18 @@ On-stack replacement
void (*push_frame)(MuCtx *ctx, MuStackRefValue stack, MuFuncRefValue func);
* ``pop_frame`` pops the top frame of the stack. Popping native frames has
implementation-defined behaviour. Popping a Mu frame changes the state of the
stack to ``READY<Ts>`` where Ts are the return types of the function of the
popped frame.
implementation-defined behaviour.
* ``push_frame`` creates a new frame on the top of ``stack`` for function
``func``.
If the previous stack top frame is a Mu frame, it must be pausing on the
``CALL`` instruction. The return type of ``func`` must be the same as return
type of the ``CALL`` instruction of the previous top.
The previous top frame must be in the **READY<Ts>** state for some Ts. The
return type of ``%func`` must be *Ts*.
If the previous stack top frame is a native frame, the new function must
have the same return type as the previous Mu callee.
After ``push_frame``, the stack enters the ``READY<Ts>`` state where Ts are
the argument types of ``func``. When the stack is rebound, it continues from
the beginning of ``func``. The return value or exceptions from ``func`` are
received by the caller.
After ``push_frame``, the new top frame is in the **READY<Ts>** state where Ts
are the argument types of ``func``. When the stack is rebound, it continues
from the beginning of ``func``. The return value or exceptions from ``func``
are received by the previous frame.
..
......
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