Adapt to C API and fix potential handle leaks for callbacks

Also make context to manage context options lifetime and adapt related docs

Author: stringintech

kernel/chain.go

@@ -54,23 +54,6 @@ func (c *Chain) GetByHeight(height int) *BlockTreeEntry {
 	return entry
 }
 
-// GetNextBlockTreeEntry returns the next block tree entry in the active chain, or nil if block tree entry is the chain tip or not in the chain
-func (c *Chain) GetNextBlockTreeEntry(blockTreeEntry *BlockTreeEntry) (*BlockTreeEntry, error) {
-	checkReady(c)
-	if err := validateReady(blockTreeEntry); err != nil {
-		return nil, err
-	}
-
-	ptr := C.btck_chain_get_next_block_tree_entry(c.ptr, blockTreeEntry.ptr)
-	if ptr == nil {
-		return nil, nil
-	}
-
-	nextEntry := &BlockTreeEntry{ptr: ptr}
-	runtime.SetFinalizer(nextEntry, (*BlockTreeEntry).destroy)
-	return nextEntry, nil
-}
-
 // Contains returns true if the chain contains the block tree entry
 func (c *Chain) Contains(blockTreeEntry *BlockTreeEntry) bool {
 	checkReady(c)

kernel/chain_test.go

@@ -76,20 +76,6 @@ func TestChain(t *testing.T) {
 		t.Errorf("Expected block height 1, got %d", block1.Height())
 	}
 
-	// Test GetNextBlockTreeEntry
-	nextEntry, err := chain.GetNextBlockTreeEntry(genesis)
-	if err != nil {
-		t.Fatalf("Chain.GetNextBlockTreeEntry() error = %v", err)
-	}
-	if nextEntry == nil {
-		t.Fatal("Next block tree entry is nil")
-	}
-	defer nextEntry.Destroy()
-
-	if nextEntry.Height() != 1 {
-		t.Errorf("Expected next block height 1, got %d", nextEntry.Height())
-	}
-
 	// Test Contains
 	containsGenesis := chain.Contains(genesis)
 	if !containsGenesis {

kernel/context.go

@@ -16,12 +16,11 @@ var _ cManagedResource = &Context{}
 //
 // A constructed context can be safely used from multiple threads.
 type Context struct {
-	ptr *C.btck_Context
+	ptr     *C.btck_Context
+	options *ContextOptions
 }
 
 // NewContext creates a new kernel context with the specified options.
-// Kernel copies all necessary data from the options during context creation,
-// so the caller can safely free the options object after this call returns.
 func NewContext(options *ContextOptions) (*Context, error) {
 	if err := validateReady(options); err != nil {
 		return nil, err
@@ -32,21 +31,20 @@ func NewContext(options *ContextOptions) (*Context, error) {
 		return nil, ErrKernelContextCreate
 	}
 
-	ctx := &Context{ptr: ptr}
+	ctx := &Context{
+		ptr:     ptr,
+		options: options,
+	}
 	runtime.SetFinalizer(ctx, (*Context).destroy)
 	return ctx, nil
 }
 
 // NewDefaultContext creates a new kernel context with default mainnet parameters.
-// The defer statements are safe here because the Kernel copies all necessary
-// data during context creation, so the caller can safely free the options and
-// parameters objects immediately after the context is created.
 func NewDefaultContext() (*Context, error) {
 	opts, err := NewContextOptions()
 	if err != nil {
 		return nil, err
 	}
-	defer opts.Destroy()
 
 	params, err := NewChainParameters(ChainTypeMainnet)
 	if err != nil {
@@ -69,6 +67,10 @@ func (ctx *Context) destroy() {
 		C.btck_context_destroy(ctx.ptr)
 		ctx.ptr = nil
 	}
+	if ctx.options != nil {
+		ctx.options.Destroy()
+		ctx.options = nil
+	}
 }
 
 func (ctx *Context) Destroy() {

kernel/context_options.go

@@ -15,42 +15,18 @@ extern void go_notify_warning_unset_bridge(void* user_data, btck_Warning warning
 extern void go_notify_flush_error_bridge(void* user_data, const char* message, size_t message_len);
 extern void go_notify_fatal_error_bridge(void* user_data, const char* message, size_t message_len);
 extern void go_validation_interface_block_checked_bridge(void* user_data, const btck_BlockPointer* block, const btck_BlockValidationState* state);
-
-// Wrapper function: C helper to set notifications with Go callbacks
-// Converts Handle ID to void* and passes to C library
-static inline void set_notifications_wrapper(btck_ContextOptions* opts, uintptr_t handle) {
-    btck_NotificationInterfaceCallbacks callbacks = {
-        .user_data = (void*)handle,
-        .block_tip = (btck_NotifyBlockTip)go_notify_block_tip_bridge,
-        .header_tip = (btck_NotifyHeaderTip)go_notify_header_tip_bridge,
-        .progress = (btck_NotifyProgress)go_notify_progress_bridge,
-        .warning_set = (btck_NotifyWarningSet)go_notify_warning_set_bridge,
-        .warning_unset = (btck_NotifyWarningUnset)go_notify_warning_unset_bridge,
-        .flush_error = (btck_NotifyFlushError)go_notify_flush_error_bridge,
-        .fatal_error = (btck_NotifyFatalError)go_notify_fatal_error_bridge,
-    };
-    btck_context_options_set_notifications(opts, callbacks);
-}
-
-// Wrapper function: C helper to set validation interface with Go callbacks
-// Converts Handle ID to void* and passes to C library
-static inline void set_validation_interface_wrapper(btck_ContextOptions* opts, uintptr_t handle) {
-    btck_ValidationInterfaceCallbacks callbacks = {
-        .user_data = (void*)handle,
-        .block_checked = (btck_ValidationInterfaceBlockChecked)go_validation_interface_block_checked_bridge,
-    };
-    btck_context_options_set_validation_interface(opts, callbacks);
-}
 */
 import "C"
 import (
 	"runtime"
 	"runtime/cgo"
+	"unsafe"
 )
 
 var _ cManagedResource = &ContextOptions{}
 
-// ContextOptions wraps the C btck_ContextOptions
+// ContextOptions wraps the C btck_ContextOptions.
+// Once the options is set on a context, the context is responsible for its lifetime and should not be destroyed manually.
 type ContextOptions struct {
 	ptr                *C.btck_ContextOptions
 	notificationHandle cgo.Handle // Prevents notification callbacks GC until Destroy() called
@@ -87,15 +63,29 @@ func (opts *ContextOptions) SetNotifications(callbacks *NotificationCallbacks) e
 		return ErrNilNotificationCallbacks
 	}
 
+	// Clean up existing handle if present
+	if opts.notificationHandle != 0 {
+		opts.notificationHandle.Delete()
+		opts.notificationHandle = 0
+	}
+
 	// Create a handle for the callbacks - this prevents garbage collection
 	// and provides a stable ID that can be passed through C code safely
-	handle := cgo.NewHandle(callbacks)
-
-	// Call the C wrapper function to set all notification callbacks
-	C.set_notifications_wrapper(opts.ptr, C.uintptr_t(handle))
-
-	// Store the handle to prevent GC and allow cleanup
-	opts.notificationHandle = handle
+	opts.notificationHandle = cgo.NewHandle(callbacks)
+
+	// Create notification callbacks struct and call C library directly
+	notificationCallbacks := C.btck_NotificationInterfaceCallbacks{
+		user_data:         unsafe.Pointer(opts.notificationHandle),
+		user_data_destroy: nil, // Go handles memory management via cgo.Handle
+		block_tip:         C.btck_NotifyBlockTip(C.go_notify_block_tip_bridge),
+		header_tip:        C.btck_NotifyHeaderTip(C.go_notify_header_tip_bridge),
+		progress:          C.btck_NotifyProgress(C.go_notify_progress_bridge),
+		warning_set:       C.btck_NotifyWarningSet(C.go_notify_warning_set_bridge),
+		warning_unset:     C.btck_NotifyWarningUnset(C.go_notify_warning_unset_bridge),
+		flush_error:       C.btck_NotifyFlushError(C.go_notify_flush_error_bridge),
+		fatal_error:       C.btck_NotifyFatalError(C.go_notify_fatal_error_bridge),
+	}
+	C.btck_context_options_set_notifications(opts.ptr, notificationCallbacks)
 	return nil
 }
 
@@ -107,15 +97,23 @@ func (opts *ContextOptions) SetValidationInterface(callbacks *ValidationInterfac
 		return ErrNilValidationInterfaceCallbacks
 	}
 
+	// Clean up existing handle if present
+	if opts.validationHandle != 0 {
+		opts.validationHandle.Delete()
+		opts.validationHandle = 0
+	}
+
 	// Create a handle for the callbacks - this prevents garbage collection
 	// and provides a stable ID that can be passed through C code safely
-	handle := cgo.NewHandle(callbacks)
+	opts.validationHandle = cgo.NewHandle(callbacks)
 
-	// Call the C wrapper function to set all validation interface callbacks
-	C.set_validation_interface_wrapper(opts.ptr, C.uintptr_t(handle))
-
-	// Store the handle to prevent GC and allow cleanup
-	opts.validationHandle = handle
+	// Create validation callbacks struct and call C library directly
+	validationCallbacks := C.btck_ValidationInterfaceCallbacks{
+		user_data:         unsafe.Pointer(opts.validationHandle),
+		user_data_destroy: nil, // Go handles memory management via cgo.Handle
+		block_checked:     C.btck_ValidationInterfaceBlockChecked(C.go_validation_interface_block_checked_bridge),
+	}
+	C.btck_context_options_set_validation_interface(opts.ptr, validationCallbacks)
 	return nil
 }
 

kernel/logging_connection.go

@@ -8,12 +8,6 @@ package kernel
 // Bridge function: exported Go function that C library can call
 // user_data contains the cgo.Handle ID as void* for callback identification
 extern void go_log_callback_bridge(void* user_data, char* message, size_t message_len);
-
-// Wrapper function: C helper to create logging connection with Go callback
-// Converts Handle ID to void* and passes to C library
-static inline btck_LoggingConnection* create_logging_connection_wrapper(uintptr_t context, btck_LoggingOptions options) {
-    return btck_logging_connection_create((btck_LogCallback)go_log_callback_bridge, (void*)context, options);
-}
 */
 import "C"
 import (
@@ -62,9 +56,14 @@ func NewLoggingConnection(callback LogCallback, options LoggingOptions) (*Loggin
 		return nil, ErrLoggingConnectionUninitialized //FIXME
 	}
 
+	connection := &LoggingConnection{
+		ptr:    nil,
+		handle: 0,
+	}
+
 	// Create a handle for the callback - this prevents garbage collection
 	// and provides a stable ID that can be passed through C code safely
-	handle := cgo.NewHandle(callback)
+	connection.handle = cgo.NewHandle(callback)
 
 	cOptions := C.btck_LoggingOptions{
 		log_timestamps:               boolToInt(options.LogTimestamps),
@@ -74,17 +73,13 @@ func NewLoggingConnection(callback LogCallback, options LoggingOptions) (*Loggin
 		always_print_category_levels: boolToInt(options.AlwaysPrintCategoryLevel),
 	}
 
-	ptr := C.create_logging_connection_wrapper(C.uintptr_t(handle), cOptions)
-	if ptr == nil {
-		handle.Delete()
+	connection.ptr = C.btck_logging_connection_create((C.btck_LogCallback)(C.go_log_callback_bridge),
+		unsafe.Pointer(connection.handle), nil, cOptions)
+	if connection.ptr == nil {
+		connection.handle.Delete()
 		return nil, ErrKernelLoggingConnectionCreate
 	}
 
-	connection := &LoggingConnection{
-		ptr:    ptr,
-		handle: handle,
-	}
-
 	runtime.SetFinalizer(connection, (*LoggingConnection).destroy)
 	return connection, nil
 }