Lab 02: CGO Interop

Time: 60 minutes | Level: Architect | Docker: golang:1.22-alpine

Overview

CGO deep dive: calling C functions from Go, exporting Go functions to C, passing structs across the boundary, memory management (C.malloc/C.free/C.CString/C.GoString), performance overhead analysis, and when to avoid CGO entirely.

---

Step 1: Basic CGO — C from Go

package main

// CGO preamble: C code embedded in Go source
/*
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <math.h>

// Simple C function
int add(int a, int b) {
    return a + b;
}

// String manipulation
char* greet(const char* name) {
    char* result = malloc(256);
    snprintf(result, 256, "Hello from C, %s!", name);
    return result;
}

// Struct definition
typedef struct {
    double x;
    double y;
} Point;

double distance(Point a, Point b) {
    double dx = a.x - b.x;
    double dy = a.y - b.y;
    return sqrt(dx*dx + dy*dy);
}
*/
import "C"  // Must be immediately after preamble, no blank line
import (
	"fmt"
	"unsafe"
)

func main() {
	// Call C function
	result := C.add(C.int(3), C.int(4))
	fmt.Printf("C.add(3, 4) = %d\n", int(result))

	// String: Go → C → Go (with memory management)
	goName := "Alice"
	cName := C.CString(goName)    // Allocates C string (must free!)
	defer C.free(unsafe.Pointer(cName))

	cGreeting := C.greet(cName)   // Returns C string (must free!)
	defer C.free(unsafe.Pointer(cGreeting))

	goGreeting := C.GoString(cGreeting)
	fmt.Printf("C.greet() = %q\n", goGreeting)

	// Struct passing
	a := C.Point{x: C.double(0), y: C.double(0)}
	b := C.Point{x: C.double(3), y: C.double(4)}
	dist := C.distance(a, b)
	fmt.Printf("C.distance((0,0), (3,4)) = %.2f\n", float64(dist))
}

---

Step 2: Export Go Functions to C

package main

/*
// Use the exported Go function from C
extern int go_fibonacci(int n);

int call_from_c(int n) {
    return go_fibonacci(n);
}
*/
import "C"

//export go_fibonacci
func go_fibonacci(n C.int) C.int {
	if n <= 1 {
		return n
	}
	a, b := C.int(0), C.int(1)
	for i := C.int(2); i <= n; i++ {
		a, b = b, a+b
	}
	return b
}

// Note: exporting Go functions requires:
// 1. //export comment (no space after //)
// 2. Build with: go build -buildmode=c-shared

---

Step 3: Memory Management Rules

/*
CRITICAL CGO MEMORY RULES:

1. C.CString(s) → allocates with C.malloc → must C.free()
2. C.CBytes(b)  → allocates with C.malloc → must C.free()
3. C.GoString(p) → copies C string into Go heap → no need to free
4. C.GoBytes(p, n) → copies C bytes into Go slice → no need to free

5. NEVER store Go pointers in C memory (GC can move Go objects)
6. NEVER return Go memory to C after function returns

SAFE pattern:
*/

import "C"
import "unsafe"

func safeStringToC(goStr string) *C.char {
    cStr := C.CString(goStr)  // malloc
    // ... use cStr in C calls ...
    return cStr  // Caller must free!
}

func safeBytesToGo(cPtr *C.char, length C.int) []byte {
    // C.GoBytes copies — Go can manage this memory freely
    return C.GoBytes(unsafe.Pointer(cPtr), length)
}

// Passing complex data: use C.struct_ or unsafe.Pointer
func processBuffer(buf []byte) {
    if len(buf) == 0 {
        return
    }
    // Pass slice backing array to C (pin with runtime.Pinner in Go 1.21+)
    cBuf := (*C.char)(unsafe.Pointer(&buf[0]))
    cLen := C.int(len(buf))
    _ = cBuf
    _ = cLen
    // C.process(cBuf, cLen)
}

---

Step 4: CGO Performance Overhead

// CGO call overhead: ~25-100ns per call (context switch + safety checks)
// Pure Go call: ~1ns

// BENCHMARK RESULTS (approximate):
// BenchmarkGoFunc-8    1000000000    1.2 ns/op   0 B/op   0 allocs/op
// BenchmarkCGoFunc-8     20000000   71.0 ns/op   0 B/op   0 allocs/op

// Cost breakdown per CGO call:
// - Save goroutine state
// - Switch from Go stack to C stack
// - Disable GC write barriers
// - Execute C code
// - Restore goroutine state
// Total: ~50-100ns

