| // Copyright 2016 The Go Authors. All rights reserved. | |
| // Use of this source code is governed by a BSD-style | |
| // license that can be found in the LICENSE file. | |
| // 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: | |
| // | |
| // - Plugins are currently supported only on Linux, FreeBSD, and | |
| // macOS, making them unsuitable for applications intended to be | |
| // portable. | |
| // | |
| // - Plugins are poorly supported by the Go race detector. Even simple | |
| // race conditions may not be automatically detected. See | |
| // https://go.dev/issue/24245 for more information. | |
| // | |
| // - Applications that use plugins may require careful configuration | |
| // to ensure that the various parts of the program be made available | |
| // in the correct location in the file system (or container image). | |
| // By contrast, deploying an application consisting of a single static | |
| // executable is straightforward. | |
| // | |
| // - Reasoning about program initialization is more difficult when | |
| // some packages may not be initialized until long after the | |
| // application has started running. | |
| // | |
| // - Bugs in applications that load plugins could be exploited by | |
| // an attacker to load dangerous or untrusted libraries. | |
| // | |
| // - Runtime crashes are likely to occur unless all parts of the | |
| // program (the application and all its plugins) are compiled | |
| // using exactly the same version of the toolchain, the same build | |
| // tags, and the same values of certain flags and environment | |
| // variables. | |
| // | |
| // - Similar crashing problems are likely to arise unless all common | |
| // dependencies of the application and its plugins are built from | |
| // exactly the same source code. | |
| // | |
| // - Together, these restrictions mean that, in practice, the | |
| // application and its plugins must all be built together by a | |
| // single person or component of a system. In that case, it may | |
| // be simpler for that person or component to generate Go source | |
| // files that blank-import the desired set of plugins and then | |
| // compile a static executable in the usual way. | |
| // | |
| // 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. | |
| package plugin | |
| // Plugin is a loaded Go plugin. | |
| type Plugin struct { | |
| pluginpath string | |
| err string // set if plugin failed to load | |
| loaded chan struct{} // closed when loaded | |
| syms map[string]any | |
| } | |
| // 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 Open(path string) (*Plugin, error) { | |
| return open(path) | |
| } | |
| // 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. | |
| func (p *Plugin) Lookup(symName string) (Symbol, error) { | |
| return lookup(p, symName) | |
| } | |
| // 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" | |
| type Symbol any | |