Commit 682ee4b5 authored by Kunshan Wang's avatar Kunshan Wang

Emphaise that handles are immutable

And they are not the same as the constants in the IR.
parent 643ac0b3
......@@ -158,6 +158,21 @@ Handles have reference semantics: a handle refers to a value the client context
holds. Handles can be copied as if they are pointers in C, and the resulting
handles refer to the same value held by a context.
Handles and their values are **immutable**. This means, once MuCtx created a
handle to a value, the value cannot be changed. Every time an API function is
called, a **new** handle to a **new** value is generated. Some API functions
have confusing names (as a legacy from LLVM) such as ``insertvalue`` or
``insertelement``, but these functions (conceptually) make copies of the old
values, and update the copied values before giving the handle to the client.
Handles are not `constants <ir.rst#constant-definition>`__. Handles are
ephemeral **run-time** value holders, and can only be used through the API.
"Constants", on the other hand, are part of the Mu IR, are **compile-time** SSA
variables, are permanent in the bundle, and are usable by Mu IR instructions.
There is a `handle_from_const <#handle-from-const>`__ API function that creates a new value in the
MuCtx which has the same value of the `constant
<ir.rst#constant-definition>`__, and returns its handle to the client.
A handle is only valid within a client context. They must only be accessed with
API functions that operates on the same context the handle is in. Handles are
valid until either the value held by the context is explicitly deleted, or the
......@@ -465,6 +480,8 @@ Other functions are:
For JNI users: Primitive types in JNI do not need to be converted. They are
not held by handles and they are already compatible with C data types.
.. _handle-from-const:
Create handles from Mu global variables
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment