coder.inline

Control inlining of current function in generated code

Syntax

coder.inline(option)

Description

coder.inline(option) controls the inlining of the current function in the generated C/C++ code, as specified by option.

• coder.inline("always") instructs the code generator to replace a function call with the contents (body) of the called function in the generated code.

• coder.inline("never") prevents inlining of the current function in the generated code.

• coder.inline("default") instructs the code generator to use internal heuristics to determine whether to inline the current function.

Inlining eliminates the overhead of a function call and can create opportunities for further optimization of the generated code, but can generate larger, more complex code. Conversely, preventing inlining can simplify the mapping between the MATLAB^® code and the generated code. By default, the code generator uses internal heuristics to determine whether to inline the current function. Usually, these heuristics produce highly optimized code. Use the coder.inline optimization directive explicitly in your MATLAB functions only when you need to fine-tune these optimizations.

To control the inlining behavior of the code generator at each individual call site, use coder.inlineCall and coder.nonInlineCall.

Examples

Control Function Inlining

Create an entry-point function inliningEntryPoint that calls two local functions, local_Inline and local_NoInline. Both local functions return the square of the input value, but local_Inline uses the directive coder.inline("always"), while local_NoInline uses the directive coder.inline("never").

type inliningEntryPoint.m

function [x,y] = inliningEntryPoint(n) %#codegen
arguments
    n (1,1) double
end
x = local_Inline(n);
y = local_NoInline(n);
end

function y = local_Inline(x)
coder.inline("always");
y = x^2;
end

function y = local_NoInline(x)
coder.inline("never");
y = x^2;
end

Generate C code for inliningEntryPoint and inspect the entry-point function in the generated code. The code generator inlines the call to local_Inline but does not inline the call to local_NoInline.

codegen -config:lib inliningEntryPoint

Warning: Code generation is using a coder.EmbeddedCodeConfig object. Because
Embedded Coder is not installed, this might cause some Embedded Coder features
to fail.

Code generation successful (with warnings): To view the report, open('codegen/lib/inliningEntryPoint/html/report.mldatx')

type(fullfile("codegen","lib","inliningEntryPoint","inliningEntryPoint.c"))

/*
 * File: inliningEntryPoint.c
 *
 * MATLAB Coder version            : 24.2
 * C/C++ source code generated on  : 05-Sep-2024 16:34:52
 */

/* Include Files */
#include "inliningEntryPoint.h"

/* Function Declarations */
static double local_NoInline(double x);

/* Function Definitions */
/*
 * Arguments    : double x
 * Return Type  : double
 */
static double local_NoInline(double x)
{
  return x * x;
}

/*
 * Arguments    : double n
 *                double *x
 *                double *y
 * Return Type  : void
 */
void inliningEntryPoint(double n, double *x, double *y)
{
  *x = n * n;
  *y = local_NoInline(n);
}

/*
 * File trailer for inliningEntryPoint.c
 *
 * [EOF]
 */

Use coder.inline in Flow-Control Statements

You can use multiple coder.inline directives to control function inlining based on parameters such as input arguments.

Create the entry-point function conditionalInlining, which calls the local function simpleDivision. Use multiple coder.inline directives to instruct the code generator to inline simpleDivision only if both input arguments are scalar.

type conditionalInlining.m

function out = conditionalInlining(x,y) %#codegen
out = simpleDivision(x,y);
end

function y = simpleDivision(dividend, divisor)
if isscalar(dividend) && isscalar(divisor)
    forceInlining = "always";
else
    forceInlining = "default";
end
coder.inline(forceInlining)
y = dividend / divisor;
end

Generate C code for conditionalInlining, specifying scalar inputs, and examine the entry-point function in the generated code. The code generator inlines simpleDivision in the generated code.

codegen -config:lib conditionalInlining -args {3 4}

Warning: Code generation is using a coder.EmbeddedCodeConfig object. Because
Embedded Coder is not installed, this might cause some Embedded Coder features
to fail.

Code generation successful (with warnings): To view the report, open('codegen/lib/conditionalInlining/html/report.mldatx')

type(fullfile("codegen","lib","conditionalInlining","conditionalInlining.c"))

/*
 * File: conditionalInlining.c
 *
 * MATLAB Coder version            : 24.2
 * C/C++ source code generated on  : 05-Sep-2024 16:36:03
 */

/* Include Files */
#include "conditionalInlining.h"

/* Function Definitions */
/*
 * Arguments    : double x
 *                double y
 * Return Type  : double
 */
double conditionalInlining(double x, double y)
{
  return x / y;
}

/*
 * File trailer for conditionalInlining.c
 *
 * [EOF]
 */

Generate C code for conditionalInlining, specifying vector inputs, and examine the entry-point function in the generated code. The code generator uses internal heuristics to determine whether or not to inline simpleDivision in the generated code.

codegen -config:lib conditionalInlining -args {1:10 11:20}

Warning: Code generation is using a coder.EmbeddedCodeConfig object. Because
Embedded Coder is not installed, this might cause some Embedded Coder features
to fail.

Code generation successful (with warnings): To view the report, open('codegen/lib/conditionalInlining/html/report.mldatx')

type(fullfile("codegen","lib","conditionalInlining","conditionalInlining.c"))

/*
 * File: conditionalInlining.c
 *
 * MATLAB Coder version            : 24.2
 * C/C++ source code generated on  : 05-Sep-2024 16:36:07
 */

/* Include Files */
#include "conditionalInlining.h"
#include "mrdivide_helper.h"
#include "rt_nonfinite.h"

/* Function Definitions */
/*
 * Arguments    : const double x[10]
 *                const double y[10]
 * Return Type  : double
 */
double conditionalInlining(const double x[10], const double y[10])
{
  return mrdiv(x, y);
}

/*
 * File trailer for conditionalInlining.c
 *
 * [EOF]
 */

Input Arguments

option — Control inlining

"always" | "never" | "default"

Control inlining of the current MATLAB function, specified as "default", "always", or "never".

• coder.inline("default") instructs the code generator to use internal heuristics to determine whether to inline the current function. Use the coder.inline("default") directive only when you want to override global inlining settings. See Control Inlining to Fine-Tune Performance and Readability of Generated Code.

• coder.inline("always") instructs the code generator to replace a function call with the contents (body) of the called function in the generated code. The coder.inline("always") directive does not support the inlining of:

  • Entry-point functions

  • Recursive functions

  • Functions that contain parfor-loops

  • Functions called from parfor-loops

• coder.inline("never") prevents inlining of the current function in the generated code. The coder.inline("never") optimization directive does not prevent the inlining of:

  • Empty functions

  • Functions that return constant output

  To prevent inlining even in these situations, use the coder.ignoreConst function on an input at the function call site in your MATLAB code. See Resolve Issue: coder.inline("never") and coder.nonInlineCall Do Not Prevent Function Inlining.

Tips

• If you use the codegen or the fiaccel (Fixed-Point Designer) command, you can disable inlining for all functions by using the -O disable:inline option.

• You might have different speed and readability requirements for C/C++ code generated from functions that you write as compared to C/C++ code generated from MATLAB functions. Additional global settings enable you to control inlining for these two parts of the generated code base. See Control Inlining to Fine-Tune Performance and Readability of Generated Code.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

HDL Code Generation

Generate VHDL, Verilog and SystemVerilog code for FPGA and ASIC designs using HDL Coder™.

The coder.inline function supports MATLAB to High-Level Synthesis code generation.

Version History

Introduced in R2011a

R2024a: Support for High-Level Synthesis Code Generation

You can inline MATLAB functions in the generated HLS code.