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

> Discover the MulleObjCBang function, a macro defined in mulle-objc-startup-private.inc. Learn how it initializes your Mulle Objective-C universe and essential startup processes.

- Repository: [mulle-objc/mulleobjc-startup](https://github.com/mulle-objc/mulleobjc-startup)
- Tags: deep-dive
- Published: 2026-03-07

---

**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:

```c
#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:

```c
// 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.