Add godocs and free memory in more places (#35)

* Add more detailed documentation * Add godocs * Address review feedback * Free allocated memory for output functions * Revert change * Remove backticks from function name godocs --------- Signed-off-by: Glenn Lewis <[email protected]>
extism · Jun 18, 2024 · de6b7b8 · de6b7b8
1 parent e565f18
commit de6b7b8
Show file tree

Hide file tree

Showing 6 changed files with 215 additions and 87 deletions.
diff --git a/env.go b/env.go
@@ -2,78 +2,144 @@ package pdk
 
 type extismPointer uint64
 
+// extismInputLength returns the number of bytes provided by the host via its input methods.
+//
 //go:wasmimport extism:host/env input_length
-func extism_input_length() uint64
+func extismInputLength() uint64
 
+// extismLength returns the number of bytes associated with the block of host memory
+// located at `offset`.
+//
 //go:wasmimport extism:host/env length
-func extism_length(extismPointer) uint64
+func extismLength(offset extismPointer) uint64
 
 //go:wasmimport extism:host/env length_unsafe
-func extism_length_unsafe(extismPointer) uint64
+func extismLengthUnsafe(extismPointer) uint64
 
+// extismAlloc allocates `length` bytes of data with host memory for use by the plugin
+// and returns its offset within the host memory block.
+//
 //go:wasmimport extism:host/env alloc
-func extism_alloc(uint64) extismPointer
+func extismAlloc(length uint64) extismPointer
 
+// extismFree releases the bytes previously allocated with `extism_alloc` at the given `offset`.
+//
 //go:wasmimport extism:host/env free
-func extism_free(extismPointer)
+func extismFree(offset extismPointer)
 
+// extismInputLoadU8 returns the byte at location `offset` of the "input" data from the host.
+//
 //go:wasmimport extism:host/env input_load_u8
-func extism_input_load_u8_(extismPointer) uint32
-
-func extism_input_load_u8(p extismPointer) uint8 {
-	return uint8(extism_input_load_u8_(p))
+func extismInputLoadU8_(offset extismPointer) uint32
+func extismInputLoadU8(offset extismPointer) uint8 {
+	return uint8(extismInputLoadU8_(offset))
 }
 
+// extismInputLoadU64 returns the 64-bit unsigned integer of the "input" data from the host.
+// Note that `offset` must lie on an 8-byte boundary.
+//
 //go:wasmimport extism:host/env input_load_u64
-func extism_input_load_u64(extismPointer) uint64
+func extismInputLoadU64(offset extismPointer) uint64
 
+// extismOutputSet sets the "output" data from the plugin to the host to be the memory that
+// has been written at `offset` with the given `length`.
+// The memory can be immediately freed because the host makes a copy for its use.
+//
 //go:wasmimport extism:host/env output_set
-func extism_output_set(extismPointer, uint64)
+func extismOutputSet(offset extismPointer, length uint64)
 
+// extismErrorSet sets the "error" data from the plugin to the host to be the memory that
+// has been written at `offset`.
+// The memory can be immediately freed because the host makes a copy for its use.
+//
 //go:wasmimport extism:host/env error_set
-func extism_error_set(extismPointer)
+func extismErrorSet(offset extismPointer)
 
+// extismConfigGet returns the host memory block offset for the "config" data associated with
+// the key which is represented by the UTF-8 string which as been previously written at `offset`.
+// The memory for the key can be immediately freed because the host has its own copy.
+//
 //go:wasmimport extism:host/env config_get
-func extism_config_get(extismPointer) extismPointer
+func extismConfigGet(offset extismPointer) extismPointer
 
+// extismVarGet returns the host memory block offset for the "var" data associated with
+// the key which is represented by the UTF-8 string which as been previously written at `offset`.
+// The memory for the key can be immediately freed because the host has its own copy.
+//
 //go:wasmimport extism:host/env var_get
-func extism_var_get(extismPointer) extismPointer
-
+func extismVarGet(offset extismPointer) extismPointer
+
+// extismVarSet sets the host "var" memory keyed by the UTF-8 string located at `offset`
+// to be the value which has been previously written at `valueOffset`.
+//
+// A `valueOffset` of 0 causes the old value associated with this key to be freed on the host
+// and the association to be completely removed.
+//
+// The memory for the key can be immediately freed because the host has its own copy.
+// The memory for the value, however, should not be freed, as that erases the value from the host.
+//
 //go:wasmimport extism:host/env var_set
-func extism_var_set(extismPointer, extismPointer)
+func extismVarSet(offset, valueOffset extismPointer)
 
+// extismStoreU8 stores the byte `v` at location `offset` in the host memory block.
+//
 //go:wasmimport extism:host/env store_u8
-func extism_store_u8_(extismPointer, uint32)
-func extism_store_u8(p extismPointer, v uint8) {
-	extism_store_u8_(p, uint32(v))
+func extismStoreU8_(extismPointer, uint32)
+func extismStoreU8(offset extismPointer, v uint8) {
+	extismStoreU8_(offset, uint32(v))
 }
 
+// extismLoadU8 returns the byte located at `offset` in the host memory block.
+//
 //go:wasmimport extism:host/env load_u8
-func extism_load_u8_(extismPointer) uint32
-func extism_load_u8(p extismPointer) uint8 {
-	return uint8(extism_load_u8_(p))
+func extismLoadU8_(offset extismPointer) uint32
+func extismLoadU8(offset extismPointer) uint8 {
+	return uint8(extismLoadU8_(offset))
 }
 
+// extismStoreU64 stores the 64-bit unsigned integer value `v` at location `offset` in the host memory block.
+// Note that `offset` must lie on an 8-byte boundary.
+//
 //go:wasmimport extism:host/env store_u64
-func extism_store_u64(extismPointer, uint64)
+func extismStoreU64(offset extismPointer, v uint64)
 
+// extismLoadU64 returns the 64-bit unsigned integer at location `offset` in the host memory block.
+// Note that `offset` must lie on an 8-byte boundary.
+//
 //go:wasmimport extism:host/env load_u64
-func extism_load_u64(extismPointer) uint64
+func extismLoadU64(offset extismPointer) uint64
 
+// extismHTTPRequest sends the HTTP `request` to the Extism host with the provided `body` (0 means no body)
+// and returns back the memory offset to the response body.
+//
 //go:wasmimport extism:host/env http_request
-func extism_http_request(extismPointer, extismPointer) extismPointer
+func extismHTTPRequest(request, body extismPointer) extismPointer
 
+// extismHTTPStatusCode returns the status code for the last-sent `extism_http_request` call.
+//
 //go:wasmimport extism:host/env http_status_code
-func extism_http_status_code() int32
+func extismHTTPStatusCode() int32
 
+// extismLogInfo logs an "info" string to the host from the previously-written UTF-8 string written to `offset`.
+// Note that the memory at `offset` can be immediately freed because it is immediately logged.
+//
 //go:wasmimport extism:host/env log_info
-func extism_log_info(extismPointer)
+func extismLogInfo(offset extismPointer)
 
+// extismLogDebug logs a "debug" string to the host from the previously-written UTF-8 string written to `offset`.
+// Note that the memory at `offset` can be immediately freed because it is immediately logged.
+//
 //go:wasmimport extism:host/env log_debug
-func extism_log_debug(extismPointer)
+func extismLogDebug(offset extismPointer)
 
+// extismLogWarn logs a "warning" string to the host from the previously-written UTF-8 string written to `offset`.
+// Note that the memory at `offset` can be immediately freed because it is immediately logged.
+//
 //go:wasmimport extism:host/env log_warn
-func extism_log_warn(extismPointer)
+func extismLogWarn(offset extismPointer)
 
+// extismLogError logs an "error" string to the host from the previously-written UTF-8 string written to `offset`.
+// Note that the memory at `offset` can be immediately freed because it is immediately logged.
+//
 //go:wasmimport extism:host/env log_error
-func extism_log_error(extismPointer)
+func extismLogError(offset extismPointer)
diff --git a/example/countvowels/std_main.go b/example/countvowels/std_main.go
@@ -14,23 +14,25 @@ import (
 // `_start` via WASI. So, `main` functions should contain the plugin behavior, that the host will
 // invoke by explicitly calling `_start`.
 func main() {
-	count_vowels()
-	count_vowels_typed()
-	count_vowels_json_output()
+	countVowels()
+	countVowelsTyped()
+	countVowelsJSONOutput()
 }
 
+// CountVowelsInput represents the JSON input provided by the host.
 type CountVowelsInput struct {
 	Input string `json:"input"`
 }
 
+// CountVowelsOutput represents the JSON output sent to the host.
 type CountVowelsOuptut struct {
 	Count  int    `json:"count"`
 	Total  int    `json:"total"`
 	Vowels string `json:"vowels"`
 }
 
 //export count_vowels_typed
-func count_vowels_typed() int32 {
+func countVowelsTyped() int32 {
 	var input CountVowelsInput
 	if err := pdk.InputJSON(&input); err != nil {
 		pdk.SetError(err)
@@ -42,7 +44,7 @@ func count_vowels_typed() int32 {
 }
 
 //export count_vowels_json_output
-func count_vowels_json_output() int32 {
+func countVowelsJSONOutput() int32 {
 	output := CountVowelsOuptut{Count: 42, Total: 2.1e7, Vowels: "aAeEiIoOuUyY"}
 	err := pdk.OutputJSON(output)
 	if err != nil {
@@ -52,7 +54,7 @@ func count_vowels_json_output() int32 {
 	return 0
 }
 
-func count_vowels() int32 {
+func countVowels() int32 {
 	input := pdk.Input()
 
 	count := 0

diff --git a/example/countvowels/tiny_main.go b/example/countvowels/tiny_main.go
@@ -9,18 +9,20 @@ import (
 	"github.com/extism/go-pdk"
 )
 
+// CountVowelsInput represents the JSON input provided by the host.
 type CountVowelsInput struct {
 	Input string `json:"input"`
 }
 
+// CountVowelsOutput represents the JSON output sent to the host.
 type CountVowelsOuptut struct {
 	Count  int    `json:"count"`
 	Total  int    `json:"total"`
 	Vowels string `json:"vowels"`
 }
 
 //export count_vowels_typed
-func count_vowels_typed() int32 {
+func countVowelsTyped() int32 {
 	var input CountVowelsInput
 	if err := pdk.InputJSON(&input); err != nil {
 		pdk.SetError(err)
@@ -32,7 +34,7 @@ func count_vowels_typed() int32 {
 }
 
 //export count_vowels_json_output
-func count_vowels_json_output() int32 {
+func countVowelsJSONOutput() int32 {
 	output := CountVowelsOuptut{Count: 42, Total: 2.1e7, Vowels: "aAeEiIoOuUyY"}
 	err := pdk.OutputJSON(output)
 	if err != nil {
@@ -43,7 +45,7 @@ func count_vowels_json_output() int32 {
 }
 
 //export count_vowels
-func count_vowels() int32 {
+func countVowels() int32 {
 	input := pdk.Input()
 
 	count := 0

diff --git a/example/reactor/tiny_main.go b/example/reactor/tiny_main.go
@@ -11,7 +11,7 @@ import (
 )
 
 //export read_file
-func read_file() {
+func readFile() {
 	name := pdk.InputString()
 
 	content, err := os.ReadFile(name)