Initial commit

Author: Devoter

.gitignore

@@ -0,0 +1,20 @@
+# IDE
+.idea
+.vscode
+
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+vendor/

LICENSE

@@ -0,0 +1,28 @@
+Copyright (c) 2022 Alexey Nosov.
+Copyright (c) 2009 The Go Authors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,169 @@
+# dlplugin
+
+This package is based on the official Go `plugin` package, but modified to use any dynamic C libraries (Only Linux, FreeBSD, and macOS).
+
+It provides a thread-safe interface for loading/unloading dynamic libraries, but the library symbols should be loaded manually using `PluginInitializer`.
+
+
+## Installation
+
+`go get github.com/Devoter/dlplugin`
+
+or use `go mod` tool.
+
+
+## Usage
+
+**WARNING:** Windows implementation was not tested and should not be used.
+
+This package uses `cgo`, it is highly recommended to read the [official CGO documentation](https://pkg.go.dev/cmd/cgo).
+
+Open and prepare a plugin via `dlplugin.Open()` function:
+
+```go
+Open(path string, initializer PluginInitializer) (*Plugin, error)
+```
+
+It accepts a library filename and an initializer. The `Init()` method denotes a function type which initializes a plugin API.
+
+```go
+type PluginInitializer interface {
+	Init(lookup func(symName string) (uintptr, error)) error
+}
+```
+
+An opened library may be closed using the `Close()` method of the `Plugin` or the `Close()` function:
+
+```go
+func (p *Plugin) Close() error
+
+func Close(p *Plugin) error
+```
+
+## Examples
+
+All examples have Makefiles, therefore you can build each example with the `make` command.
+
+### Basic
+
+This example is a program that prints "Hello, world!" via dynamic library call. The example contains two implementations of program: naive and with an interface.
+
+<details>
+  <summary>Plugin code</summary>
+
+```go
+package main
+
+import "C"
+import "fmt"
+
+//export println
+func println(v *C.char) {
+	s := C.GoString(v)
+
+	fmt.Println(s)
+}
+
+func main() {}
+
+```
+</details>
+
+<details>
+  <summary>Program code</summary>
+
+```go
+package main
+
+/*
+#include <stdint.h>
+#include <stdlib.h>
+
+static void println(uintptr_t r, char *s)
+{
+	((void (*)(char *))r)(s);
+}
+*/
+import "C"
+import (
+	"flag"
+	"fmt"
+	"os"
+	"unsafe"
+
+	"github.com/Devoter/dlplugin"
+)
+
+type PluginAPI struct {
+	Println func(s string)
+}
+
+// Init initializes the plugin API.
+func (papi *PluginAPI) Init(lookup func(symName string) (uintptr, error)) error {
+	printlnPtr, err := lookup("println")
+	if err != nil {
+		return err
+	}
+
+	papi.Println = func(s string) {
+		cs := C.CString(s)
+		defer C.free(unsafe.Pointer(cs))
+
+		C.println(C.uintptr_t(printlnPtr), cs)
+	}
+
+	return nil
+}
+
+func main() {
+	pluginFilename := flag.String("plugin", "", "plugin filename")
+	help := flag.Bool("help", false, "show this text")
+
+	flag.Parse()
+
+	if *help {
+		flag.PrintDefaults()
+		return
+	}
+
+	var papi PluginAPI
+
+	plug, err := dlplugin.Open(*pluginFilename, &papi)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "could not initialize a plugin by the reason: %v\n", err)
+		os.Exit(1)
+	}
+
+	defer plug.Close()
+
+	papi.Println("Hello, world!")
+}
+```
+</details>
+
+[See](./examples/basic).
+
+
+### Random values
+
+This example starts a random values generator from the library and reads generated values.
+
+[See](./examples/random_values).
+
+
+### Callback
+
+This example concatenates two string with a dynamic library and returns the result via a callback function.
+
+[See](./examples/callback).
+
+
+### Multilib
+
+This example loads two libs with the single interface. The program instanciates remote objects and works with them.
+
+[See](https://github.com/Devoter/dlplugin_multilib_example)
+
+## License
+
+[LICENSE](./LICENSE)

doc.go

@@ -0,0 +1,7 @@
+// Copyright 2022 Alexey Nosov.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package dlplugin provides a thread-safe interface for loading/unloading dynamic libraries.
+// The library symbols should be loaded manually using PluginInitializer interface.
+package dlplugin

examples/basic/iface_prog/.gitignore

@@ -0,0 +1,2 @@
+prog
+*.exe

examples/basic/iface_prog/Makefile

@@ -0,0 +1,20 @@
+NAME=prog
+GOFLAGS=
+GOOS=
+GOARCH=
+GOARM=
+CGO_ENABLED=1
+CC=
+BIN_SUFFIX=
+
+ifeq ($(GOOS), windows)
+	BIN_SUFFIX=.exe
+endif
+
+all: $(NAME)$(BIN_SUFFIX)
+
+clean:
+	rm -f $(NAME)$(BIN_SUFFIX)
+
+$(NAME)$(BIN_SUFFIX): main.go plugin_api.go
+	GOOS=$(GOOS) GOARCH=$(GOARCH) GOARM=$(GOARM) CGO_ENABLED=$(CGO_ENABLED) CC=$(CC) go build $(GOFLAGS) -o $(NAME)$(BIN_SUFFIX) ./...

examples/basic/iface_prog/main.go

@@ -0,0 +1,40 @@
+// Copyright 2022 Alexey Nosov.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+
+	"github.com/Devoter/dlplugin"
+)
+
+func main() {
+	pluginFilename := flag.String("plugin", "", "plugin filename")
+	help := flag.Bool("help", false, "show this text")
+
+	flag.Parse()
+
+	if *help {
+		flag.PrintDefaults()
+		return
+	}
+
+	var plugInst Plugin
+
+	// loading the plugin an initializing its inteface.
+	plug, err := dlplugin.Open(*pluginFilename, &plugInst)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "could not initialize a plugin by the reason: %v\n", err)
+		os.Exit(1)
+	}
+
+	defer plug.Close() // release a plugin library
+
+	var papi PluginAPI = &plugInst
+
+	papi.Println("Hello, world!") // call plugin function
+}

