From 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 7 Apr 2024 13:41:34 -0500 Subject: new repository --- devdocs/go/plugin%2Findex.html | 60 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 devdocs/go/plugin%2Findex.html (limited to 'devdocs/go/plugin%2Findex.html') diff --git a/devdocs/go/plugin%2Findex.html b/devdocs/go/plugin%2Findex.html new file mode 100644 index 00000000..bc061022 --- /dev/null +++ b/devdocs/go/plugin%2Findex.html @@ -0,0 +1,60 @@ +

Package plugin

import "plugin"
Overview
Index

Overview

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.
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.

Index

type Plugin
func Open(path string) (*Plugin, error) +
func (p *Plugin) Lookup(symName string) (Symbol, error) +
type Symbol

Package files

plugin.go plugin_dlopen.go

type Plugin 1.8

Plugin is a loaded Go plugin.

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

func Open 1.8

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 1.8

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 1.8

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

-- cgit v1.2.3