From a8059fa3fdec511d62e66199211a2ebfc020a700 Mon Sep 17 00:00:00 2001
From: Kayne Ruse <kayneruse@gmail.com>
Date: Wed, 7 Jun 2023 03:07:47 +1000
Subject: [PATCH] Write the reffunction API

---
 c-api/toy_reffunction_h.md | 46 ++++++++++++++++++++++++++++++++++++++
 index.md                   |  2 +-
 2 files changed, 47 insertions(+), 1 deletion(-)
 create mode 100644 c-api/toy_reffunction_h.md

diff --git a/c-api/toy_reffunction_h.md b/c-api/toy_reffunction_h.md
new file mode 100644
index 0000000..62e3838
--- /dev/null
+++ b/c-api/toy_reffunction_h.md
@@ -0,0 +1,46 @@
+# toy_reffunction.h
+
+This header defines the structure `Toy_RefFunction`, as well as all of the related utilities.
+
+See [toy_RefString](toy_refstring_h.md) for more information about the reference pattern.
+
+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_RefFunctionAllocatorFn)(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_setRefFunctionAllocatorFn(Toy_RefFunctionAllocatorFn)
+
+This function conforms to and is invoked by Toy's memory API, and generally shouldn't be used.
+
+### Toy_RefFunction* Toy_createRefFunction(const void* data, size_t length)
+
+This function returns a new `Toy_RefFunction`, containing a copy of `data`, or `NULL` on error.
+
+This function also sets the returned `refFunction`'s reference counter to 1.
+
+### void Toy_deleteRefFunction(Toy_RefFunction* refFunction)
+
+This function reduces the `refFunction`'s reference counter by 1 and, if it reaches 0, frees the memory.
+
+### int Toy_countRefFunction(Toy_RefFunction* refFunction)
+
+This function returns the total number of references to `refFunction`, for debugging.
+
+### size_t Toy_lengthRefFunction(Toy_RefFunction* refFunction)
+
+This function returns the length of the underlying bytecode of `refFunction`.
+
+### Toy_RefFunction* Toy_copyRefFunction(Toy_RefFunction* refFunction)
+
+This function increases the reference counter of `refFunction` by 1, before returning the given pointer.
+
+### Toy_RefFunction* Toy_deepCopyRefFunction(Toy_RefFunction* refFunction)
+
+This function behaves identically to `Toy_copyRefFunction`, 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.
+
diff --git a/index.md b/index.md
index e9385d0..f79eab0 100644
--- a/index.md
+++ b/index.md
@@ -81,6 +81,6 @@ print tally(); //3
 * [toy_literal.h](c-api/toy_literal_h.md)
 * [toy_memory.h](c-api/toy_memory_h.md)
 * [toy_parser.h](c-api/toy_parser_h.md)
-* toy_reffunction.h (docs coming soon)
+* [toy_reffunction.h](c-api/toy_reffunction_h.md)
 * [toy_refstring.h](c-api/toy_refstring_h.md)
 * [toy_scope.h](c-api/toy_scope_h.md)