dymokomi/luce-browser-foundation
Source of release 0.6.1
0.6.1 / docs / regions / r01.md
# Region r01: AK core (`ak`) — what other regions need to know
Region r01 ports AK's allocation, assertions, numeric helpers, Checked, Math, FixedPoint,
UFixedBigInt, Vector, HashTable, HashMap, the iterators, Function, Error, Time, the smart pointers,
atomics, bitmaps, sorting, Optional, ByteBuffer, the streams, CircularBuffer, LEB128, and the
lists, trees and queues. Each fragment's header describes it, and `docs/namemap.tsv` lists every
name. The stub fragments `ak/stub_r01_ak_core.lucb` and `gc/stub_r01_ak_core.lucb` are gone.
## Signature and type changes against the skeleton
### Imports
- Module-wide imports live in `ak/module.lucb`: `io`, `memory`, `Allocator`, `luce`, `os`, `math`,
`math32`, `atomic as atomics`, `thread` and `testing`. A fragment may not import any of these
again.
### Allocation
- The allocation hook of DESIGN.md §3.3 and §4.1.1: `ak.atomic_allocator` is a `local var` of type
`Allocator?` that gc installs. `kmalloc_atomic` and `alloc_atomic` use it.
- `kmalloc`, `kfree` and `krealloc` allocate from the current allocator with a size header.
- `vector_create_atomic[T]()` makes a Vector whose buffer is atomic storage.
### Arithmetic templates
Generics cannot do arithmetic, so arithmetic templates are suffixed per type:
- `ceil_div_usize`, `saturating_add_i32`, `exp2_usize`, `sqrt_f64`, `clamp_to_i32_f64`, …;
- Checked: `checked_add_usize`, `add_i64`, the generic `checked_value(&c)`, `is_within_range_u32`;
- NumericLimits are constants (`i32_max`, `f64_epsilon`);
- `min`, `max` and `clamp` are generic over Comparable; `min_f64` and friends use `<` so that NaN
behaves as in C++.
### Callbacks
- Predicates and callbacks are `FunctionN` values. `function1_call`, `functionN_is_set` and
`functionN_clear` are added.
- Generic callbacks must be static methods of generic structs.
### Vector
- `vector_span(&v)` is what `for` walks.
- `vector_at` answers `T*`; `vector_get` answers `T*?`.
- The struct gained `m_atomic` and conforms to `IndexedContainer[T]`.
- `vector_clone` is the copy constructor and `vector_move_assign` the move assignment.
- The moving overloads (`vector_extend`, `vector_prepend_vector`) take `Vector[T]*` and empty the
source.
### HashTable and HashMap
- HashTable has `m_mask`, `m_head`/`m_tail` and `m_ordered`; every bucket has links and a stored
hash.
- OrderedHashTable wraps a HashTable; OrderedHashMap is used through `ordered_hash_map_*` and
`ordered_hash_table_*`.
- Iterators are `HashTableIterator[T]`, which `for` walks.
- `hash_map_get_k` answers `V*?`, `hash_map_take_k` answers `V?`, and `hash_map_clone` is fallible.
- Hash-compatible lookups take `HashCompatibleTraits[T, K]`.
- BucketState is `as u8`.
### Traits
- The integer traits are filled in; PtrTraits uses `ptr_hash`.
- `traits.lucb` adds U8, U16, I8, I16, Usize, Isize, Bool, Char, F32, F64 and IdentityHashTraits.
- FlyString, String and Utf16String traits are r02's. DefaultTraits still traps.
### Errors
- A string-literal ErrorOr failure is `error(ak_error, "…")`.
- errno and syscall errors are `ak_error_throw(ak_error_from_errno(code))`, which stores the error
in `ak_pending_error` and fails with `ak_errno_error`. `ak_error_from_failure(failure)` recovers
the AkError.
- errno constants: `enomem`, `einval`, `enoent`, `eintr`, `ebadf`, and the functions `eagain()`,
`enotconn()` and `emsgsize()`.
### Assertions
- Messages are `str`. `custom_assertion_handler` replaces the donor's weak symbol.
### Types fixed by hand
Many `types_*.lucb` declarations were fixed by hand (noted in their headers):
- the Types of every header;
- iterator types take the element type as their only parameter;
- ByteBuffer's inline storage is restored;
- the stream vtables answer `usize!`;
- FixedPoint is `[TUnderlying, TPrecision]`;
- `types_external`'s Timespec and Timeval, and `types_big_int_base`'s IntegerWrapper.
Placeholder `void*?` stub signatures were given real types, keeping their namemap names.
Intrusive containers take a `member: usize` offset.
### For gc (r04)
- `weakable_make_weak_ptr` (in gc, the new `gc/weakable.lucb`) stored an `ak.WeakLink*` in
`Weak.m_impl`. See `INTEGRATION.md` for how this was reconciled with r04's Weak.
## Deviations from the donor
- The inline capacity of Vector and friends, the node caches and the fast last-access paths are
dropped.
- Reference counts are kept faithfully, but nothing is ever freed.
- Variant's parameter-pack functions trap.
- Per-architecture branches take the AArch64/libm branch, using luce-std math and `rint`.
- Donor bug kept: `Bitmap::find_best_fit` never terminates on a bitmap shorter than 64 bits; the
test avoids it.
## Compiler issues
- `generic_function_value`, `float_bits_through_pointer` and `generic_sizeof_branch` (all in
luce-js/docs/COMPILER-REQUESTS.md) are fixed in Luce 0.8.13 and their workarounds removed. A
callback whose function type does not mention every type parameter (a traits type, as in
HashMapKeyEquals) is still a static method of its captures: a generic function value takes its
type arguments from the expected function type only;
- `luce-base check -W` exits 0 on warnings, so `test.sh` fails on any output.