This updates and reformats the doc file for the runtime package. The
list of things that need to be implemented for a compiler runtime to
work has been updated in accordance with recent changes to runtime
(notably `cstring16` and `string16` types and `#load_directory`). Some
copy-paste errors around string-comparison procedures have been fixed.
The file has been renamed to `doc.odin` as per convention, the comment
has been moved to the top of the package declaration and the comment is
now markdown-formatted.
Also wrote down a little map to maybe slightly help with understanding
navigation within package runtime's files and added a few more
explanations as to why that list of declarations exists and how to use
it.
The list of declarations has been detailed to some degree, explaining
under what conditions the declarations are required.
Add `ODIN_PLATFORM_SUBTARGET_IOS` builtin constant which evaluated to
`true` when the platform is `Darwin` and the subtarget it either `iPhone` or `iPhoneSimulator`
It has been discovered that AddressSanitizer does not keep a 1:1 mapping
of which bytes are poisoned and which are not. This can cause issues for
allocations less than 8 bytes and where addresses straddle 8-byte
boundaries.
See the following link for more information:
https://github.com/google/sanitizers/wiki/AddressSanitizerAlgorithm#mapping
`typeid` used to be a fancy index with extra metadata stored on it. Now it is direct hash of the type.
This is safe to do in practice since any possible collisions are checked at compile time AND the chances of having a 1% collision are around 1 in 600K (see the Birthday Paradox).
Therefore accessing a `^Type_Info` is now a hash table lookup with linear probing. The table is twice the size than necessary so prevent too much probing due to an overly dense hash table.
This affects `runtime.Arena` and `virtual.Arena`, but not currently
`mem.Arena`. These changes allow the last allocation that has been
made to be resized to a larger size by just extending their
allocation in-place, when there's sufficient room in the memory block to
do so.
Shrinking in place and re-using the rest of the allocation can be
supported using almost the same logic, but would require the memory to
be zeroed. Since this would add a additional cost that isn't currently
present, shrinking has not been changed.
`map_desired_position` does not return the actual position, probing must
be done afterwards to figure out the real position. `map_entry` did not
do this for the returned key pointer so it could point to the wrong key
if probing was done.
