From 6bd632e03140bd2d810cf56d9ce7e9e0b59d04e5 Mon Sep 17 00:00:00 2001 From: servostar Date: Fri, 11 Oct 2024 16:28:08 +0200 Subject: [PATCH] draft: added specification for module memory --- lib/spec.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 63 insertions(+), 4 deletions(-) diff --git a/lib/spec.md b/lib/spec.md index 6a23a35..7a4db79 100644 --- a/lib/spec.md +++ b/lib/spec.md @@ -8,7 +8,7 @@ | `types` | Commonly used types and aliases in submodules | | `mem` | Memory management for allocations, frees and copy operations | | `os` | Abstractions for common tasks related to the operating system | -| `io` | Basic wrapper for general purpose input/output operations | +| `io` | Basic wrapper for general purpose synchronous input/output operations | | `fs` | File system operations extending functionality of the `io` module | | `net` | Module for networking capabilities | | `vec` | Vector data type implemented as growable array | @@ -16,6 +16,65 @@ ## Bootstrap -require dependency library in source - library name -mark function as external library source +This module contains sources required to boot a program, setup the runtime, libraries and eventually call the `main` function. +Since only applications make use of this boot code it is of no use when compiling a library. +It requires the `main` function to be defined. This function is the start of a gemstone applications and is called after setup with the following signature: +``` +#[nomangle] +fun main() +``` +In contrast to other programming languages such as `C` the main function does not exit with a return value. +In order to exit with a custom code use `std::os::exit()`. + +## Operating System (OS) + +## Memory management (mem) + +This module compiles function for generic memory mangement closely integrated with the host operating system. +Included functionalities are: allocation, copy and clone operations. +This module is built around the idea that memory mangement happens at byte level. +Functions provided by this module are low-level functions for managing buffer of bytes without any considerations of higher abstractions of types. +Thus most functions interact with the folloing unsigned 8-bit integral type: +``` +type unsigned half half: u8 +``` + +### Invalid memory and null pointer + +Gemstone has no pointers. References are conceptually no pointers but behave eqivalent on machine language level. +In constrast to other languages the is no null. However since it is convention that a memory adress of zero is to be considered invalid gemstone will treat any reference of value zero as invalid reference. +This property is used to check validity of references. It should be noted that this is not a fault prove method as the value of a reference can be changed at any point in time. +The following example will set a refernce to a reference to "point" to adress 97: +``` +ref float: myValue = (97 as i32) to ref float +``` + +### Allocation + +Buffers of bytes can be allocated by the operating system with the following `alloc` function: +``` +fun ref u8:alloc(in u32: len) +``` +This function allocates `len` bytes (as a buffers "length") and returns a reference to the buffer. +The buffer is guaranted to be a consecutive field of bytes all initialized to zero. +In case the allocations fails, for whatever reason, the returned reference will be zero (similar to `NULL` or `nullptr` in `C/C++`). +Implementationwise this function should use the standard platforms way of allocating memory from the global processes heap. + +A block of memory allocated with `alloc` can be changed in length with `realloc`: +``` +fun ref u8:realloc(in out ref u8: buf, in u32: len) +``` +This function will reallocate an existing buffer (supplied by `buf`) to a new length and returns a reference to the buffer with the supplied length. +Behaviorwise, the supplied reference to a preexisting buffer will be overwritten to the newly allocated buffer. +The supplied reference and the returned result will be set to zero in case an error occurs. + +Memory can be given back to the operating system with the free function: +``` +fun free(in out ref u8: buf) +``` +This function will give back the memory block specified by `buf`. +The reference supplied is the be considered invalid afterwards as it will be set to zero. + +## Input and Output (IO) + +## Networking (net)