Class: Extism::CurrentPlugin

Inherits:
Object
  • Object
show all
Defined in:
lib/extism/current_plugin.rb

Overview

Represents a reference to a plugin in a host function Use this class to read and write to the memory of the plugin These methods allow you to get data in and out of the plugin in a host function

Instance Method Summary collapse

Constructor Details

#initialize(ptr) ⇒ CurrentPlugin

Initialize a CurrentPlugin given an pointer

Parameters:

  • ptr (FFI::Pointer) —

    the raw pointer to the plugin



13
14
15
 
# File 'lib/extism/current_plugin.rb', line 13

def initialize(ptr)
  @ptr = ptr
end

Instance Method Details

#alloc(num_bytes) ⇒ Extism::Memory

Allocates a memory block in the plugin

Examples:

Allocate 1kB

mem = current_plugin.alloc(1_024)
current_plugin.free(mem)

Parameters:

  • num_bytes (Integer) —

    The amount in bytes to allocate

Returns:



25
26
27
28
 
# File 'lib/extism/current_plugin.rb', line 25

def alloc(num_bytes)
  offset = LibExtism.extism_current_plugin_memory_alloc(@ptr, num_bytes)
  Memory.new(offset, num_bytes)
end

#free(memory) ⇒ Extism::Memory

Frees the memory block

Examples:

mem = current_plugin.alloc(1_024)
current_plugin.free(mem)

Parameters:

Returns:



38
39
40
 
# File 'lib/extism/current_plugin.rb', line 38

def free(memory)
  LibExtism.extism_current_plugin_memory_free(@ptr, memory.offset)
end

#input_as_json(input) ⇒ Hash

Gets the input as a JSON parsed Hash

Examples:

param1 = current_plugin.input_as_json(inputs.first)
raise "Failed" unless param1 == {hello: "world"}

Parameters:

  • input (Extism::Val) —

    The input val from the host function

Returns:

  • (Hash) —

    The Hash object

Raises:



86
87
88
89
90
91
92
 
# File 'lib/extism/current_plugin.rb', line 86

def input_as_json(input)
  raise ArgumentError, 'input is not an Extism::Val' unless input.instance_of? Extism::Val

  mem = memory_at_offset(input.value)
  str = memory_ptr(mem).read_bytes(mem.len)
  JSON.parse(str)
end

#input_as_string(input) ⇒ String

Gets the input as a string

Examples:

param1 = current_plugin.input_as_string(inputs.first)
raise "Failed" unless param1 == "First param from plug-in host function call"

Parameters:

  • input (Extism::Val) —

    The input val from the host function

Returns:

  • (String) —

    raw bytes as a string

Raises:



69
70
71
72
73
74
 
# File 'lib/extism/current_plugin.rb', line 69

def input_as_string(input)
  raise ArgumentError, 'input is not an Extism::Val' unless input.instance_of? Extism::Val

  mem = memory_at_offset(input.value)
  memory_ptr(mem).read_bytes(mem.len)
end

#memory_at_offset(offset) ⇒ Extism::Memory

Gets the memory block at a given offset. Note: try to use input_* and output_* methods where possible.

Examples:

mem = current_plugin.memory_at_offset(123456789)
current_plugin.free(mem)

Parameters:

  • offset (Integer) —

    The offset pointer to the memory. This is relative to the plugin not the host.

Returns:

Raises:



52
53
54
55
56
57
 
# File 'lib/extism/current_plugin.rb', line 52

def memory_at_offset(offset)
  len = LibExtism.extism_current_plugin_memory_length(@ptr, offset)
  raise Extism::Error, "Could not find memory block at offset #{offset}" if len.zero?

  Memory.new(offset, len)
end

#output_json(output, obj) ⇒ Object

Sets json to the return of the host function

Examples:

msg = {hello: "world"}
current_plugin.output_json(outputs.first, msg)

Parameters:

  • output (Extism::Val) —

    The output val from the host function

  • obj (Hash) —

    The hash object to turn to JSON

Raises:



120
121
122
123
124
125
 
# File 'lib/extism/current_plugin.rb', line 120

def output_json(output, obj)
  bytes = JSON.generate(obj)
  mem = alloc(bytes.length)
  memory_ptr(mem).put_bytes(0, bytes)
  set_return(output, mem.offset)
end

#output_string(output, bytes) ⇒ Object

Sets string to the return of the host function

Examples:

msg = "A string returned from the host function"
current_plugin.output_string(outputs.first, msg)

Parameters:

  • output (Extism::Val) —

    The output val from the host function

  • bytes (String) —

    The bytes to set

Raises:



104
105
106
107
108
 
# File 'lib/extism/current_plugin.rb', line 104

def output_string(output, bytes)
  mem = alloc(bytes.length)
  memory_ptr(mem).put_bytes(0, bytes)
  set_return(output, mem.offset)
end

#set_return(output, value) ⇒ Object

Sets the return value parameter

Parameters:

  • output (Extism::Val) —

    The output val from the host function

  • value (Integer | Float) —

    The i32 value

Raises:



133
134
135
136
137
138
139
140
 
# File 'lib/extism/current_plugin.rb', line 133

def set_return(output, value)
  case output.type
  when :i32, :i64, :f32, :f64
    output.value = value
  else
    raise ArgumentError, "Don't know how to set output type #{output.type}"
  end
end