Skip to content

WIP: Switch to markdown and fix code blocks #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 14 commits into
base: master
Choose a base branch
from
Prev Previous commit
Next Next commit
fix all figures
  • Loading branch information
BuonOmo committed Apr 18, 2021
commit b1229c08132a501cb4e1578bd34037c815c1f374
18 changes: 8 additions & 10 deletions anyeval.md
Original file line number Diff line number Diff line change
@@ -503,11 +503,11 @@ It means, it would look like Figure 1. Now, it is assured that
we can refer to the block local variables of the outside scope
from inside of a string to `eval`.

<figure>
<img src="images/ch_anyeval_dynavars.jpg" alt="figure 1: `ruby_dyna_vars` inside `eval`">
<figcaption>figure 1: <code class="inline">ruby_dyna_vars</code> inside <code class="inline">eval</code></figcaption>
</figure>

<div class="image">
<img src="images/ch_anyeval_dynavars.jpg" alt="(dynavars)"><br>
Figure 1: `ruby_dyna_vars` inside `eval`
</div>


Well, it's sure we can refer to,
@@ -590,12 +590,10 @@ that part is defined as `specific_eval()`.
Figure 2 shows it and also what will be described.
What with parentheses are calls by function pointers.


<p class="image">
<img src="images/ch_anyeval_speceval.jpg" alt="(speceval)"><br>
Figure 2: Call Graph
</p>

<figure>
<img src="images/ch_anyeval_speceval.jpg" alt="figure 2: Call Graph">
<figcaption>figure 2: Call Graph</figcaption>
</figure>

Whichever `instance_eval` or `module_eval`,
it can accept both a block and a string,
2 changes: 1 addition & 1 deletion class.md
Original file line number Diff line number Diff line change
@@ -664,7 +664,7 @@ vertical direction is inheritance (the superclasses are above).

<figure>
<img src="images/ch_class_addsclass.png" alt="figure 1: `rb_singleton_class`">
<figcaption>figure 1: `rb_singleton_class`</figcaption>
<figcaption>figure 1: <code class="inline">rb_singleton_class</code></figcaption>
</figure>

When comparing the first and last part of this diagram, you can
4 changes: 2 additions & 2 deletions contextual.md
Original file line number Diff line number Diff line change
@@ -177,7 +177,7 @@ which case suits best (see image 1)

<figure>
<img src="images/ch_contextual_transittobeg.jpg" alt="figure 1: Transition to `EXPR_BEG`">
<figcaption>figure 1: Transition to `EXPR_BEG`</figcaption>
<figcaption>figure 1: Transition to <code class="inline">EXPR_BEG</code></figcaption>
</figure>

