Merge pull request #951 from devlights/add-unsafe-example

Add unsafe example

Author: devlights

examples/basic/unsafes/README.md

@@ -9,3 +9,4 @@
 | unsafe_stringdata.go   | unsafe_stringdata   | unsafe.StringData() のサンプルです.                                  |
 | unsafe_pointer_cast.go | unsafe_pointer_cast | unsafeパッケージを用いてポインタを任意の型にキャストするサンプルです |
 | unsafe_add.go          | usnafe_add          | unsafe.Add関数を利用してポインタ演算するサンプルです                 |
+| unsafe_slice.go        | usnafe_slice        | unsafe.SliceData() と unsafe.Slice() のサンプルです                  |

examples/basic/unsafes/examples.go

@@ -18,4 +18,5 @@ func (r *register) Regist(m mapping.ExampleMapping) {
 	m["unsafe_stringdata"] = UnsafeStringData
 	m["unsafe_pointer_cast"] = PointerCast
 	m["unsafe_add"] = Add
+	m["unsafe_slice"] = Slice
 }

examples/basic/unsafes/unsafe_slice.go

@@ -0,0 +1,28 @@
+package unsafes
+
+import (
+	"bytes"
+	"fmt"
+	"unsafe"
+)
+
+// Slice は、unsafe.SliceData() と unsafe.Slice() のサンプルです。
+//
+// unsafe.SliceData() は、特定のスライスを *T に変換する関数。
+// 逆を行ってくれるのが unsafe.Slice() となる。
+//
+// REFERENCES:
+//   - https://pkg.go.dev/unsafe@go1.25.3#SliceData
+func Slice() error {
+	var (
+		original = []byte("helloworld")
+		result   []byte
+		ptr      *byte
+	)
+	ptr = unsafe.SliceData(original)          // []byteを*byteに変換
+	result = unsafe.Slice(ptr, len(original)) // *byteを[]byteに変換
+
+	fmt.Printf("b1 equals b2: %v\n", bytes.Equal(original, result))
+
+	return nil
+}

examples/singleapp/unsafe_slice_with_cgo/README.md

@@ -0,0 +1,103 @@
+# これは何？
+
+このサンプルプログラムは、cgoを利用してGo言語とC言語の間でデータを連携させる方法、特にGo 1.17で導入された`unsafe.Slice`とGo 1.20で導入された`unsafe.SliceData`を活用した効率的なメモリアクセス方法を具体的に示すものです。
+
+Cの関数からGoの関数を呼び出し、Go側で受け取ったデータを処理して、再びCの関数に処理結果を返す、という一連の流れを実装しています。
+
+## 処理の流れ
+
+このプログラムは、以下の順序で処理が実行されます。
+
+1.  **`main.go:main()`**
+    *   プログラムのエントリポイント。C言語側で定義された`c_func()`を呼び出します。
+
+2.  **`c.go:c_func()`**
+    *   スタック上に文字列 `"helloworld"` を確保します。
+    *   Go側でエクスポートされている`go_func()`を、文字列のポインタとサイズを引数にして呼び出します。
+
+3.  **`export.go:go_func()`**
+    *   Cから渡されたポインタ (`*C.char`) とサイズ (`C.size_t`) を `unsafe.Slice` を使ってGoのスライス (`[]byte`) に変換します。この操作はメモリコピーを発生させず、Cのメモリ領域を直接参照します。
+    *   安全のため、Cのメモリを直接変更するのではなく、Goの管理するメモリにデータをコピーします。
+    *   コピーしたデータに対して文字列の反転処理を行います。
+    *   処理後のGoスライスを `unsafe.SliceData` を使ってCで扱えるポインタ形式に変換し、C側の`c_func2()`を呼び出します。
+
+4.  **`c.go:c_func2()`**
+    *   Goから渡されたデータを受け取り、標準出力に表示します。
+
+## 技術詳細
+
+### CからGoへのデータ受け渡し: `unsafe.Slice`
+
+Goの関数 (`go_func`) がCからデータを受け取る際、`unsafe.Slice` を利用してパフォーマンスを向上させています。
+
+```go
+//export go_func
+func go_func(s *C.char, n C.size_t) {
+	var (
+		sPtr   = unsafe.Pointer(s)
+		cSlice = unsafe.Slice((*byte)(sPtr), n) // cSliceはC側のスタック変数を指している
+	)
+	fmt.Printf("[Go] %s", cSlice)
+    // ...
+}
+```
+
+- `*C.char` を `unsafe.Pointer` を経由してGoの `*byte` に変換します。
+- `unsafe.Slice` は、このポインタとデータ長 `n` を基に、Goのスライスヘッダを生成します。
+- この結果得られる `cSlice` は、C言語側のメモリ領域を直接指し示すスライスとなり、**余計なメモリコピーが発生しません（ゼロコピー）**。
+
+**【重要】注意点:**
+`cSlice`が参照しているのはCのスタックメモリです。Goのガベージコレクタの管理外であり、関数を抜けると無効になる可能性があります。Go側でこのデータを永続化したり変更したりする場合は、必ずGoが管理するメモリに`copy()`で複製してから操作する必要があります。
+
+### GoからCへのデータ受け渡し: `unsafe.SliceData`
+
+Goで処理したデータをCの関数に渡す際には、`unsafe.SliceData` を利用します。
+
+```go
+// ...
+	// C側の関数に渡すための準備
+	var (
+		bytePtr = unsafe.SliceData(goSlice)          // *byteに変換し
+		charPtr = (*C.char)(unsafe.Pointer(bytePtr)) // そこから (char *) に変換
+		charLen = C.size_t(len(goSlice))             // サイズはスライスからそのまま取得
+	)
+	C.c_func2(charPtr, charLen)
+}
+```
+
+- `unsafe.SliceData` は、Goのスライスの先頭要素へのポインタ (`*byte`) を返します。
+- このポインタを `unsafe.Pointer` を経由してCの `*C.char` 型にキャストすることで、Cの関数に渡せるようになります。
+- これにより、Goのメモリ領域をC側から直接読み取ることが可能になります。
+
+### C言語とGo言語間の文字列の扱い
+
+Cの文字列は通常NULL文字で終端されます。`unsafe.Slice`でGoスライスに変換した場合、このNULL文字もスライスの一部として含まれることがあります。
+このサンプルでは、文字列を反転させる前に、NULL文字を考慮して実際のデータ長を計算しています。
+
+```go
+// NULL終端文字がある場合は減算して実データサイズとする
+if dataLen > 0 && cSlice[dataLen-1] == 0 {
+    dataLen--
+}
+
+// 実データ分をコピー
+goSlice = make([]byte, dataLen)
+copy(goSlice, cSlice[:dataLen])
+```
+
+逆に、GoからCへデータを渡す際は、C側がNULL終端文字列を期待していることを想定し、処理後のスライスにNULL文字を追加しています。
+
+## 実行方法
+
+プロジェクトのルートにある`Taskfile.yml`に実行コマンドが定義されています。以下のコマンドでサンプルを実行できます。
+
+```sh
+go run *.go
+```
+
+### 実行結果
+
+```
+[Go] helloworld
+[C ] dlrowolleh
+```