examples/basic/iface_prog/plugin_api.go

@@ -0,0 +1,50 @@
+// Copyright 2022 Alexey Nosov.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+/*
+#include <stdint.h>
+#include <stdlib.h>
+
+static void println(uintptr_t r, char *s)
+{
+	((void (*)(char *))r)(s);
+}
+*/
+import "C"
+import "unsafe"
+
+// PluginAPI declares a plugin interface.
+type PluginAPI interface {
+	Println(s string)
+}
+
+// Plugin struct declares a plugin interface implementation.
+type Plugin struct {
+	println func(s string)
+}
+
+// Println calls a plugin `println` function transparently.
+func (p *Plugin) Println(s string) {
+	p.println(s)
+}
+
+// InitPluginAPIFactory returns an interface instance and a function that initializes the plugin API.
+func (p *Plugin) Init(lookup func(symName string) (uintptr, error)) error {
+	printlnPtr, err := lookup("println") // search for the library symbol
+	if err != nil {
+		return err
+	}
+
+	// defining a Go wrapper.
+	p.println = func(s string) {
+		cs := C.CString(s)
+		defer C.free(unsafe.Pointer(cs))
+
+		C.println(C.uintptr_t(printlnPtr), cs)
+	}
+
+	return nil
+}

examples/basic/plug/.gitignore

@@ -0,0 +1,3 @@
+*.h
+*.so
+*.dll

examples/basic/plug/Makefile

@@ -0,0 +1,22 @@
+NAME=plug
+GOFLAGS=-buildmode=c-shared
+GOOS=
+GOARCH=
+GOARM=
+CGO_ENABLED=1
+CC=
+LIB_EXT=
+
+ifeq ($(GOOS), windows)
+	LIB_EXT=dll
+else
+	LIB_EXT=so
+endif
+
+all: $(NAME).$(LIB_EXT)
+
+clean:
+	rm -f $(NAME).$(LIB_EXT) $(NAME).h
+
+$(NAME).$(LIB_EXT): main.go
+	GOOS=$(GOOS) GOARCH=$(GOARCH) GOARM=$(GOARM) CGO_ENABLED=$(CGO_ENABLED) CC=$(CC) go build $(GOFLAGS) -o $(NAME).$(LIB_EXT) ./...