Main Content

coder.extrinsic

함수를 외재적 함수로 선언하고 MATLAB에서 실행

페이지 내 모두 축소

구문

coder.extrinsic(function)
coder.extrinsic(function1,...,functionN)
coder.extrinsic(syn, function1, ... ,functionN)

설명

예제

coder.extrinsic(function)은 function을 외재적 함수로 선언합니다. 코드 생성기가 외재적 함수의 본문에 대해 코드를 생성하지 않고 대신 MATLAB® 엔진을 사용하여 호출을 실행합니다. 이 기능은 실행하는 동안 MATLAB 엔진이 사용 가능한 상황에서만 이용할 수 있습니다. MATLAB 엔진이 사용 가능한 상황의 예로는 MEX 함수 실행, Simulink® 시뮬레이션, 코드 생성 시점(컴파일 타임이라고도 함)의 함수 호출이 있습니다.

코드 생성기는 독립 실행형 코드를 생성할 때 외재적 함수가 이 외재적 함수를 호출한 함수에 영향을 주는지 확인합니다. 외재적 함수가 자신을 호출한 함수에 영향을 미치지 않는 경우라면(예를 들어 외재적 함수가 플롯을 표시하는 함수라면) 코드 생성기는 코드 생성을 계속 진행하지만 생성하는 코드에서 이 외재적 함수를 제외시킵니다. 외재적 함수가 자신을 호출한 함수에 영향을 미치는 경우라면(예를 들어 외재적 함수가 자신을 호출한 함수에 값을 반환한다면) 코드 생성기는 컴파일 오류를 생성합니다.

MATLAB은 코드 생성 외의 상황에서는 coder.extrinsic 지시문을 무시합니다.

Use MATLAB Engine to Execute a Function Call in Generated Codein MATLAB Function BlocksDuring Fixed-Point Algorithm Acceleration 항목을 참조하십시오.

참고

외재적 함수의 런타임 출력값은 MATLAB 배열이라고도 하는 mxArray입니다. mxArray에 대해 유효하게 수행할 수 있는 유일한 작업은 이 출력값을 변수에 저장하거나 다른 외재적 함수에 전달하거나 MATLAB에 반환하는 것입니다. 그 외의 모든 다른 작업, 예를 들어 mxArray 값을 코드 내의 표현식에 사용하는 작업이 가능하려면 사전 할당을 통해 유형이 이미 정의된 변수에 mxArray를 할당하여 mxArray를 알려진 유형으로 변환해야 합니다. Working with mxArrays (MATLAB Coder) 항목을 참조하십시오.

coder.extrinsic(function1,...,functionN)은 function1부터 functionN까지를 외재적 함수로 선언합니다.

coder.extrinsic(syn, function1, ... ,functionN)은 외재적 함수 호출 전/후에 MATLAB 코드와 생성된 MEX 파일 간의 전역 데이터 동기화를 제어합니다. 기본적으로 코드 생성기는 외재적 함수 호출 전/후에 전역 변수를 동기화하여 MATLAB 코드와 MEX 함수를 최대한 맞춥니다. 이 디폴트 동작의 변경 방법과 시점에 대해서는 Generate Code for Global Data (MATLAB Coder) 항목을 참조하십시오.

예제

모두 축소

라이브 스크립트 열기

MATLAB 함수 str2num의 출력값을 표시하는 로컬 함수 convertStringToNumber를 정의합니다. str2num은 코드 생성이 지원되지 않으므로, 이 함수를 MATLAB 코드에서 외재적 함수로 선언해야 합니다. str2num을 외재적 함수로 선언함으로써, 코드 생성기에게 str2num에 대한 코드를 생성하지 않도록 지시합니다. 대신 코드 생성기는 str2num을 MATLAB에 디스패치해서 실행합니다. convertStringToNumber는 str2num에서 반환된 값을 disp를 사용하여 표시하며, 코드 생성기는 이 함수를 자동으로 외재적 함수로 처리합니다. 

type("convertStringToNumber.m")
function convertStringToNumber(c) %#codegen
    coder.extrinsic("str2num");
    disp(str2num(c));
end

convertStringToNumber에 대한 MEX 코드를 생성합니다. 입력값을 비유계 문자형 벡터로 지정합니다.

