Skip to content

Commit

Permalink
Add godocs and free memory in more places (#35)
Browse files Browse the repository at this point in the history
* 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 <6598971+gmlewis@users.noreply.github.com>
  • Loading branch information
gmlewis authored Jun 18, 2024
1 parent e565f18 commit de6b7b8
Show file tree
Hide file tree
Showing 6 changed files with 215 additions and 87 deletions.
126 changes: 96 additions & 30 deletions env.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
14 changes: 8 additions & 6 deletions example/countvowels/std_main.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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 {
Expand All @@ -52,7 +54,7 @@ func count_vowels_json_output() int32 {
return 0
}

func count_vowels() int32 {
func countVowels() int32 {
input := pdk.Input()

count := 0
Expand Down
8 changes: 5 additions & 3 deletions example/countvowels/tiny_main.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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 {
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion example/reactor/tiny_main.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import (
)

//export read_file
func read_file() {
func readFile() {
name := pdk.InputString()

content, err := os.ReadFile(name)
Expand Down
Loading

0 comments on commit de6b7b8

Please sign in to comment.