1
0
mirror of https://github.com/janet-lang/janet synced 2024-12-29 01:40:26 +00:00

Change name to janet.

Calvin Rose 2018-09-05 22:23:38 -04:00
parent 9f45345eaa
commit 41d6ec49c2

@ -1,14 +1,14 @@
The Dst language is implemented on top of an abstract machine (AM). The compiler
converts Dst data structures to this bytecode, which can then be efficiently executed
from inside a C program. To understand the dst bytecode, it is useful to understand
the abstractions used inside the Dst AM, as well as the C types used to implement these
The Janet language is implemented on top of an abstract machine (AM). The compiler
converts Janet data structures to this bytecode, which can then be efficiently executed
from inside a C program. To understand the janet bytecode, it is useful to understand
the abstractions used inside the Janet AM, as well as the C types used to implement these
features.
## The Stack = The Fiber
A Dst Fiber is the type used to represent multiple concurrent processes
in dst. It is basically a wrapper around the idea of a stack. The stack is
divided into a number of stack frames (`DstStackFrame *` in C), each of which
A Janet Fiber is the type used to represent multiple concurrent processes
in janet. It is basically a wrapper around the idea of a stack. The stack is
divided into a number of stack frames (`JanetStackFrame *` in C), each of which
contains information such as the function that created the stack frame,
the program counter for the stack frame, a pointer to the previous frame,
and the size of the frame. Each stack frame also is paired with a number
@ -58,35 +58,35 @@ of their stacks. Making a function call involves pushing arguments to this
temporary stack, and then invoking either the CALL or TCALL instructions.
Arguments for the next function call are pushed via the PUSH, PUSH2, PUSH3, and
PUSHA instructions. The stack of a fiber will grow as large as needed, although by
default dst will limit the maximum size of a fiber's stack.
default janet will limit the maximum size of a fiber's stack.
The maximum stack size can be modified on a per fiber basis.
The slots in the stack are exposed as virtual registers to instructions. They
can hold any Dst value.
can hold any Janet value.
## Closures
All functions in dst are closures; they combine some bytecode instructions
All functions in janet are closures; they combine some bytecode instructions
with 0 or more environments. In the C source, a closure (hereby the same as
a function) is represented by the type `DstFunction *`. The bytecode instruction
part of the function is represented by `DstFuncDef *`, and a function environment
is represented with `DstFuncEnv *`.
a function) is represented by the type `JanetFunction *`. The bytecode instruction
part of the function is represented by `JanetFuncDef *`, and a function environment
is represented with `JanetFuncEnv *`.
The function definition part of a function (the 'bytecode' part, `DstFuncDef *`),
The function definition part of a function (the 'bytecode' part, `JanetFuncDef *`),
we also store various metadata about the function which is useful for debugging,
as well as constants referenced by the function.
## C Functions
Dst uses C functions to bridge to native code. A C function
(`DstCFunction *` in C) is a C function pointer that can be called like
a normal dst closure. From the perspective of the bytecode instruction set, there is no difference
in invoking a C function and invoking a normal dst function.
Janet uses C functions to bridge to native code. A C function
(`JanetCFunction *` in C) is a C function pointer that can be called like
a normal janet closure. From the perspective of the bytecode instruction set, there is no difference
in invoking a C function and invoking a normal janet function.
## Bytecode Format
Dst bytecode presents an interface to a virtual machine with a large number
of identical registers that can hold any Dst value (`Dst *` in C). Most instructions
Janet bytecode presents an interface to a virtual machine with a large number
of identical registers that can hold any Janet value (`Janet *` in C). Most instructions
have a destination register, and 1 or 2 source register. Registers are simply
named with positive integers.
@ -130,7 +130,7 @@ for an environment, or an unsigned integer.
## Instruction Reference
A listing of all opcode values can be found in src/include/dst/dstopcodes.h. The dst assembly
A listing of all opcode values can be found in src/include/janet/janetopcodes.h. The janet assembly
short names can be found src/assembler/asm.c. In this document, we will refer to the instructions
by their short names as presented to the assembler rather than their numerical values.
@ -150,7 +150,7 @@ failure to return or error.
that these operators correspond to integers or real numbers only, respectively. All
bitwise operators and bit shifts only work with integers.
* The `>>>` indicates unsigned right shift, as in Java. Because all integers in dst are
* The `>>>` indicates unsigned right shift, as in Java. Because all integers in janet are
signed, we differentiate the two kinds of right bit shift.
* The 'im' suffix in the instruction name is short for immediate. The 'i' suffix is short for integer,
@ -170,7 +170,7 @@ failure to return or error.
| `bxor` | `(bxor dest lhs rhs)` | $dest = $lhs ^ $rhs |
| `call` | `(call dest callee)` | $dest = call($callee, args) |
| `clo` | `(clo dest index)` | $dest = closure(defs[$index]) |
| `cmp` | `(cmp dest lhs rhs)` | $dest = dst\_compare($lhs, $rhs) |
| `cmp` | `(cmp dest lhs rhs)` | $dest = janet\_compare($lhs, $rhs) |
| `div` | `(div dest lhs rhs)` | $dest = $lhs / $rhs |
| `divi` | `(divi dest lhs rhs)` | $dest = $lhs /i $rhs |
| `divim` | `(divim dest lhs im)` | $dest = $lhs /i im |