codegen convertStringToNumber -args {coder.typeof('c', [1 Inf])} -report
Code generation successful: To view the report, open('codegen/mex/convertStringToNumber/html/report.mldatx')

파일 convertStringToNumber.c를 코드 생성 리포트에서 확인해 보면 MATLAB 함수 disp 및 str2num에 대해 생성된 C 코드가 없음을 알 수 있습니다. 대신, 생성 코드는 이 두 함수를 내부 함수 emlrtCallMATLABR2012b를 사용하여 MATLAB으로 보내서 실행합니다.

다음과 같이 문자형 벡터를 사용하여 convertStringToNumber에 대해 생성된 MEX 코드를 호출합니다.

convertStringToNumber_mex('123')
   123

convertStringToNumber_mex('1,2,3')
     1     2     3

convertStringToNumber_mex(num2str(1:10))
     1     2     3     4     5     6     7     8     9    10
라이브 스크립트 열기

MATLAB 함수 str2num의 출력값을 MATLAB에 반환하는 로컬 함수 returnStringToNumber를 정의합니다. str2num은 코드 생성이 지원되지 않으므로, 이 함수를 MATLAB 코드에서 외재적 함수로 선언해야 합니다. str2num을 외재적 함수로 선언함으로써, 코드 생성기에게 str2num에 대한 코드를 생성하지 않도록 지시합니다. 대신 코드 생성기는 str2num을 MATLAB에 디스패치해서 실행합니다. 런타임 시점에 str2num이 반환하는 값은 mxArray이며 이를 MATLAB 배열이라고도 합니다. mxArray에 대해 유효하게 수행할 수 있는 유일한 작업은 이 출력값을 변수에 저장하거나 다른 외재적 함수에 전달하거나 MATLAB에 반환하는 것입니다. Working with mxArrays (MATLAB Coder) 항목을 참조하십시오.

type returnStringToNumber.m
function num = returnStringToNumber(c) %#codegen
    coder.extrinsic("str2num");
    num = str2num(c);
end

returnStringToNumber에 대한 MEX 코드를 생성합니다. 입력값을 비유계 문자형 벡터로 지정합니다.

codegen returnStringToNumber -args {coder.typeof('c', [1 Inf])} -report
Code generation successful: To view the report, open('codegen/mex/returnStringToNumber/html/report.mldatx')

코드 생성 리포트에서 num이 mxArray임을 알 수 있습니다.

다음과 같이 문자형 벡터를 사용하여 returnStringToNumber에 대해 생성된 MEX 코드를 호출합니다.

a = returnStringToNumber_mex('123')
a = 123

b = returnStringToNumber_mex('1,2,3')
b = 1×3

     1     2     3


c = returnStringToNumber_mex(num2str(1:10))
c = 1×10

     1     2     3     4     5     6     7     8     9    10

returnStringToNumber_mex가 mxArray를 반환하더라도 MATLAB은 출력값을 숫자형 벡터로 올바르게 해석합니다.

라이브 스크립트 열기

MATLAB 함수 str2num의 출력값에 따라 다른 메시지를 표시하는 로컬 함수 useStringToNumber를 정의합니다. str2num은 코드 생성이 지원되지 않으므로, 이 함수를 MATLAB 코드에서 외재적 함수로 선언해야 합니다. str2num을 외재적 함수로 선언함으로써, 코드 생성기에게 str2num에 대한 코드를 생성하지 않도록 지시합니다. 대신 코드 생성기는 str2num을 MATLAB에 디스패치해서 실행합니다. 런타임 시점에 str2num이 반환하는 값은 mxArray이며 이를 MATLAB 배열이라고도 합니다.

mxArray에 대해 유효하게 수행할 수 있는 유일한 작업은 이 출력값을 변수에 저장하거나 다른 외재적 함수에 전달하거나 MATLAB에 반환하는 것입니다. 그 외의 모든 다른 작업, 예를 들어 mxArray 값을 코드 내의 표현식에 사용하는 작업이 가능하려면 사전 할당을 통해 유형이 이미 정의된 변수에 mxArray를 할당하여 mxArray를 알려진 유형으로 변환해야 합니다. Working with mxArrays (MATLAB Coder) 항목을 참조하십시오.

