speedboost

README

⭐   the project to show your appreciation. :arrow_upper_right:

SPEEDBOOST

Call any function from a shared library that is C ABI compatible (i.e. you can build with C, Zig, Rust etc).

It is CGO free and has less overhead than Purego.

After factoring in the overhead of calling a shared library, you may find that it is faster than the equivalent Go implementation: https://niklas-heer.github.io/speed-comparison

See the example project for more details.

C Library programmed in Zig (cross-platform)

const std = @import("std");

// multiply returns a ⨯ b, where a and b are float64.
export fn multiply(a: f64, b: f64) callconv(.c) f64 {
    return a * b;
}

Go code consuming Library

type Ptr = unsafe.Pointer

//go:generate zig build --build-file ./lib/build.zig go-build
//go:embed lib/zig-out/mymath.shared
var sharedLibrary []byte

func main() {
    lib, err := sb.LoadLibrary(sharedLibrary)
    if err != nil {
        panic(err)
    }
    defer lib.Unload()

    addPtr := lib.GetSymbol("multiply")

    cifAdd := sb.SetFuncSignature(sb.DoubleTypeDescriptor, sb.DoubleTypeDescriptor, sb.DoubleTypeDescriptor)

    // Call Function
    var result float64
    err = sb.CallFunction(cifAdd, addPtr, Ptr(&result), Ptr(new(40.0))), Ptr(new(2.0)))
    if err != nil {
        panic(err)
    }

    fmt.Printf("multiply(40.0, 2.0) = %f\n", result) // 80.0    
}

How to run example project

Install Zig 0.16 (later versions may break build.zig)

$ go generate ./...
$ CGO_ENABLED=0 go run .

For cross-platform compilation

$ GOOS=linux go generate ./...
$ GOOS=linux CGO_ENABLED=0 go run .

Special Thanks

@kolkov of https://github.com/go-webgpu/goffi

Documentation

Index

• Variables
• func CallFunction(cif *types.CallInterface, fn unsafe.Pointer, rvalue unsafe.Pointer, ...) error
• func CallFunctionContext(ctx context.Context, cif *types.CallInterface, fn unsafe.Pointer, ...) error
• func SetFuncSignature(returnType *types.TypeDescriptor, argTypes ...*types.TypeDescriptor) *types.CallInterface
• type SharedLibrary
  • func LoadLibrary(libBinary []byte) (*SharedLibrary, error)
  • func (l *SharedLibrary) GetSymbol(symbol string) unsafe.Pointer
  • func (l *SharedLibrary) Unload()

Variables

var (
	VoidTypeDescriptor    = types.VoidTypeDescriptor
	IntTypeDescriptor     = types.IntTypeDescriptor
	FloatTypeDescriptor   = types.FloatTypeDescriptor
	DoubleTypeDescriptor  = types.DoubleTypeDescriptor
	UInt8TypeDescriptor   = types.UInt8TypeDescriptor
	SInt8TypeDescriptor   = types.SInt8TypeDescriptor
	UInt16TypeDescriptor  = types.UInt16TypeDescriptor
	SInt16TypeDescriptor  = types.SInt16TypeDescriptor
	UInt32TypeDescriptor  = types.UInt32TypeDescriptor
	SInt32TypeDescriptor  = types.SInt32TypeDescriptor
	UInt64TypeDescriptor  = types.UInt64TypeDescriptor
	SInt64TypeDescriptor  = types.SInt64TypeDescriptor
	PointerTypeDescriptor = types.PointerTypeDescriptor
)

Functions

func CallFunction

func CallFunction(cif *types.CallInterface, fn unsafe.Pointer, rvalue unsafe.Pointer, avalue ...unsafe.Pointer) error

CallFunction calls fn (obtained using GetSymbol).

func CallFunctionContext

func CallFunctionContext(ctx context.Context, cif *types.CallInterface, fn unsafe.Pointer, rvalue unsafe.Pointer, avalue ...unsafe.Pointer) error

CallFunctionContext calls fn (obtained using GetSymbol). It accepts a context for the first argument.

func SetFuncSignature

func SetFuncSignature(returnType *types.TypeDescriptor, argTypes ...*types.TypeDescriptor) *types.CallInterface

SetFuncSignature configures the C function's signature (i.e. return value argument types).

Types

type SharedLibrary

type SharedLibrary struct {
	// contains filtered or unexported fields
}

SharedLibrary represents a shared library that has been loaded and is ready to use.

func LoadLibrary

func LoadLibrary(libBinary []byte) (*SharedLibrary, error)

LoadLibrary loads a shared library after being supplied with the binary for the library.

func (*SharedLibrary) GetSymbol

func (l *SharedLibrary) GetSymbol(symbol string) unsafe.Pointer

GetSymbol returns a pointer to an exported function in the shared library.

func (*SharedLibrary) Unload

func (l *SharedLibrary) Unload()

Unload can be called after the already loaded library is no longer needed.