Attributes

Attributes are metadata attached to items (functions, structs, enums) that modify their behavior or provide information to the compiler.

Syntax

Attributes are placed above the item they annotate, prefixed with #[...]:

#[attribute_name]
fn function() { }

#[attribute_name(key = value)]
fn function_with_args() { }

Energy Budget

The primary attribute in Joule. Declares the maximum energy a function is allowed to consume:

#[energy_budget(max_joules = 0.0001)]
fn efficient_add(x: i32, y: i32) -> i32 {
    x + y
}

Parameters

Multiple parameters can be combined:

#[energy_budget(max_joules = 0.001, max_watts = 20.0, max_temp_delta = 3.0)]
fn critical_path() { }

See Energy System Guide for details.

Thermal Awareness

Marks a function as thermal-aware. The compiler may insert thermal throttling checks:

#[thermal_aware]
fn heavy_compute(data: Vec<f64>) -> f64 {
    // ...
}

Test

Marks a function as a test. Test functions are collected and executed when the compiler runs with --test:

#[test]
fn test_addition() {
    assert_eq!(add(2, 3), 5);
}

#[test]
fn test_sort_correctness() {
    let data = vec![5, 3, 1, 4, 2];
    let sorted = sort(data);
    assert_eq!(sorted[0], 1);
    assert_eq!(sorted[4], 5);
}

Test Energy Reporting

Every test run includes energy consumption data. The test runner reports:

• Pass/fail status
• Energy consumed by each test (in joules)
• Total energy across all tests

joulec program.joule --test

Output:

running 3 tests
test test_addition ... ok (0.000012 J)
test test_sort_correctness ... ok (0.000089 J)
test test_fibonacci ... ok (0.000341 J)

test result: ok. 3 passed; 0 failed
total energy: 0.000442 J

Bench

Marks a function as a benchmark. Benchmark functions are collected and executed when the compiler runs with --bench:

#[bench]
fn bench_matrix_multiply() {
    let a = Matrix::random(100, 100);
    let b = Matrix::random(100, 100);
    let _ = a.multiply(b);
}

#[bench]
fn bench_sort_large() {
    let data = generate_random_vec(10000);
    let _ = sort(data);
}

Bench Energy Reporting

Benchmarks report timing and energy data over multiple iterations:

joulec program.joule --bench

Output:

running 2 benchmarks
bench bench_matrix_multiply ... 1,234 ns/iter (+/- 56) | 0.00185 J/iter
bench bench_sort_large      ...   892 ns/iter (+/- 23) | 0.00134 J/iter

total energy: 3.19 J (1000 iterations each)

Derive

Automatically implement traits for a type:

#[derive(Clone, Debug)]
pub struct Point {
    pub x: f64,
    pub y: f64,
}

Available Derive Traits

GPU Kernel

Marks a function for GPU execution (requires MLIR backend):

#[gpu_kernel]
fn vector_add(a: Vec<f32>, b: Vec<f32>) -> Vec<f32> {
    // ...
}

Visibility

While not strictly an attribute, visibility modifiers control access:

pub fn public_function() { }      // visible everywhere
pub(crate) fn crate_function() { } // visible within the crate
fn private_function() { }          // module-private (default)