str2num이 useStringToNumber에 반환하는 mxArray를 사용하기 위해, 외재적 함수 호출 전에 num을 double형으로 초기화합니다. 코드 생성기는 컴파일 시점에 str2num에서 반환된 mxArray를 double형으로 자동 변환하며, 이를 이후 표현식에서 사용할 수 있습니다. num을 먼저 알려진 유형으로 설정하지 않은 채 표현식에 사용하면 코드 생성이 실패합니다.

type useStringToNumber.m
function useStringToNumber(c) %#codegen
   coder.extrinsic("str2num");
   num = 0;                 % initialize num as a scalar double
   num = str2num(c(1));     % force str2num to return a scalar double
   if num == 1              % because num is a known type, it can be used in expressions
       disp('Starts from one');
   else
       disp('Does not start from one');
   end
end

useStringToNumber에 대한 MEX 코드를 생성합니다. 입력값을 비유계 character형 벡터로 지정합니다.

codegen useStringToNumber -args {coder.typeof('c', [1 Inf])} -report
Code generation successful: To view the report, open('codegen/mex/useStringToNumber/html/report.mldatx')

코드 생성 리포트에서 str2num의 출력값이 mxArray이고 num이 1 x 1 double형임을 알 수 있습니다.

다음과 같이 문자형 벡터를 사용하여 useStringToNumber에 대해 생성된 MEX 코드를 호출합니다.

useStringToNumber_mex('1,2,3')
Starts from one

useStringToNumber_mex('3,2,1')
Does not start from one
라이브 스크립트 열기

MATLAB 함수 str2num의 출력값에 따라 다른 크기의 배열을 반환하는 로컬 함수 useStringToNumberVarSize를 정의합니다. str2num은 코드 생성이 지원되지 않으므로, 이 함수를 MATLAB 코드에서 외재적 함수로 선언해야 합니다. str2num을 외재적 함수로 선언함으로써, 코드 생성기에게 str2num에 대한 코드를 생성하지 않도록 지시합니다. 대신 코드 생성기는 str2num을 MATLAB에 디스패치해서 실행합니다. 런타임 시 str2num에서 반환되는 값은 MATLAB 배열이라고도 하는 mxArray입니다.

mxArray에 대해 유효하게 수행할 수 있는 유일한 작업은 이 출력값을 변수에 저장하거나 다른 외재적 함수에 전달하거나 MATLAB에 반환하는 것입니다. 그 외의 모든 다른 작업, 예를 들어 mxArray 값을 코드 내의 표현식에 사용하는 작업이 가능하려면 사전 할당을 통해 유형이 이미 정의된 변수에 mxArray를 할당하여 mxArray를 알려진 유형으로 변환해야 합니다. Working with mxArrays (MATLAB Coder) 항목을 참조하십시오.

str2num의 mxArray 출력값 크기가 런타임 시점에 바뀔 수 있으므로, 먼저 num을 알려진 유형(doubles형의 빈 배열)으로 초기화한 다음 coder.varsize (MATLAB Coder) 항목을 사용하여 num을 가변 크기로 선언하십시오. num을 사용하기 전에 이를 알려진 유형으로 설정하지 않으면 코드 생성이 실패합니다. num을 가변 크기로 선언하지 않으면, 비어 있지 않은 모든 배열에 대해 MEX 실행이 실패합니다. 코드 생성을 위한 가변 크기 데이터 처리 방법에 대해 자세히 알아보려면 Code Generation for Variable-Size Arrays (MATLAB Coder) 항목을 참조하십시오.

type useStringToNumberVarSize.m
function num = useStringToNumberVarSize(c) %#codegen
    coder.extrinsic("str2num");
    num = [];                   % initialize num as an empty array of doubles
    coder.varsize("num");       % declare num as variable-sized
    num = str2num(c);           % because num is known to be variable-sized, the generated code does not error when passed a non-empty vector
    if numel(num) > 5           % because num is a known type and not an mxArray, it can be used in expressions
        num = num(1:5);
    end
end

useStringToNumberVarSize에 대한 MEX 코드를 생성합니다. 입력값을 비유계 문자형 벡터로 지정합니다.

codegen useStringToNumberVarSize -args {coder.typeof('c', [1 Inf])} -report
Code generation successful: To view the report, open('codegen/mex/useStringToNumberVarSize/html/report.mldatx')

