Documentation
¶
Overview ¶
Package objc provides the CGo runtime layer shared by all generated framework packages.
It defines the Object interface that every generated ObjC wrapper type satisfies (exposing its underlying ObjC pointer via Ptr), and supplies the low-level operations that generated code relies on at runtime:
- Memory management: Retain and Release wrap ObjC retain/release; all bridge functions return +1-retained pointers and a Go finalizer calls Release so the caller never needs to manage object lifetimes manually.
- Main-thread dispatch: RunOnMainThread executes a closure on the main GCD queue using dispatch_sync_f, which is required for all AppKit and UIKit calls.
- String conversion: helpers to marshal between NSString * and Go string.
- ObjC exception bridging: utilities used by [tel] to convert a caught NSException back into a Go panic.
All files in this package are compiled with -fno-objc-arc; reference counting is handled explicitly through the functions above.
Index ¶
- Constants
- Variables
- func AllocObject(className string) unsafe.Pointer
- func ClassNameOf(ptr unsafe.Pointer) string
- func DispatchAsyncMain(f func())
- func ExceptionReason(ptr unsafe.Pointer) string
- func FreePtr(ptr unsafe.Pointer)
- func GetAssociatedObject(obj unsafe.Pointer, key string) unsafe.Pointer
- func GoStringToNSString(s string) unsafe.Pointer
- func InstallCrashHandlers()
- func KeepAlive(v any)
- func NSErrorToError(ptr unsafe.Pointer) error
- func NSStringToGoString(ptr unsafe.Pointer) string
- func PumpMainRunLoop(seconds float64)
- func RaiseIfException(exc unsafe.Pointer)
- func Release(ptr unsafe.Pointer)
- func RemoveAssociatedObjects(obj unsafe.Pointer)
- func Retain(ptr unsafe.Pointer) unsafe.Pointer
- func RunOnMainThread(f func())
- func SetAssociatedObject(obj unsafe.Pointer, key string, value unsafe.Pointer, policy uintptr)
- func SetDeallocListener(obj unsafe.Pointer, listener func())
- func Track(wrapper any, ptrFn func() unsafe.Pointer)
- func WrapTyped[T any](ptr unsafe.Pointer, constructor func(unsafe.Pointer) T) (result T)
- type ExceptionInfo
- type NSError
- type Object
- type SyncCache
Constants ¶
const ( AssocAssign uintptr = 0 AssocRetainNonatomic uintptr = 1 AssocCopyNonatomic uintptr = 3 AssocRetain uintptr = 0x301 AssocCopy uintptr = 0x303 )
Association policies for SetAssociatedObject, mirroring objc_AssociationPolicy.
Variables ¶
var OnCallbackPanic func(name string, r any, stack []byte)
OnCallbackPanic is called when a panic is recovered inside a generated //export callback (goCallBlock_* or goCallIMP_*). Wire this to your structured logger at application startup. Called from any goroutine.
var OnException func(reason string)
OnException is called by RaiseIfException immediately before panicking with an ObjC exception. Wire this to your structured logger at application startup. Called from any goroutine; must be goroutine-safe.
var OnMainThreadPanic func(r interface{}, stack []byte)
OnMainThreadPanic is called when a panic is recovered inside a RunOnMainThread or DispatchAsyncMain closure. Wire this to your structured logger at application startup. Called on the main OS thread; must not block.
Functions ¶
func AllocObject ¶
AllocObject calls +alloc on the named ObjC class and returns the uninitialized +1-retained pointer. The caller must immediately pass it to an init method. Returns nil if the class is not registered at runtime.
func ClassNameOf ¶
ClassNameOf returns the ObjC runtime class name of the object at ptr, or "" if ptr is nil. Wraps object_getClass() + class_getName().
func DispatchAsyncMain ¶
func DispatchAsyncMain(f func())
DispatchAsyncMain schedules f to run on the macOS main OS thread without blocking. The function will be called during the next available main run loop iteration. Use this to schedule UI setup after [NSApp run] has started.
func ExceptionReason ¶
ExceptionReason extracts the reason string from a caught ObjC NSException. Deprecated: prefer ExceptionInfoFromPtr for structured access.
func FreePtr ¶
FreePtr releases a heap-allocated C pointer returned by the bridge layer. Used by generated code to free the malloc'd struct buffer after copying it into a Go value (value-type struct returns).
func GetAssociatedObject ¶
GetAssociatedObject retrieves the value previously attached to obj under key. Returns nil if no value has been set.
func GoStringToNSString ¶
GoStringToNSString converts a Go string to an ObjC NSString (+1 retain). The caller (or finalizer) is responsible for releasing the returned pointer.
func InstallCrashHandlers ¶
func InstallCrashHandlers()
InstallCrashHandlers installs an ObjC uncaught-exception handler that writes the exception name, reason, and full call-stack symbols to stderr before the process terminates. Call this as early as possible in main().
func KeepAlive ¶
func KeepAlive(v any)
KeepAlive marks v as live until the call to KeepAlive, preventing the GC from finalizing ObjC wrapper objects before a CGo call using the raw pointer has completed.
func NSErrorToError ¶
NSErrorToError converts an ObjC NSError pointer to a Go error. Releases the pointer and returns nil if ptr is nil.
func NSStringToGoString ¶
NSStringToGoString converts an ObjC NSString pointer to a Go string. Returns an empty string if ptr is nil.
func PumpMainRunLoop ¶
func PumpMainRunLoop(seconds float64)
PumpMainRunLoop runs the main NSRunLoop for up to seconds seconds, then returns. Drains pending main-queue dispatch items; useful for test binaries that need RunOnMainThread to work without a full NSApplicationMain run loop.
func RaiseIfException ¶ added in v0.5.0
RaiseIfException converts a caught ObjC NSException pointer to a Go panic. It is a no-op when exc is nil. The exception object is released by ExceptionInfoFromPtr. OnException (if set) is invoked with the reason first, giving the application a chance to log through its structured logger before the panic unwinds the stack.
func RemoveAssociatedObjects ¶
RemoveAssociatedObjects removes all associated objects from obj.
func RunOnMainThread ¶
func RunOnMainThread(f func())
RunOnMainThread executes f on the macOS main OS thread and blocks until f returns. Required for all AppKit/UIKit operations.
If the calling goroutine is already running on the main thread, f is called inline without dispatching.
func SetAssociatedObject ¶
SetAssociatedObject attaches value to obj under key using the given policy. key is a Go string; pointer identity is handled internally via a stable cache.
func SetDeallocListener ¶
SetDeallocListener fires listener exactly once when obj is deallocated by the ObjC runtime. This is the correct mechanism to notify Go when an ObjC object it holds a reference to is being torn down — for example, to clean up Go closures stored via associated objects that would otherwise be orphaned.
Internally this attaches a GoObjcDeallocListener as a retained associated object on obj. When obj is released, ObjC clears its associated objects, releasing the listener, whose -dealloc fires the callback.
func Track ¶
Track registers a finalizer on wrapper that calls Release on its ObjC pointer when the GC collects the wrapper. ptrFn must return the wrapper's ptr field.
AppKit objects (NSView and its subclasses) perform CoreAnimation layer cleanup in -dealloc that must run on the main thread. Go's finalizer goroutine is never the main thread, so we always dispatch the release to the main queue rather than calling CFRelease inline. This prevents kCAValueWeakPointer / NSViewBackingLayer corruption that causes CA::AttrList::get crashes on the next AppKit call.
func WrapTyped ¶
WrapTyped wraps an ObjC pointer in a typed Go wrapper using the provided constructor. The constructor is called only when ptr is non-nil. It is the centralised nil-guard used by generated method returns and block callbacks:
// generated method return
return objc.WrapTyped(_ptr, NewVZVirtualMachine)
// generated block callback
blocks.MakeBlock_void_ptr(func(_p0 unsafe.Pointer) {
completionHandler(objc.WrapTyped(_p0, NewVZMacOSRestoreImage), objc.NSErrorToError(_p1))
})
constructor must not be nil.
Types ¶
type ExceptionInfo ¶
type ExceptionInfo struct {
// Name is the exception class name (e.g. "NSInvalidArgumentException").
Name string
// Reason is the human-readable failure description.
Reason string
}
ExceptionInfo holds structured fields from a caught ObjC NSException.
func ExceptionInfoFromPtr ¶
func ExceptionInfoFromPtr(ptr unsafe.Pointer) ExceptionInfo
ExceptionInfoFromPtr extracts structured fields from a caught ObjC NSException, releases the exception object, and returns the populated ExceptionInfo. Returns zero value if ptr is nil.
type NSError ¶
type NSError struct {
// contains filtered or unexported fields
}
NSError wraps an ObjC NSError pointer as a Go error.
type Object ¶
Object is the constraint satisfied by every generated ObjC wrapper type. It guarantees the type exposes its underlying ObjC pointer.
func WrapObject ¶
WrapObject wraps an ObjC pointer in a minimal Object implementation. Used when a method's return type is a generic type parameter and the concrete wrapper type is not known at generation time (e.g. NSArray[T].firstObject). Returns nil when ptr is nil.
type SyncCache ¶
type SyncCache[K comparable, V any] struct { // contains filtered or unexported fields }
SyncCache is a thread-safe compute-once cache. The first call to Load for a given key invokes compute; subsequent calls return the cached value.
Source Files