Performance annotations

just-makeit ships a set of compiler-hint macros and a dispatch pattern that can significantly accelerate hot DSP loops. Performance is opt-in: plain projects build and run correctly without any of it.

Enabling perf

New project:

just-makeit new my_filter --object filter --perf

Existing project (preserves all user code):

just-makeit perf

Once perf = true is recorded in just-makeit.toml, every subsequent init and add inherits it automatically.

jm_perf.h — compiler-hint macros

All macros expand to safe no-ops on unknown compilers. On x86, jm_perf.h also includes <immintrin.h> so SIMD intrinsics are available without an extra include.

JM_DEFINE_STEPS — the dispatch macro

JM_DEFINE_STEPS stamps out <fn>_steps() — the outer dispatch loop — so you never write it by hand.

Generic form

JM_DEFINE_STEPS(fn, state_t, sample_t, LENGTH, BATCH, CHUNK)

LENGTH, BATCH, and CHUNK must be integer constant expressions (no VLA).

What gets generated:

• On AVX-512: fills a stack-resident scratch buffer (L1-resident, LENGTH + CHUNK samples), calls fn##_step_batch() in strides of BATCH, then falls through to the scalar tail via fn##_step().
• Everywhere else: loops directly over fn##_step().

The three constants are the only coupling between layers. You write step(). You optionally write step_batch() for SIMD. JM_DEFINE_STEPS owns the rest.

Convention: state->delay[0..LENGTH-1] is the delay line, delay[0] = newest.

FIR filter example

In the component header — define the constants and the SIMD kernel:

#define FIR_TAPS   16              /* algorithm:   number of coefficients       */
#define FIR_LENGTH (FIR_TAPS - 1)  /* history:     samples held in delay[]      */
#define FIR_BATCH  8               /* parallelism: AVX-512 complex samples/call */

#ifdef __AVX512F__
JM_FORCEINLINE JM_HOT void
fir_filter_step_batch(
    fir_filter_state_t     *state,
    const float complex    *window,
    float complex          *out)
{
    __m512 vg  = _mm512_set1_ps(state->gain);
    __m512 acc = _mm512_setzero_ps();
    for (int k = 0; k < FIR_TAPS; k++) {
        __m512 vx = _mm512_loadu_ps((const float *)(window + FIR_LENGTH - k));
        acc = _mm512_fmadd_ps(_mm512_set1_ps(state->coeffs[k]), vx, acc);
    }
    _mm512_storeu_ps((float *)out, _mm512_mul_ps(acc, vg));
}
#endif

FIR_LENGTH is what the macro sees — the history depth. FIR_TAPS is the FIR-specific concept; step_batch() loops over it, and the window index FIR_LENGTH - k reaches back exactly TAPS samples (index 0 = oldest history, index FIR_LENGTH = current sample).

In the component source — tune the chunk size and generate steps():

#define FIR_CHUNK 256  /* tuning: samples per scratch-buffer fill */

JM_DEFINE_STEPS(fir_filter, fir_filter_state_t, float complex,
                FIR_LENGTH, FIR_BATCH, FIR_CHUNK)

See the FIR filter example for a complete walkthrough including benchmarks.

jm_simd.h — width-portable operation macros

Raw AVX intrinsics lock your step_batch() to one ISA. jm_simd.h provides macros that select the widest available instruction set at compile time — AVX-512, AVX2+FMA, or scalar — so the same source compiles everywhere.

Included automatically by jm_perf.h; can also be included standalone.

SIMD tier selection

JM_SIMD_WIDTH_F64 is always half of JM_SIMD_WIDTH_F32.

Operation macros

Dot product helper

float  jm_dot_f32(const float  *a, const float  *b, int n);
double jm_dot_f64(const double *a, const double *b, int n);

Handles the SIMD loop and scalar tail automatically.

FIR inner loop example

/* step_batch: compute one output sample from JM_SIMD_WIDTH_F32 inputs */
JM_FORCEINLINE JM_HOT void
fir_step_batch(fir_state_t *state, const float *window, float *out)
{
    JM_VEC_F32 acc = JM_ZERO_F32();
    for (int k = 0; k < N_TAPS; k++)
        JM_MAC_F32(acc, window + k, state->coeffs[k]);
    *out = JM_HSUM_F32(acc) * state->gain;
}

On AVX-512 this expands to _mm512_fmadd_ps + _mm512_reduce_add_ps. On scalar it compiles to a plain loop the compiler can auto-vectorise. No #ifdef in user code; the tier is chosen once at the top of jm_simd.h.

Additional hint macros (in jm_perf.h)

SIMD build flag

SIMD intrinsics require -march=native -ffast-math. Pass -DENABLE_SIMD=ON to CMake:

cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DENABLE_SIMD=ON
cmake --build build --parallel