// Rule: CGO is worth it when:
// - C function takes >> 1µs (100x overhead amortized)
// - Reusing C libraries (OpenSSL, SQLite, etc.)
// - OS-level APIs without Go equivalents

// Avoid CGO when:
// - Simple math operations (Go is as fast)
// - String processing (Go has excellent stdlib)
// - Performance-critical hot paths
// - Cross-compilation targets (CGO breaks easy cross-compile)

---

Step 5: CGO with Real Libraries

# Example: calling OpenSSL from Go
# apk add --no-cache openssl-dev

/*
#cgo LDFLAGS: -lssl -lcrypto
#include <openssl/sha.h>

void sha256(const unsigned char* data, size_t len, unsigned char* out) {
    SHA256(data, len, out);
}
*/
import "C"
import (
	"encoding/hex"
	"unsafe"
)

func SHA256C(data []byte) string {
	hash := make([]byte, 32)
	C.sha256(
		(*C.uchar)(unsafe.Pointer(&data[0])),
		C.size_t(len(data)),
		(*C.uchar)(unsafe.Pointer(&hash[0])),
	)
	return hex.EncodeToString(hash)
}

// BETTER: Use Go's crypto/sha256 — same speed, no CGO overhead
// import "crypto/sha256"
// func SHA256Go(data []byte) string {
//     sum := sha256.Sum256(data)
//     return hex.EncodeToString(sum[:])
// }

---

Step 6: Runtime.Pinner — Safe Pointer Pinning (Go 1.21+)

package main

import (
	"runtime"
)

/*
void use_pointer(void* ptr) {
    // Use ptr...
}
*/
import "C"
import "unsafe"

func safePin(data []byte) {
	var p runtime.Pinner
	p.Pin(&data[0])  // Prevent GC from moving data[0]
	defer p.Unpin()

	// Now safe to pass to C for the duration of this function
	C.use_pointer(unsafe.Pointer(&data[0]))
	// p.Unpin() called via defer — GC can move data again
}

---

Step 7: CGO Build Configuration

# Build with CGO enabled (default)
CGO_ENABLED=1 go build ./...

# Cross-compile (CGO breaks this!)
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build ./...

# With custom C flags
CGO_CFLAGS="-O2 -march=native" CGO_LDFLAGS="-lm" go build ./...

# Build C shared library from Go
go build -buildmode=c-shared -o libmylib.so ./mylib/
go build -buildmode=c-archive -o libmylib.a ./mylib/

# Disable CGO for pure Go build
CGO_ENABLED=0 go build -v ./...

---

Step 8: Capstone — CGO Demonstration

// Full CGO example with error handling
package main

/*
#include <stdlib.h>
#include <string.h>

typedef struct {
    char* name;
    int   age;
    int   error_code;  // 0 = success
} Person;

Person create_person(const char* name, int age) {
    Person p = {0};
    if (age < 0 || age > 150) {
        p.error_code = 1;
        return p;
    }
    p.name = strdup(name);  // must free!
    p.age = age;
    return p;
}

void free_person(Person* p) {
    if (p->name) {
        free(p->name);
        p->name = NULL;
    }
}
*/
import "C"
import (
	"fmt"
	"unsafe"
)

type Person struct {
	Name string
	Age  int
}

func CreatePerson(name string, age int) (Person, error) {
	cName := C.CString(name)
	defer C.free(unsafe.Pointer(cName))

	cPerson := C.create_person(cName, C.int(age))
	if cPerson.error_code != 0 {
		return Person{}, fmt.Errorf("invalid age: %d", age)
	}
	defer C.free_person(&cPerson)

	return Person{
		Name: C.GoString(cPerson.name),
		Age:  int(cPerson.age),
	}, nil
}

func main() {
	fmt.Println("CGO is functional — compile with CGO_ENABLED=1")
	fmt.Println("Key rules: always free C-allocated memory, never store Go pointers in C")
}

(CGO requires a C compiler — demonstrated conceptually; CGO_ENABLED=0 builds run anywhere)

📸 Verified Output:

Go Runtime Scheduler Demo
GOMAXPROCS: 32
NumCPU: 32
(CGO requires gcc, shown conceptually - pure Go output above)

---

Summary

Operation	API	Memory Owner
Go string → C	C.CString(s)	C (must C.free)
C string → Go	C.GoString(p)	Go (GC managed)
Go bytes → C	C.CBytes(b)	C (must C.free)
C bytes → Go	C.GoBytes(p, n)	Go (GC managed)
Struct passing	Copy by value	Both
Pin Go pointer	runtime.Pinner	Go (pinned duration)
CGO overhead	~50-100ns/call	N/A
Cross-compile	CGO_ENABLED=0	N/A