package plugin

import "plugin"

Package plugin implements loading and symbol resolution of Go plugins.

A plugin is a Go main package with exported functions and variables that has been built with:

go build -buildmode=plugin

When a plugin is first opened, the init functions of all packages not already part of the program are called. The main function is not run. A plugin is only initialized once, and cannot be closed.

Warnings

The ability to dynamically load parts of an application during execution, perhaps based on user-defined configuration, may be a useful building block in some designs. In particular, because applications and dynamically loaded functions can share data structures directly, plugins may enable very high-performance integration of separate parts.

However, the plugin mechanism has many significant drawbacks that should be considered carefully during the design. For example:

For these reasons, many users decide that traditional interprocess communication (IPC) mechanisms such as sockets, pipes, remote procedure call (RPC), shared memory mappings, or file system operations may be more suitable despite the performance overheads.

Index

Types

type Plugin

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

Plugin is a loaded Go plugin.

func Open

func Open(path string) (*Plugin, error)

Open opens a Go plugin. If a path has already been opened, then the existing *Plugin is returned. It is safe for concurrent use by multiple goroutines.

func (*Plugin) Lookup

func (p *Plugin) Lookup(symName string) (Symbol, error)

Lookup searches for a symbol named symName in plugin p. A symbol is any exported variable or function. It reports an error if the symbol is not found. It is safe for concurrent use by multiple goroutines.

type Symbol

type Symbol any

A Symbol is a pointer to a variable or function.

For example, a plugin defined as

package main

import "fmt"

var V int

func F() { fmt.Printf("Hello, number %d\n", V) }

may be loaded with the Open function and then the exported package symbols V and F can be accessed

p, err := plugin.Open("plugin_name.so")
if err != nil {
	panic(err)
}
v, err := p.Lookup("V")
if err != nil {
	panic(err)
}
f, err := p.Lookup("F")
if err != nil {
	panic(err)
}
*v.(*int) = 7
f.(func())() // prints "Hello, number 7"