CGO and ODPI-C Integration

export CGO_CFLAGS="-I/custom/path/include"
export CGO_LDFLAGS="-L/custom/path/lib -lodpi"
make build

make odpi

third_party/odpi/
├── include/
│   ├── dpi.h                 # Main ODPI-C header (1000+ declarations)
│   ├── dpi_go_helpers.h      # Helper macros for Go integration
│   └── dpi_go_helpers.c      # Helper function implementations
├── lib/
│   ├── libodpi.dylib         # macOS ARM64 shared library
│   └── odpi.dll              # Windows DLL
└── build/                    # Temporary object files (*.o)

typedef struct {
    char* data;       // Message payload (JSON from CLOB)
    uint64_t length;  // Payload length in bytes
} TraceMessage;

typedef struct {
    char* data;       // Message ID (RAW bytes)
    uint32_t length;  // ID length
} TraceId;

int DequeueManyAndExtract(
    dpiConn* conn,           // Oracle connection
    dpiContext* context,     // ODPI context for error handling
    const char* subscriberName,  // Queue consumer name
    uint32_t batchSize,      // Number of messages to dequeue
    int32_t waitTime,        // Wait time: -1=forever, 0=no wait, >0=seconds
    TraceMessage** outMessages,  // Output: array of messages
    TraceId** outIds,        // Output: array of message IDs
    uint32_t* actualCount    // Output: actual number dequeued
);

1. Load Oracle object types (OMNI_TRACER_PAYLOAD_ARRAY, OMNI_TRACER_RAW_ARRAY)
2. Create ODPI variables for output collections
3. Call ExecuteDequeueProc() to run PL/SQL procedure
4. Allocate memory for results
5. Iterate through payload collection:
   - Extract CLOB attribute from each message object
   - Read CLOB content with ReadLobContent()
   - Store in TraceMessage struct
6. Iterate through raw ID collection:
   - Extract RAW bytes
   - Store in TraceId struct
7. Return results or cleanup on error

const char* sql = "BEGIN OMNI_TRACER_API.Dequeue_Array_Events(:1, :2, :3, :4, :5, :6); END;";

// ORA-25228: Timeout or end of fetch reached
if (errorInfo.code == 25228) {
    *outCount = 0;  // No messages available
    result = 0;     // Success (not an error)
    goto cleanup;
}

static char* ReadLobContent(dpiLob* lob, uint64_t* outLength) {
    // Get LOB size
    dpiLob_getSize(lob, &size);
    
    // Allocate buffer
    char* buffer = (char*)malloc(size);
    
    // Read LOB data
    uint64_t bytesRead = size;
    dpiLob_readBytes(lob, 1, size, buffer, &bytesRead);
    
    *outLength = bytesRead;
    return buffer;  // Caller must free()
}

void FreeDequeueResults(TraceMessage* messages, TraceId* ids, uint32_t count) {
    if (messages) {
        for (uint32_t i = 0; i < count; i++) {
            if (messages[i].data) free(messages[i].data);
        }
        free(messages);
    }
    if (ids) {
        for (uint32_t i = 0; i < count; i++) {
            if (ids[i].data) free(ids[i].data);
        }
        free(ids);
    }
}

package oracle

// #cgo CFLAGS: -I${SRCDIR}/../../../../third_party/odpi/include
// #cgo LDFLAGS: -L${SRCDIR}/../../../../third_party/odpi/lib -lodpi
// #include "dequeue_ops.h"
// #include <stdlib.h>
import "C"
import "unsafe"

func DequeueMessages(conn *C.dpiConn, ctx *C.dpiContext, subscriber string, batchSize int, waitTime int) ([]Message, error) {
    // Convert Go string to C string
    cSubscriber := C.CString(subscriber)
    defer C.free(unsafe.Pointer(cSubscriber))
    
    var cMessages *C.TraceMessage
    var cIds *C.TraceId
    var actualCount C.uint32_t
    
    // Call C function
    result := C.DequeueManyAndExtract(
        conn, ctx, cSubscriber,
        C.uint32_t(batchSize),
        C.int32_t(waitTime),
        &cMessages, &cIds, &actualCount,
    )
    
    if result != 0 {
        return nil, errors.New("dequeue failed")
    }
    
    // Convert C results to Go
    messages := make([]Message, int(actualCount))
    for i := 0; i < int(actualCount); i++ {
        msg := C.GetMessage(cMessages, C.int(i))  // Helper to get array element
        messages[i] = Message{
            Data: C.GoBytes(unsafe.Pointer(msg.data), C.int(msg.length)),
            ID:   // ... extract ID
        }
    }
    
    // Free C memory
    C.FreeDequeueResults(cMessages, cIds, actualCount)
    
    return messages, nil
}

make check-cgo

CGO_ENABLED=1 go build -x ./internal/adapter/storage/oracle

// ❌ WRONG: String gets freed before C function returns
name := "subscriber"
result := C.DoSomething(C.CString(name))

// ✅ CORRECT: Keep pointer alive and free after
cName := C.CString(name)
defer C.free(unsafe.Pointer(cName))
result := C.DoSomething(cName)

// ❌ WRONG: Go pointer might move during C call
var data []byte
C.ProcessData(unsafe.Pointer(&data[0]))  // Dangerous!

// ✅ CORRECT: Pin memory or copy to C-allocated buffer
cData := C.malloc(C.size_t(len(data)))
defer C.free(cData)
C.memcpy(cData, unsafe.Pointer(&data[0]), C.size_t(len(data)))

// Enable ODPI-C error reporting in dequeue_ops.c
#define CHECK_DPI(status, ctx, msg) \
    if (status != DPI_SUCCESS) { \
        dpiErrorInfo errorInfo; \
        dpiContext_getError((ctx), &errorInfo); \
        fprintf(stderr, "[C ERROR] %s: %.*s\n", \
                (msg), (int)errorInfo.messageLength, errorInfo.message); \
        return -1; \
    }

# Oracle Instant Client location
export INSTANT_CLIENT_DIR=/opt/oracle/instantclient_23_7

# CGO must be enabled (default is 1)
export CGO_ENABLED=1

# Force CGO to use specific compiler
export CC=gcc-11

# Add extra compiler flags
export CGO_CFLAGS="$CGO_CFLAGS -DDEBUG -g"

# Add extra linker flags
export CGO_LDFLAGS="$CGO_LDFLAGS -v"