MulleObjCBang Function: Definition, Location, and Startup Usage in MulleObjC

MulleObjCBang is a macro defined in mulle-objc-startup-private.inc that initializes a Mulle Objective-C universe by registering it with the runtime, applying configuration settings, and executing the core startup sequence.

The MulleObjCBang macro serves as the primary entry point for bootstrapping a Mulle Objective-C universe in the mulle-objc/mulleobjc-startup repository. This initialization routine bridges raw memory allocation and a fully functional Objective-C runtime environment by orchestrating the transition from a dormant struct _mulle_objc_universe to an active execution context. Understanding its definition and invocation pattern is essential for developers working with custom MulleObjC embedded systems or debugging startup failures.

What Is the MulleObjCBang Function?

Despite its function-like syntax, MulleObjCBang is implemented as a preprocessor macro rather than a C function. It encapsulates the three-phase initialization sequence required to activate a MulleObjC universe:

1. Registration: Associates the universe pointer with the global runtime registry via _mulle_objc_universe_register
2. Configuration: Applies the provided _mulle_objc_universeconfiguration settings using _mulle_objc_universe_set_configuration
3. Initialization: Executes internal setup routines including exception handler installation through _mulle_objc_universe_initialize

The macro accepts three parameters: a pointer to the struct _mulle_objc_universe being initialized, a struct mulle_allocator* for memory management, and a pointer to the universe configuration structure containing exception tables and foundation metadata.

Where Is MulleObjCBang Defined?

The definition resides in the private header file mulle-objc-startup-private.inc, which is part of the core MulleObjC runtime library (mulle-objc/mulle-objc) rather than the startup repository itself. According to the MulleObjC source code, this file is located at:

include/MulleObjC/mulle-objc-startup-private.inc

Within this header, the macro expands to a sequence of internal runtime calls wrapped in a standard do { ... } while(0) idiom to ensure safe usage within control flow statements:

#define MulleObjCBang( universe, allocator, config ) \
   do { \
      _mulle_objc_universe_register( (universe), (allocator) ); \
      _mulle_objc_universe_set_configuration( (universe), (config) ); \
      _mulle_objc_universe_initialize( (universe) ); \
   } while(0)

This implementation ensures atomic initialization by grouping the registration and configuration steps into a single compile-time expansion that behaves like a single statement.

How MulleObjCBang Is Used in mulleobjc-startup

The mulleobjc-startup repository consumes this macro in src/MulleObjC-startup.m within a static helper function named bang. This function retrieves the default universe configuration, optionally modifies it, then invokes the macro to activate the runtime:

// src/MulleObjC-startup.m
#include <MulleObjC/mulle-objc-startup-private.inc>

static void bang( struct _mulle_objc_universe *universe,
                  struct mulle_allocator *allocator,
                  void *userinfo)
{
    struct _mulle_objc_universeconfiguration   config;

    memcpy( &config,
            mulle_objc_global_get_default_universeconfiguration(),
            sizeof( config));

    MulleObjCBang( universe, allocator, &config );
}

This pattern allows the startup code to initialize the universe using runtime defaults while maintaining the flexibility to inject custom allocator strategies or configuration overrides before the bang occurs.

Summary

• MulleObjCBang is a preprocessor macro, not a function, defined in mulle-objc-startup-private.inc
• It performs three critical steps: universe registration, configuration application, and runtime initialization via internal _mulle_objc_universe_* routines
• The macro is defined in the MulleObjC runtime repository (mulle-objc/mulle-objc), not in the mulleobjc-startup repository
• It is invoked from src/MulleObjC-startup.m to transition a universe from allocated memory to an active Objective-C runtime state

Frequently Asked Questions

Is MulleObjCBang a function or a macro?

MulleObjCBang is a preprocessor macro wrapped in a do { ... } while(0) block to ensure safe usage in control flow statements. While it behaves like a function call, it expands directly to the underlying _mulle_objc_universe_register, _mulle_objc_universe_set_configuration, and _mulle_objc_universe_initialize routines at compile time.

Why is mulle-objc-startup-private.inc not in the mulleobjc-startup repository?

The header belongs to the core MulleObjC runtime library because it contains private implementation details of the universe initialization sequence. The mulleobjc-startup repository acts as a consumer and wrapper, including this header to trigger the standardized startup procedure without duplicating low-level runtime logic or exposing internal data structures.

What parameters does MulleObjCBang require?

The macro requires three parameters: a pointer to the struct _mulle_objc_universe being initialized, a struct mulle_allocator* for memory management, and a pointer to a struct _mulle_objc_universeconfiguration containing exception handler tables and foundation settings.

Can I call MulleObjCBang multiple times for the same universe?

No, MulleObjCBang should only be called once per universe instance. The underlying _mulle_objc_universe_register function assumes a pristine universe structure, and duplicate initialization attempts would trigger runtime assertions or undefined behavior in the exception handling and method cache subsystems.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}