코드 생성 리포트에서 str2num의 출력값이 mxArray이고 num이 doubles형의 가변 크기(:? x :?) 배열임을 알 수 있습니다.

다음과 같이 문자형 벡터를 사용하여 useStringToNumberVarSize에 대해 생성된 MEX 코드를 호출합니다.

a = useStringToNumberVarSize_mex('1,2,3')
a = 1×3

     1     2     3


b = useStringToNumberVarSize_mex(num2str(1:10))
b = 1×5

     1     2     3     4     5

예상대로, useStringToNumberVarSize_mex가 요소를 5개 가진 숫자형 벡터를 반환합니다.

라이브 스크립트 열기

상수 값을 반환하는 외재적 함수를 호출하는 경우, 코드 생성기가 컴파일 시점에 coder.const 항목을 사용하여 외재적 함수를 실행하도록 지시할 수 있습니다. 그러면 코드 생성기는 이 상수를 생성 코드에 사용합니다. 외재적 함수의 출력값을 사용하는 독립 실행형 코드를 생성하는 경우에 이와 같은 코딩 패턴을 활용할 수 있습니다.

진입점 함수 rotate_complex를 정의합니다. 이 함수는 파일 complex.xml 내의 복소수를 입력 인수 theta만큼 회전합니다. 함수 rotate_complex는 또 다른 로컬 함수 xml2struct를 호출하고 이 로컬 함수는 MAXP(MATLAB API for XML processing)를 사용하여 파일 complex.xml에서 XML 형식의 숫자를 구조체로 변환합니다. MAXP는 코드 생성이 지원되지 않으므로, xml2struct 함수를 rotate_complex 함수 본문에서 외재적 함수로 선언해야 합니다. xml2struct를 외재적 함수로 선언함으로써, 코드 생성기에게 xml2struct에 대한 코드를 생성하지 않도록 지시합니다. 대신 코드 생성기는 xml2struct를 MATLAB에 디스패치해서 실행합니다. 하지만 complex.xml이 코드 생성 시점과 런타임 시점 사이에 바뀌지 않으므로, 코드 생성기가 coder.const를 사용하여 외재적 함수 xml2struct의 출력값을 런타임 상수로 처리하도록 지시할 수 있습니다. 코드 생성 시점에 이 외재적 함수에 상수 폴딩이 적용되므로 xml2struct의 출력값을 알려진 유형으로 명시적으로 변환할 필요가 없습니다.

복소수의 실수부와 허수부가 포함된 지원 파일 complex.xml을 살펴봅니다. 

type complex.xml
<params>
    <param name="real" value="3"/>
    <param name="imaginary" value="4"/>
</params>

함수 xml2struct를 정의합니다. 이 함수는 전달받은 XML 파일을 MAXP(MATLAB API for XML processing)를 사용하여 읽은 후 XML 파라미터 이름과 값을 구조체 필드로 저장하고 해당 구조체를 반환합니다. 

type xml2struct.m
function s = xml2struct(file)
s = struct();
import matlab.io.xml.dom.*
doc = parseFile(Parser,file);
els = doc.getElementsByTagName("params");
for i = 0:els.getLength-1
    it = els.item(i);
    ps = it.getElementsByTagName("param");
    for j = 0:ps.getLength-1
        param = ps.item(j);
        paramName = char(param.getAttribute("name"));
        paramValue = char(param.getAttribute("value"));
        paramValue = evalin("base", paramValue);
        s.(paramName) = paramValue;
    end
end

xml2struct를 사용하여 complex.xml을 구조체로 변환하는 MATLAB 진입점 함수 rotate_complex를 정의합니다. 그러면 함수 rotate_complex는 입력 인수 theta에 해당하는 각도(단위: 도)만큼 복소수를 회전하고, 결과 복소수를 반환합니다. 이 함수에서 coder.extrinsic 지시문을 사용하여 xml2struct 함수를 외재적 함수로 선언하고, coder.const 지시문을 사용하여 이 함수의 출력값에 대해 상수 폴딩을 수행합니다.

type rotate_complex.m
function y = rotate_complex(theta) %#codegen
coder.extrinsic("xml2struct");
s = coder.const(xml2struct("complex.xml"));

