1 // Copyright 2016 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package plugin implements loading and symbol resolution of Go plugins. 6 // 7 // A plugin is a Go main package with exported functions and variables that 8 // has been built with: 9 // 10 // go build -buildmode=plugin 11 // 12 // When a plugin is first opened, the init functions of all packages not 13 // already part of the program are called. The main function is not run. 14 // A plugin is only initialized once, and cannot be closed. 15 // 16 // Currently plugins are only supported on Linux and macOS. 17 // Please report any issues. 18 package plugin 19 20 // Plugin is a loaded Go plugin. 21 type Plugin struct { 22 pluginpath string 23 err string // set if plugin failed to load 24 loaded chan struct{} // closed when loaded 25 syms map[string]interface{} 26 } 27 28 // Open opens a Go plugin. 29 // If a path has already been opened, then the existing *Plugin is returned. 30 // It is safe for concurrent use by multiple goroutines. 31 func Open(path string) (*Plugin, error) { 32 return open(path) 33 } 34 35 // Lookup searches for a symbol named symName in plugin p. 36 // A symbol is any exported variable or function. 37 // It reports an error if the symbol is not found. 38 // It is safe for concurrent use by multiple goroutines. 39 func (p *Plugin) Lookup(symName string) (Symbol, error) { 40 return lookup(p, symName) 41 } 42 43 // A Symbol is a pointer to a variable or function. 44 // 45 // For example, a plugin defined as 46 // 47 // package main 48 // 49 // import "fmt" 50 // 51 // var V int 52 // 53 // func F() { fmt.Printf("Hello, number %d\n", V) } 54 // 55 // may be loaded with the Open function and then the exported package 56 // symbols V and F can be accessed 57 // 58 // p, err := plugin.Open("plugin_name.so") 59 // if err != nil { 60 // panic(err) 61 // } 62 // v, err := p.Lookup("V") 63 // if err != nil { 64 // panic(err) 65 // } 66 // f, err := p.Lookup("F") 67 // if err != nil { 68 // panic(err) 69 // } 70 // *v.(*int) = 7 71 // f.(func())() // prints "Hello, number 7" 72 type Symbol interface{} 73