Attributes

Attributes provide metadata to the compiler about how code should be compiled. They are placed in square brackets before declarations.

Syntax

[AttributeName]
[AttributeName(value)]
[AttributeName(key = value)]
[AttributeName(value1, key = value2)]

Attributes use PascalCase naming and support positional and named arguments. Values can be integers, floats, strings, or booleans.

Defining Attributes

Attributes are defined in std/sys/intrinsics.djinn using the attribute keyword:

// Without fields:
attribute ForceInline(AttributeTarget.Function | AttributeTarget.Method);

// With fields:
attribute Align(AttributeTarget.Struct | AttributeTarget.Field | AttributeTarget.Parameter) {
    i32 value;
}

// Compiler-filled attribute (transparent to caller):
attribute Location(AttributeTarget.Field | AttributeTarget.Parameter | AttributeTarget.Variable) {
    i8* fileName;
    i32 line;
    i32 column;
}

The attribute keyword is a contextual keyword — valid only at top-level declarations.

Function / Method Attributes

`[ForceInline]`

Forces the compiler to always inline the function at call sites:

struct Math {
    [ForceInline]
    public static i32 add(i32 a, i32 b) {
        return a + b;
    }
}

`[NoInline]`

Prevents the compiler from inlining the function:

struct Debug {
    [NoInline]
    public static void log(i8* msg) {
        printf("%s\n", msg);
    }
}

`[NoReturn]`

Marks a function that never returns (e.g., abort, infinite loop):

struct Util {
    [NoReturn]
    public static void abort() {
        while (true) {}
    }
}

`[Hot]` / `[Cold]`

Optimization hints for branch prediction. [Hot] marks frequently called functions, [Cold] marks rarely called ones:

struct Handler {
    [Hot]
    public static void fast_path(i32 x) {
        // called frequently
    }

    [Cold]
    public static void error_handler(i32 code) {
        // rarely called
    }
}

`[NoSync]`

Marks a function that does not synchronize with other threads:

[NoSync]
i32 pure_compute(i32 x) {
    return x * x + 1;
}

`[NoUnwind]`

Marks a function that never throws. Applied implicitly to all Djinn functions since Djinn has no exception mechanism.

`[WillReturn]`

Guarantees the function will always return (no infinite loops):

struct Math {
    [WillReturn]
    public static i32 abs(i32 x) {
        if (x < 0) { return -x; }
        return x;
    }
}

`[NoRecurse]`

Marks a function that does not call itself directly or indirectly.

Struct Attributes

`[Align(N)]`

Specifies memory alignment for a struct:

[Align(16)]
struct Vec4 {
    f32 x;
    f32 y;
    f32 z;
    f32 w;
}

`[intrinsic]`

Marks a struct as compiler-intrinsic. Its fields are populated by the compiler at compile time:

[intrinsic] constexpr struct Platform {
    bool Windows;
    bool Linux;
    bool MacOs;
}

`[Deprecated(message = "...")]`

Marks a declaration as deprecated with an optional message:

[Deprecated(message = "use ApiV2 instead")]
struct OldApi {
    public static void call() {}
}

Marks a parameter as compiler-provided. The compiler automatically fills in the source location (file, line, column) of the call site. The parameter is transparent to the caller — callers don't pass it:

struct Debug {
    [ForceInline]
    public static void assert(bool condition, i8* message, [Location] Location sourceLocation) {
        if (unlikely(condition == false)) {
            Debug.assert_fail(message, sourceLocation);
        }
        assume(condition);
    }
}

// Caller only passes 2 arguments — Location is injected by the compiler:
Debug::assert(x > 0, "x must be positive");

The Location struct contains:

i8* fileName — source file path
i32 line — line number
i32 column — column number

`[Llvm(...)]` Escape Hatch

For advanced users, raw LLVM attribute strings can be passed directly:

struct Util {
    [Llvm("mustprogress")]
    public static i32 compute(i32 x) {
        return x * 2;
    }
}

Multiple LLVM attributes can be specified:

[Llvm("mustprogress", "nosync")]
i32 pure(i32 x) {
    return x;
}

Implicit Attributes

The compiler automatically applies certain LLVM attributes based on language semantics:

Attribute	Applied To	Reason
`nounwind`	All Djinn functions	Djinn has no exception mechanism

Multiple Attributes

Multiple attributes can be stacked on a single declaration:

struct Math {
    [ForceInline]
    [Hot]
    public static i32 add(i32 a, i32 b) {
        return a + b;
    }
}

Attribute Reference

Attribute	Targets	Parameters	LLVM
`ForceInline`	Function, Method	-	`alwaysinline`
`NoInline`	Function, Method	-	`noinline`
`NoReturn`	Function, Method	-	`noreturn`
`Hot`	Function, Method	-	`hot`
`Cold`	Function, Method	-	`cold`
`NoSync`	Function, Method	-	`nosync`
`NoUnwind`	Function, Method	-	`nounwind`
`WillReturn`	Function, Method	-	`willreturn`
`NoRecurse`	Function, Method	-	`norecurse`
`Align`	Struct, Field, Parameter	`i32 value`	alignment
`intrinsic`	Struct	-	compile-time
`NoMangle`	Function, Struct	-	skip mangling
`Deprecated`	All	`i8* message`	-
`Llvm`	Function, Method	`i8* attr`	raw passthrough
`Location`	Field, Parameter, Variable	-	compiler-injected caller info
`Reflect`	Struct	-	generates `TypeInfoExt`