comp = s.real + 1i * s.imaginary;
magnitude = abs(comp);
phase = angle(comp) + deg2rad(theta);
y = magnitude * cos(phase) + 1i * sin(phase);

end

codegen (MATLAB Coder) 명령을 사용하여 rotate_complex에 대한 정적 라이브러리를 생성합니다. 입력 유형을 double형 스칼라로 지정합니다.

codegen -config:lib rotate_complex -args {0} -report 
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/rotate_complex/html/report.mldatx')

생성된 C++ 파일 rotate_complex.c를 살펴봅니다. xml2struct 함수의 출력값이 생성 코드에서 하드코딩되었음을 알 수 있습니다.

type codegen/lib/rotate_complex/rotate_complex.c
/*
 * File: rotate_complex.c
 *
 * MATLAB Coder version            : 24.1
 * C/C++ source code generated on  : 12-Feb-2024 20:58:34
 */

/* Include Files */
#include "rotate_complex.h"
#include <math.h>

/* Function Definitions */
/*
 * Arguments    : double theta
 * Return Type  : creal_T
 */
creal_T rotate_complex(double theta)
{
  creal_T y;
  double y_tmp;
  y_tmp = 0.017453292519943295 * theta + 0.92729521800161219;
  y.re = 5.0 * cos(y_tmp);
  y.im = sin(y_tmp);
  return y;
}

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

입력 인수

모두 축소

외재적으로 호출할 MATLAB 함수로, 문자형 벡터로 지정됩니다.

예: coder.extrinsic('patch')

데이터형: char

전역 변수 동기화로, '-sync:on' 또는 '-sync:off'로 지정됩니다. 기본적으로 코드 생성기는 외재적 함수 호출 전/후에 전역 변수를 동기화합니다. 이 디폴트 동작의 변경 방법과 시점에 대해서는 Generate Code for Global Data (MATLAB Coder) 항목을 참조하십시오.

예: coder.extrinsic('-sync:off','cellfun')

제한 사항

  • coder.extrinsic을 사용하여 외재적 함수로 선언한 함수에는 coder.ceval (MATLAB Coder)을 사용할 수 없습니다.

  • 외재적 함수 호출은 성능에 영향을 줄 수 있습니다. 코드 생성기가 외재적 함수에 전달되는 데이터를 복사한 다음 이 데이터를 실행을 위해 MATLAB으로 전송하기 때문입니다. 반대로 MATLAB은 출력 데이터를 다시 MEX 함수 환경으로 전송하기 위해 출력 데이터를 복사합니다.

  • 코드 생성기는 프라이빗 폴더에 있는 함수를 호출할 때 coder.extrinsic 사용을 지원하지 않습니다.

  • 코드 생성기는 로컬 함수를 호출할 때 coder.extrinsic 사용을 지원하지 않습니다.

  • 코드 생성은 다음 항목에 해당하는 외재적 함수 또는 다음 항목을 포함하는 외재적 함수에 전달된 값이나 그러한 외재적 함수에서 반환된 값을 지원되지 않습니다.

    • 핸들 클래스

    • 함수 핸들

    • 불투명한(opaque로 선언된) 값(coder.opaque (MATLAB Coder) 항목 참조)

팁

  • 코드 생성기는 plot, disp, figure처럼 널리 쓰이는 여러 MATLAB 시각화 함수를 자동으로 외재적 함수로 처리합니다. 이러한 함수는 coder.extrinsic을 사용하여 명시적으로 외재적 함수로 선언할 필요가 없습니다.

  • 외재적 함수로 선언해야 하는 함수를 알아내려면 coder.screener (MATLAB Coder) 함수를 사용하십시오. 이 함수는 코드 생성 준비 툴을 실행하여 MATLAB 코드에 코드 생성이 지원되지 않는 기능과 함수가 있지 않은지 검사합니다. Check Code Using the Code Generation Readiness Tool 항목을 참조하십시오.

확장 기능

C/C++ 코드 생성
MATLAB® Coder™를 사용하여 C 코드나 C++ 코드를 생성할 수 있습니다.

GPU 코드 생성
GPU Coder™를 사용하여 NVIDIA® GPU용 CUDA® 코드를 생성할 수 있습니다.

버전 내역

R2011a에 개발됨

참고 항목

도움말 항목