((errata:<br>
@@ -1161,7 +1161,7 @@ will appear from `tLPAREN_ARG` and conflict with `method_call` (see image 3)

<figure>
<img src="images/ch_contextual_trees.jpg" alt="figure 3: `method_call` and `command_call`">
<figcaption>figure 3: `method_call` and `command_call`</figcaption>
<figcaption>figure 3: <code class="inline">method_call</code> and <code class="inline">command_call</code></figcaption>
</figure>

### The case of two parameters and more
54 changes: 20 additions & 34 deletions evaluator.md
Original file line number Diff line number Diff line change
@@ -807,24 +807,19 @@ The ordinary functions return only once for each call.
However, it's possible `setjmp()` returns twice.
Is it helpful to grasp the concept if I say that it is something like `fork()`?



<p class="image">TODO
<img src="images/ch_evaluator_setjmp.jpg" alt="(setjmp)"><br>
Fig.2: `setjmp()` `longjmp()` Image
</p>

<figure>
<img src="images/ch_evaluator_setjmp.jpg" alt="figure 2: `setjmp()` `longjmp()` Image">
<figcaption>figure 2: <code class="inline">setjmp()</code> <code class="inline">longjmp()</code> Image</figcaption>
</figure>

Now, we've learned about `setjmp()` as a preparation.
In `eval.c`, `EXEC_TAG` corresponds to `setjmp()` and `JUMP_TAG()` corresponds
to `longjmp()` respectively. (Fig.3)


<p class="image">
<img src="images/ch_evaluator_jumptag.jpg" alt="(jumptag)"><br>
Fig.3: "tag jump" image
</p>

<figure>
<img src="images/ch_evaluator_jumptag.jpg" alt="figure 3: &quot;tag jump&quot; image">
<figcaption>figure 3: "tag jump" image</figcaption>
</figure>

Take a look at this image, it seems that `EXEC_TAG()` does not have any arguments.
Where has `jmp_buf` gone?
@@ -905,12 +900,10 @@ and its cost of the memory allocation is next to nothing.
This technique is only possible because the `ruby` evaluator is made of
recursive calls of `rb_eval()`.



<p class="image">
<img src="images/ch_evaluator_tagstack.jpg" alt="(tagstack)"><br>
Fig.4: the tag stack is embedded in the machine stack
</p>
<figure>
<img src="images/ch_evaluator_tagstack.jpg" alt="figure 4: the tag stack is embedded in the machine stack">
<figcaption>figure 4: the tag stack is embedded in the machine stack</figcaption>
</figure>


Because of this implementation, it's necessary that `PUSH_TAG` and `POP_TAG`
@@ -948,11 +941,10 @@ After that, it executes the main body by calling `rb_eval()`
recursively. If there's `break` or `next`, it does `JUMP_TAG()` (`longjmp`).
Then, it can go back to the start point of the `while` loop. (Fig.5)


<p class="image">TODO
<img src="images/ch_evaluator_whilejmp.jpg" alt="(whilejmp)"><br>
Fig.5: the implementation of `while` by using "tag jump"
</p>
<figure>
<img src="images/ch_evaluator_whilejmp.jpg" alt="figure 5: the implementation of `while` by using &quot;tag jump&quot;">
<figcaption>figure 5: the implementation of <code class="inline">while</code> by using "tag jump"</figcaption>
</figure>


Though `break` was taken as an example here, what cannot be implemented without
@@ -1260,18 +1252,12 @@ the return value can be passed to the next tag without particular thought.
```



This can probably be depicted as Fig.6.


<p class="image">
<img src="images/ch_evaluator_usetag.jpg" alt="(usetag)"><br>
Fig.6: Transferring the return value
</p>




<figure>
<img src="images/ch_evaluator_usetag.jpg" alt="figure 6: Transferring the return value">
<figcaption>figure 6: Transferring the return value</figcaption>
</figure>


Exception
4 changes: 2 additions & 2 deletions gc.md
Original file line number Diff line number Diff line change
@@ -431,7 +431,7 @@ Each element of `heap` is each `slot` (Figure 9).

<figure>
<img src="images/ch_gc_heapitems.jpg" alt="figure 9: `heaps`, `heap`, `slot`">
<figcaption>figure 9: `heaps`, `heap`, `slot`</figcaption>
<figcaption>figure 9: <code class="inline">heaps</code>, <code class="inline">heap</code>, <code class="inline">slot</code></figcaption>
</figure>

The length of `heaps` is `heap_length` and it can be changed. The number of
@@ -441,7 +441,7 @@ Figure 10 shows the structure of the object heap.

<figure>
<img src="images/ch_gc_heaps.jpg" alt="figure 10: conceptual diagram of `heaps` in memory">
<figcaption>figure 10: conceptual diagram of `heaps` in memory</figcaption>
<figcaption>figure 10: conceptual diagram of <code class="inline">heaps</code> in memory</figcaption>
</figure>

This structure has a necessity to be this way.
2 changes: 1 addition & 1 deletion intro.md
Original file line number Diff line number Diff line change
@@ -965,7 +965,7 @@ it would be like Figure 1.

<figure>
<img src="images/ch_abstract_build.jpg" alt="figure 1: The process until `Makefile` is created">
<figcaption>figure 1: The process until `Makefile` is created</figcaption>
<figcaption>figure 1: The process until <code class="inline">Makefile</code> is created</figcaption>
</figure>

For the readers who want to know more details,
6 changes: 3 additions & 3 deletions iterator.md
Original file line number Diff line number Diff line change
@@ -147,7 +147,7 @@ It's possible that the block is pushed for the previous method. (Figure 1)

<figure>
<img src="images/ch_iterator_stacks.jpg" alt="figure 1: no one-to-one correspondence between `FRAME` and `BLOCK`">
<figcaption>figure 1: no one-to-one correspondence between `FRAME` and `BLOCK`</figcaption>
<figcaption>figure 1: no one-to-one correspondence between <code class="inline">FRAME</code> and <code class="inline">BLOCK</code></figcaption>
</figure>


@@ -666,7 +666,7 @@ If we focus on there, we can see a link is always pushed in at the "next" to

<figure>
<img src="images/ch_iterator_dynavarseval.jpg" alt="figure 4: the structure of `ruby_dyna_vars`">
<figcaption>figure 4: the structure of `ruby_dyna_vars`</figcaption>
<figcaption>figure 4: the structure of <code class="inline">ruby_dyna_vars</code></figcaption>
</figure>


@@ -794,7 +794,7 @@ Therefore, if `0x10` did not exist, `state` would be the same value as `TAG_xxxx

<figure>
<img src="images/ch_iterator_dst.jpg" alt="figure 6: `block->tag->dst`">
<figcaption>figure 6: `block->tag->dst`</figcaption>
<figcaption>figure 6: <code class="inline">block->tag->dst</code></figcaption>
</figure>


19 changes: 9 additions & 10 deletions load.md
Original file line number Diff line number Diff line change
@@ -449,10 +449,10 @@ returned back to the thread where it was called. When the file name
disappears from `loading_tbl`, the loading is finished so the function
can end. The `curr_thread` check is not to lock itself (figure 1).

<div class="image">
<img src="images/ch_load_loadwait.jpg" alt="(loadwait)"><br>
Figure 1: Serialisation of loads
</div>
<figure>
<img src="images/ch_load_loadwait.jpg" alt="figure 1: Serialisation of loads">
<figcaption>figure 1: Serialisation of loads</figcaption>
</figure>

Loading of Ruby programs
------------------------
@@ -808,13 +808,12 @@ entirely, and connecting them each other.
In other words, pulling the lines from all of "the necessary names",
each line must be connected to one of "the providing names" of a particular
object file. (Figure. 2)
To put this in technical terms,
it is resolving undefined symbols.
To put this in technical terms, it is resolving undefined symbols.

<div class="image">
<img src="images/ch_load_link.jpg" alt="(link)"><br>
Figure 2: object files and linking
</div>
<figure>
<img src="images/ch_load_link.jpg" alt="figure 2: object files and linking">
<figcaption>figure 2: object files and linking</figcaption>
</figure>

Logically this is how it is, but in reality a program can't run only because of
this. At least, C programs cannot run without converting the names to the
2 changes: 1 addition & 1 deletion minimum.md
Original file line number Diff line number Diff line change
@@ -1116,7 +1116,7 @@ call `puts` and `p` also at the toplevel.

<figure>
<img src="images/ch_minimum_Kernel.jpg" alt="figure 10: `main`, `Object` and `Kernel`">
<figcaption>figure 10: `main`, `Object` and `Kernel`</figcaption>
<figcaption>figure 10: <code class="inline">main</code>, <code class="inline">Object</code> and <code class="inline">Kernel</code></figcaption>
</figure>

Thus `p` isn't a function, it's a method. Just because
84 changes: 36 additions & 48 deletions module.md
Original file line number Diff line number Diff line change
@@ -43,11 +43,10 @@ consequence. This is why,
even if a procedure is called anytime and any number of times,
we only have to write its code once (Fig. 1).


<p class="image">
<img src="images/ch_module_stack.jpg" alt="(stack)"><br>
Fig.1: What is changing is only the stack
</p>
<figure>
<img src="images/ch_module_stack.jpg" alt="figure 1: What is changing is only the stack">
<figcaption>figure 1: What is changing is only the stack</figcaption>
</figure>


The execution of Ruby is also basically nothing but chained calls of methods
@@ -141,11 +140,10 @@ general noun and `FRAME` when it means `struct FRAME`.
First af all, since there's the `prev` member, you can infer that the stack is
made of a linked list. (Fig.2)


<p class="image">
<img src="images/ch_module_framestack.jpg" alt="(framestack)"><br>
Fig.2: `ruby_frame`
</p>
<figure>
<img src="images/ch_module_framestack.jpg" alt="figure 2: `ruby_frame`">
<figcaption>figure 2: <code class="inline">ruby_frame</code></figcaption>
</figure>


The fact that `ruby_xxxx` points to the top stack frame is common to all stacks
@@ -390,13 +388,10 @@ The break between blocks are similar to the one of the parser,
it is expressed by a `RVarmap` (header) whose `id` is `0`.
Details are deferred again. It will be explained in Chapter 16: Blocks.


<p class="image">
<img src="images/ch_module_vars.jpg" alt="(vars)"><br>
Fig.3: `ruby_dyna_vars`
</p>


<figure>
<img src="images/ch_module_vars.jpg" alt="figure 3: `ruby_dyna_vars`">
<figcaption>figure 3: <code class="inline">ruby_dyna_vars</code></figcaption>
</figure>


### `ruby_class`
@@ -468,10 +463,10 @@ end

Fig.4 shows how `ruby_cref` is when evaluating the code (A).

<p class="image">
<img src="images/ch_module_crefstack.jpg" alt="(crefstack)"><br>
Fig.4: `ruby_cref`
</p>
<figure>
<img src="images/ch_module_crefstack.jpg" alt="figure 4: `ruby_cref`">
<figcaption>figure 4: <code class="inline">ruby_cref</code></figcaption>
</figure>


However, illustrating this image everytime is tedious and its intention becomes unclear.
@@ -866,11 +861,10 @@ machine stack. What differentiate slightly is that the spaces of the stack
frames are allocated in the heap, the machine stack is used in order to create
the stack structure (Fig.5.).


<p class="image">
<img src="images/ch_module_scopestack.jpg" alt="(scopestack)"><br>
Fig.5. The machine stack and the SCOPE Stack
</p>
<figure>
<img src="images/ch_module_scopestack.jpg" alt="figure 5: The machine stack and the SCOPE Stack">
<figcaption>figure 5: The machine stack and the SCOPE Stack</figcaption>
</figure>


Additionally, the flags like `SCOPE_` something repeatedly appearing in the
@@ -923,11 +917,10 @@ Because they are confusing, it's a good thing writing some comments such as
"This is the variable name", "this is the value".
The one with `tbl` is for the names.


<p class="image">
<img src="images/ch_module_localvars.jpg" alt="(localvars)"><br>
Fig.6. `ruby_scope->local_vars`
</p>
<figure>
<img src="images/ch_module_localvars.jpg" alt="figure 6: `ruby_scope->local_vars`">
<figcaption>figure 6: <code class="inline">ruby_scope->local_vars</code></figcaption>
</figure>


Where is this `node` used?
@@ -1057,11 +1050,10 @@ However, the arguments of a method are obviously `VALUE` s and
the GC could not find a `VALUE` if it is stored in the heap.
Therefore, it is enforced that GC can find it through `NODE`.


<p class="image">
<img src="images/ch_module_tmpprotecttmp.jpg" alt="(tmpprotecttmp)"><br>
Fig.7. anchor the space to the stack through `NODE`
</p>
<figure>
<img src="images/ch_module_tmpprotecttmp.jpg" alt="figure 7: anchor the space to the stack through `NODE`">
<figcaption>figure 7: anchor the space to the stack through <code class="inline">NODE</code></figcaption>
</figure>


On the contrary, in the environment with the true `alloca()`, we can naturally
@@ -1667,14 +1659,10 @@ and insert into the just pushed `ruby_frame->cbase` (Fig.84)

... This is the mechanism. Complicated.



<p class="image">
<img src="images/ch_module_cbase.jpg" alt="(cbase)"><br>
Fig 8. CREF Trasfer
</p>


<figure>
<img src="images/ch_module_cbase.jpg" alt="figure 8: CREF Transfer">
<figcaption>figure 8: CREF Transfer</figcaption>
</figure>


#### `ev_const_get()`
@@ -2033,10 +2021,10 @@ So, what it is doing here is adjusting to either `list` and `val` which is
shorter and doing one-to-one assignments. (Fig.9)


<p class="image">
<img src="images/ch_module_massign.jpg" alt="(massign)"><br>
Fig.9. assign when corresponded
</p>
<figure>
<img src="images/ch_module_massign.jpg" alt="figure 9: assign when corresponded">
<figcaption>figure 9: assign when corresponded</figcaption>
</figure>


(B) if there are remainders on the right-hand side, turn them into a Ruby
Loading