From 9dbdea91f87ea8f158fb22dc238b4ec9a06f9049 Mon Sep 17 00:00:00 2001 From: Akuli Date: Wed, 11 Dec 2024 23:37:00 +0200 Subject: [PATCH] Improve comments of mem.jou (#529) --- stdlib/mem.jou | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/stdlib/mem.jou b/stdlib/mem.jou index 2bbaea02..f5a3f042 100644 --- a/stdlib/mem.jou +++ b/stdlib/mem.jou @@ -2,12 +2,25 @@ # Heap allocations # TODO: write a tutorial about using these and add a link -declare malloc(size: long) -> void* -declare calloc(a: long, b: long) -> void* -declare realloc(ptr: void*, size: long) -> void* -declare free(ptr: void*) -> None +declare malloc(size: long) -> void* # allocate memory +declare calloc(a: long, b: long) -> void* # allocate a*b bytes of memory and zero it +declare realloc(ptr: void*, new_size: long) -> void* # grow/shrink allocated memory +declare free(ptr: void*) -> None # release allocated memory so it can be reused -# TODO: explain what each of these does -declare memset(dest: void*, fill_byte: int, count: long) -> void* -declare memcpy(dest: void*, source: void*, count: long) -> void* -declare memmove(dest: void*, source: void*, count: long) -> void* +# This function fills a memory region with the given byte. +# The most common way use case for this function is zeroing memory: +# +# memset(&foo, 0, sizeof(foo)) +# +declare memset(dest: void*, fill_byte: int, size: long) -> void* + +# These functions copy memory from one place to another. Source and destination +# are of the same size, and pointers to their start are given. +# +# The difference between these two is how they handle overlapping memory. If +# source and destination may overlap, use memmove(). If you know that source +# and destination will never overlap, use memcpy(), because +# - it is a hint to people reading the code that there will be no overlap +# - it may be slightly faster. +declare memcpy(dest: void*, source: void*, size: long) -> void* # copy memory, overlaps are UB +declare memmove(dest: void*, source: void*, size: long) -> void* # copy memory, overlaps are ok