examples/singleapp/unsafe_slice_with_cgo/Taskfile.yml

@@ -0,0 +1,8 @@
+# https://taskfile.dev
+
+version: '3'
+
+tasks:
+  default:
+    cmds:
+      - go run *.go

examples/singleapp/unsafe_slice_with_cgo/c.go

@@ -0,0 +1,25 @@
+package main
+
+/*
+#include <stdio.h>
+#include <string.h>
+
+extern void go_func(const char *s, size_t n);
+
+void c_func() {
+	char s[] = "helloworld";
+	size_t s_size = sizeof(s);
+	go_func(s, s_size);
+}
+
+void c_func2(const char *s, size_t n) {
+	char buf[n];
+	{
+		memcpy(buf, s, n);
+		buf[n-1] = '\0';
+	}
+
+	printf("[C ] %s\n", buf);
+}
+*/
+import "C"

examples/singleapp/unsafe_slice_with_cgo/export.go

@@ -0,0 +1,57 @@
+package main
+
+/*
+extern void c_func2(const char *s, size_t n);
+*/
+import "C"
+import (
+	"fmt"
+	"unsafe"
+)
+
+//export go_func
+func go_func(s *C.char, n C.size_t) {
+	var (
+		sPtr   = unsafe.Pointer(s)
+		cSlice = unsafe.Slice((*byte)(sPtr), n) // cSliceはC側のスタック変数を指している
+	)
+	fmt.Printf("[Go] %s\n", cSlice)
+
+	// 何らかの変換を行う（例としてデータをリバース）
+	//
+	// 注意点として、cSliceはC側のスタック変数をそのまま指しているため
+	// これを直接変更すると、C側のスタックメモリを書き換えてしまうことになる。
+	// 必ず、コピーを取ってから変更処理は行うこと。
+	//
+	// また、C.GoBytes(), C.CString() を利用せずに直接C側のデータを扱っているので
+	// cSliceの中は最後に終端文字が入った状態となっている。
+	// この状態でそのままスライスをリバースすると \0 が先頭に来ることになるので除去してから処理する。
+	var (
+		goSlice []byte   // Go側で扱うスライス
+		dataLen = int(n) // 実データのサイズ
+	)
+	// NULL終端文字がある場合は減算して実データサイズとする
+	if dataLen > 0 && cSlice[dataLen-1] == 0 {
+		dataLen--
+	}
+
+	// 実データ分をコピー
+	goSlice = make([]byte, dataLen)
+	copy(goSlice, cSlice[:dataLen])
+
+	// リバース
+	for i, j := 0, len(goSlice)-1; i < j; i, j = i+1, j-1 {
+		goSlice[i], goSlice[j] = goSlice[j], goSlice[i]
+	}
+
+	// 終端追加
+	goSlice = append(goSlice, 0)
+
+	// C側の関数に渡すための準備
+	var (
+		bytePtr = unsafe.SliceData(goSlice)          // *byteに変換し
+		charPtr = (*C.char)(unsafe.Pointer(bytePtr)) // そこから (char *) に変換
+		charLen = C.size_t(len(goSlice))             // サイズはスライスからそのまま取得 ([]byteの場合はこれでOK)
+	)
+	C.c_func2(charPtr, charLen)
+}

examples/singleapp/unsafe_slice_with_cgo/main.go

@@ -0,0 +1,17 @@
+package main
+
+/*
+extern void c_func();
+*/
+import "C"
+
+func main() {
+	C.c_func()
+}
+
+/*
+	$ task
+	task: [default] go run *.go
+	[Go] helloworld
+	[C ] dlrowolleh
+*/