From 3c6e791dc00b7adceed11c298750b81fefb5aee4 Mon Sep 17 00:00:00 2001 From: Kayne Ruse Date: Sat, 18 Feb 2023 21:20:03 +1100 Subject: [PATCH] Wrote the refstring docs --- c-api/toy_memory_h.md | 3 ++ c-api/toy_refstring_h.md | 67 ++++++++++++++++++++++++++++++++++++++++ index.md | 2 +- 3 files changed, 71 insertions(+), 1 deletion(-) create mode 100644 c-api/toy_refstring_h.md diff --git a/c-api/toy_memory_h.md b/c-api/toy_memory_h.md index 5dbdaae..3af2c11 100644 --- a/c-api/toy_memory_h.md +++ b/c-api/toy_memory_h.md @@ -65,3 +65,6 @@ This function wraps a call to the internal assigned memory allocator. ### void Toy_setMemoryAllocator(Toy_MemoryAllocatorFn) This function sets the memory allocator, replacing the default memory allocator. + +This function also overwrites any given refstring memory allocator, see [toy_refstring.h](toy_refstring_h.md). + diff --git a/c-api/toy_refstring_h.md b/c-api/toy_refstring_h.md new file mode 100644 index 0000000..6e43356 --- /dev/null +++ b/c-api/toy_refstring_h.md @@ -0,0 +1,67 @@ +# toy_refstring.h + +This header defines the `Toy_RefString` structure, as well as all of the related utilities. + +[refstring](https://github.com/Ratstail91/refstring) is a stand-alone utility written to reduce the amount of memory manipulation used within Toy. It was independantly written and tested, before being incorporated into Toy proper. As such it has it's own memory management API, which by default is tied into Toy's [core memory API](toy_memory_h.md). + +Instances of `Toy_RefString` are reference counted - that is, rather than copying an existing string in memory, a pointer to the refstring is returned, and the internal reference counter is increased by 1. When the pointer is no longer needed, `Toy_DeleteRefString` can be called; this will decrement the internal reference counter by 1, and only free it when it reaches 0. This has multiple benefits, when used correctly: + +* Reduced memory usage +* Faster program execution + +This module reserves the right to instead preform a deep copy when it sees fit (this is for future debugging purposes). + +## Defined Interfaces + +### typedef void* (*Toy_RefStringAllocatorFn)(void* pointer, size_t oldSize, size_t newSize) + +This interface conforms to Toy's memory API, and generally shouldn't be used. + +## Defined Functions + +### void Toy_setRefStringAllocatorFn(Toy_RefStringAllocatorFn) + +This function conforms to and is invoked by Toy's memory API, and generally shouldn't be used. + +### Toy_RefString* Toy_createRefString(const char* cstring) + +This function wraps `Toy_CreateRefStringLength`, by determining the length of the given `cstring` and passing it to the other function. + +### Toy_RefString* Toy_createRefStringLength(const char* cstring, size_t length) + +This function returns a new `Toy_RefString`, containing a copy of `cstring`, or `NULL` on error. + +This function also sets the returned refstring's reference counter to 1. + +### void Toy_deleteRefString(Toy_RefString* refString) + +This function reduces the `refString`'s reference counter by 1 and, if it reaches 0, frees the memory. + +### int Toy_countRefString(Toy_RefString* refString) + +This function returns the total number of references to `refString`, for debugging. + +### size_t Toy_lengthRefString(Toy_RefString* refString) + +This function returns the length of the underlying cstring of `refString`. + +### Toy_RefString* Toy_copyRefString(Toy_RefString* refString) + +This function increases the reference counter of `refString` by 1, before returning the given pointer. + +### Toy_RefString* Toy_deepCopyRefString(Toy_RefString* refString) + +This function behaves identically to `Toy_copyRefString`, except that it explicitly preforms a deep copy of the internal memory. Using this function should be done carefully, as it incurs a performance penalty that negates the benefit of this module. + +### const char* Toy_toCString(Toy_RefString* refString) + +This function exposes the interal cstring of `refString`. Only use this function when dealing with external APIs. + +### bool Toy_equalsRefString(Toy_RefString* lhs, Toy_RefString* rhs) + +This function returns true when the two refstrings are either the same refstring, or contain the same value. Otherwise it returns false. + +### bool Toy_equalsRefStringCString(Toy_RefString* lhs, char* cstring) + +This function returns true when the `refString` contains the same value as the `cstring`. Otherwise it returns false. + diff --git a/index.md b/index.md index 8c15365..09f97f4 100644 --- a/index.md +++ b/index.md @@ -71,6 +71,6 @@ print tally(); //3 * [toy_literal.h] * [toy_memory.h](c-api/toy_memory_h.md) * [toy_parser.h](c-api/toy_parser_h.md) -* [toy_refstring.h] +* [toy_refstring.h](c-api/toy_refstring_h.md) * [toy_scope.h]