La traduzione di questa pagina non è aggiornata. Fai clic qui per vedere l'ultima versione in inglese.

coder.extrinsic

Dichiarare la funzione come estrinseca ed eseguirla in MATLAB

Sintassi

coder.extrinsic(function)

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

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

Descrizione

coder.extrinsic(function) dichiara function come funzione estrinseca. Il generatore di codice non produce codice per il corpo della funzione estrinseca, ma utilizza invece il motore di MATLAB^® per eseguire la chiamata. Questa funzionalità è disponibile solo quando il motore di MATLAB è disponibile durante l'esecuzione. Esempi di situazioni in cui è disponibile il motore di MATLAB includono l'esecuzione di funzioni MEX, simulazioni Simulink^® e chiamate di funzione al momento della generazione di codice, noto anche come fase di compilazione.

Durante la generazione di codice autonomo, il generatore di codice tenta di determinare se la funzione estrinseca influisce sulla funzione in cui viene chiamata. Se la funzione estrinseca non influisce sulla funzione di chiamata (ad esempio, la funzione estrinseca visualizza un grafico), il generatore di codice procede con la generazione di codice, ma esclude la funzione estrinseca dal codice generato. Se la funzione estrinseca influisce sulla funzione di chiamata (ad esempio, la funzione estrinseca restituisce un valore alla funzione di chiamata), il generatore di codice produce un errore di compilazione.

MATLAB ignora la direttiva coder.extrinsic esterna alla generazione di codice.

Vedere Use MATLAB Engine to Execute a Function Call in MATLAB Function Blocks.

Nota

L'output di runtime di una funzione estrinseca è un mxArray, noto anche come array MATLAB. Le uniche operazioni valide per un mxArray sono memorizzarlo in una variabile, passarlo a un'altra funzione estrinseca o restituirlo a MATLAB. Per eseguire qualsiasi altra operazione su un valore mxArray, ad esempio utilizzarlo in un'espressione nel codice, è necessario convertire mxArray in un tipo noto, assegnando mxArray una variabile il cui tipo è già definito da un compito precedente. Vedere Working with mxArrays (MATLAB Coder).

coder.extrinsic(function1,...,functionN) dichiara function1 tramite functionN come funzioni estrinseche.

coder.extrinsic(syn, function1, ... ,functionN) controlla la sincronizzazione dei dati globali tra il codice MATLAB e il file MEX generato prima e dopo la chiamata alla funzione estrinseca. Per impostazione predefinita, il generatore di codice sincronizza le variabili globali prima e dopo le chiamate alle funzioni estrinseche per massimizzare la coerenza tra il codice MATLAB e la funzione MEX. Per scoprire come e quando modificare questo comportamento predefinito, vedere Generate Code for Global Variables (MATLAB Coder).

Esempi

Chiamata alla funzione estrinseca

Definire la funzione locale convertStringToNumber, che visualizza l'output della funzione di MATLAB str2num. Poiché str2num non è supportato per la generazione di codice, è necessario dichiarare questa funzione come estrinseca nel codice MATLAB. Dichiarando str2num come funzione estrinseca, si indica al generatore di codice di non produrre codice per str2num. Il generatore di codice invia invece str2num a MATLAB per l'esecuzione. convertStringToNumber visualizza il valore restituito da str2num utilizzando disp, che il generatore di codice considera automaticamente come estrinseca.

type("convertStringToNumber.m")

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

Generare codice MEX per convertStringToNumber. Specificare che l'input sia un vettore di caratteri illimitato.

codegen convertStringToNumber -args {coder.typeof('c', [1 Inf])} -report

Code generation successful: View report

Nel file convertStringToNumber.c, visualizzabile dal report sulla generazione di codice, è possibile notare che non è stato generato alcun codice C per le funzioni MATLAB di disp e str2num. Il codice generato invia invece queste funzioni a MATLAB per l'esecuzione utilizzando la funzione interna emlrtCallMATLABR2012b.

Chiamare il codice MEX generato per convertStringToNumber utilizzando un vettore di caratteri:

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

Restituzione dell'output della funzione estrinseca in fase di runtime

Definire la funzione locale returnStringToNumber, che restituisce l'output della funzione di MATLAB str2num a MATLAB. Poiché str2num non è supportato per la generazione di codice, è necessario dichiarare questa funzione come estrinseca nel codice MATLAB. Dichiarando str2num come funzione estrinseca, si indica al generatore di codice di non produrre codice per str2num. Il generatore di codice invia invece str2num a MATLAB per l'esecuzione. Il valore restituito da str2num in fase di runtime è un mxArray, noto anche come array MATLAB. Le uniche operazioni valide per un mxArray sono memorizzarlo in una variabile, passarlo a un'altra funzione estrinseca o restituirlo a MATLAB. Vedere Working with mxArrays (MATLAB Coder).

type returnStringToNumber.m

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

Generare codice MEX per returnStringToNumber. Specificare che l'input sia un vettore di caratteri illimitato.

codegen returnStringToNumber -args {coder.typeof('c', [1 Inf])} -report

Code generation successful: View report

Nel report sulla generazione di codice, è possibile notare che num è un mxArray.

Chiamare il codice MEX generato per returnStringToNumber utilizzando un vettore di caratteri:

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

Sebbene returnStringToNumber_mex restituisca un mxArray, MATLAB interpreta correttamente l'output come un vettore numerico.

Utilizzo dell'output della funzione estrinseca in fase di runtime

Definire la funzione locale useStringToNumber, che visualizza messaggi diversi in base all'output della funzione MATLAB str2num. Poiché str2num non è supportato per la generazione di codice, è necessario dichiarare questa funzione come estrinseca nel codice MATLAB. Dichiarando str2num come funzione estrinseca, si indica al generatore di codice di non produrre codice per str2num. Il generatore di codice invia invece str2num a MATLAB per l'esecuzione. Il valore restituito da str2num in fase di runtime è un mxArray, noto anche come array MATLAB.

Le uniche operazioni valide per un mxArray sono memorizzarlo in una variabile, passarlo a un'altra funzione estrinseca o restituirlo a MATLAB. Per eseguire qualsiasi altra operazione su un valore mxArray, ad esempio utilizzarlo in un'espressione nel codice, è necessario convertire mxArray in un tipo noto, assegnando mxArray una variabile il cui tipo è già definito da un compito precedente. Vedere Working with mxArrays (MATLAB Coder).

Per utilizzare mxArray che str2num restituisce in useStringToNumber, inizializzare num come double prima della chiamata alla funzione estrinseca. In fase di compilazione, il generatore di codice converte automaticamente mxArray restituito da str2num in un double, che è quindi possibile utilizzare nelle espressioni successive. Se non si imposta num su un tipo noto prima di utilizzarlo in un'espressione, la generazione di codice non andrà a buon fine.

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

Generare codice MEX per useStringToNumber. Specificare che l'input sia un vettore character illimitato.

codegen useStringToNumber -args {coder.typeof('c', [1 Inf])} -report

Code generation successful: View report

Nel report sulla generazione di codice, è possibile notare che l'output di str2num è un mxArray e num è un 1 x 1 double.

Chiamare il codice MEX generato per useStringToNumber utilizzando un vettore di caratteri:

useStringToNumber_mex('1,2,3')

Starts from one

useStringToNumber_mex('3,2,1')

Does not start from one

Utilizzo dell'output di dimensione variabile della funzione estrinseca in fase di runtime

Definire la funzione locale useStringToNumberVarSize, che restituisce array di dimensioni diverse in base all'output della funzione di MATLAB str2num. Poiché str2num non è supportato per la generazione di codice, è necessario dichiarare questa funzione come estrinseca nel codice MATLAB. Dichiarando str2num come funzione estrinseca, si indica al generatore di codice di non produrre codice per str2num. Il generatore di codice invia invece str2num a MATLAB per l'esecuzione. Il valore restituito da str2num in fase di runtime è un mxArray, noto anche come array MATLAB.

Le uniche operazioni valide per un mxArray sono memorizzarlo in una variabile, passarlo a un'altra funzione estrinseca o restituirlo a MATLAB. Per eseguire qualsiasi altra operazione su un valore mxArray, ad esempio utilizzarlo in un'espressione nel codice, è necessario convertire mxArray in un tipo noto, assegnando mxArray una variabile il cui tipo è già definito da un compito precedente. Vedere Working with mxArrays (MATLAB Coder).

Poiché la dimensione dell'output mxArray di str2num è variabile in fase di runtime, inizializzare prima num come tipo noto (un array vuoto di doubles), quindi dichiarare num come a dimensione variabile utilizzando coder.varsize (MATLAB Coder). Se non si imposta num su un tipo noto prima di utilizzarlo, la generazione di codice non andrà a buon fine. Se non si dichiara num come a dimensione variabile, l'esecuzione MEX avrà esito negativo per tutti gli array non vuoti. Per saperne di più sulla gestione dei dati a dimensione variabile per la generazione di codice, vedere Generate Code 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

Generare codice MEX per useStringToNumberVarSize. Specificare che l'input sia un vettore di caratteri illimitato.

codegen useStringToNumberVarSize -args {coder.typeof('c', [1 Inf])} -report

Code generation successful: View report

Nel report sulla generazione di codice, è possibile notare che l'output di str2num è un mxArray e che num è un array a dimensione variabile (:? x :?) di doubles.

Chiamare il codice MEX generato per useStringToNumberVarSize utilizzando un vettore di caratteri:

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

Come previsto, useStringToNumberVarSize_mex restituisce un vettore numerico di 5 elementi.

Forzatura della valutazione della chiamata alla funzione estrinseca in fase di compilazione

Se si chiama una funzione estrinseca che restituisce un valore costante, è possibile indicare al generatore di codice di valutare la funzione estrinseca in fase di compilazione utilizzando coder.const. Il generatore di codice utilizzerà quindi questa costante nel codice generato. È possibile utilizzare questo pattern di codifica per generare codice autonomo che utilizza l'output di funzioni estrinseche.

Definire la funzione del punto di ingresso rotate_complex, che ruota il numero complesso nel file complex.xml in base all'argomento di input theta. La funzione rotate_complex invoca un'altra funzione locale xml2struct, che utilizza l'API MATLAB per l'elaborazione XML al fine di convertire il numero in formato XML nel file complex.xml in una struttura. Poiché la generazione di codice non supporta l'API MATLAB per l'elaborazione XML, è necessario dichiarare la funzione xml2struct come estrinseca nel corpo della funzione rotate_complex. Dichiarando xml2struct come funzione estrinseca, si indica al generatore di codice di non produrre codice per xml2struct. Il generatore di codice invia invece xml2struct a MATLAB per l'esecuzione. Tuttavia, poiché complex.xml non cambia tra il momento della generazione di codice e la fase di runtime, è possibile indicare al generatore di codice di considerare l'output della funzione estrinseca xml2struct come una costante di runtime utilizzando coder.const. Poiché la funzione estrinseca viene valutata come costante al momento della generazione di codice, non è necessario convertire esplicitamente l'output di xml2struct in un tipo noto.

Esaminare il file di supporto complex.xml, che contiene le parti reali e immaginarie di un numero complesso.

type complex.xml

<params>
    <param name="real" value="3"/>
    <param name="imaginary" value="4"/>
</params>

Definire la funzione xml2struct, che legge il file XML passato utilizzando l'API MATLAB per l'elaborazione XML, memorizza i nomi e i valori dei parametri XML come campi della struttura e restituisce la struttura.

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

Definire la funzione del punto di ingresso di MATLAB rotate_complex, che converte complex.xml in una struttura utilizzando xml2struct. La funzione rotate_complex ruota quindi il numero complesso di un angolo pari all'argomento di input theta, espresso in gradi, e restituisce il numero complesso risultante. In questa funzione, si dichiara la funzione xml2struct come estrinseca utilizzando la direttiva coder.extrinsic e se ne valuta l'output come costante utilizzando la direttiva 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

Generare una libreria statica per rotate_complex utilizzando il comando codegen (MATLAB Coder). Specificare che il tipo di input sia uno scalare 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): View report

Esaminare il file C++ generato rotate_complex.c. Si noti che l'output della funzione xml2struct è codificato in modo statico nel codice generato.

type codegen/lib/rotate_complex/rotate_complex.c

/*
 * Prerelease License - for engineering feedback and testing purposes
 * only. Not for sale.
 * File: rotate_complex.c
 *
 * MATLAB Coder version            : 25.1
 * C/C++ source code generated on  : 01-Feb-2025 08:02:41
 */

/* 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 phase;
  phase = atan2(4.0, 3.0) + 0.017453292519943295 * theta;
  y.re = 5.0 * cos(phase);
  y.im = sin(phase);
  return y;
}

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

Argomenti di input

function — funzione di MATLAB

vettore di caratteri

La funzione di MATLAB da chiamare estrinsecamente, specificata come vettore di caratteri.

Esempio coder.extrinsic('patch')

Tipi di dati: char

syn — Sincronizzazione delle variabili globali

'-sync:on' (predefinito) | '-sync:off'

Sincronizzazione delle variabili globali, specificata come '-sync:on' o '-sync:off'. Per impostazione predefinita, il generatore di codice sincronizza le variabili globali prima e dopo ogni chiamata alla funzione estrinseca. Per scoprire come e quando modificare questo comportamento predefinito, vedere Generate Code for Global Variables (MATLAB Coder).

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

Limitazioni

• Non è possibile utilizzare coder.ceval (MATLAB Coder) su funzioni dichiarate come estrinseche utilizzando coder.extrinsic.

• Le chiamate alle funzioni estrinseche possono influire sulle prestazioni, poiché il generatore di codice copia i dati passati a una funzione estrinseca e li invia a MATLAB per l'esecuzione. Al contrario, MATLAB copia qualsiasi dato di output per riportarlo nell'ambiente della funzione MEX.

• Il generatore di codice non supporta l'utilizzo di coder.extrinsic per chiamare funzioni che si trovano in una cartella privata.

• Il generatore di codice non supporta l'utilizzo di coder.extrinsic per chiamare funzioni locali o nidificate.

• La generazione di codice non supporta i valori passati a o restituiti da funzioni estrinseche che siano o contengano:

  • Classi di handle

  • Handle della funzione

  • Valori opachi (vedere coder.opaque)

Suggerimenti

• Il generatore di codice considera automaticamente come estrinseche molte funzioni di visualizzazione di MATLAB comuni, quali plot, disp e figure. Non è necessario dichiarare esplicitamente queste funzioni come estrinseche utilizzando coder.extrinsic.

• Utilizzare la funzione coder.screener (MATLAB Coder) per rilevare quali funzioni devono essere dichiarate come estrinseche. Questa funzione esegue lo strumento di predisposizione per la generazione di codice, che analizza il codice MATLAB per individuare feature e funzioni non supportate per la generazione di codice. Vedere Check Code Using the Code Generation Readiness Tool.

Funzionalità estese

Generazione di codice C/C++
Genera codice C e C++ con MATLAB® Coder™.

Generazione di codice GPU
Genera codice CUDA® per GPU NVIDIA® con GPU Coder™.

Cronologia versioni

Introdotto in R2011a

Vedi anche

coder.ceval | coder.screener

Argomenti

• Use MATLAB Engine to Execute a Function Call in MATLAB Function Blocks
• Generate Code for Global Variables (MATLAB Coder)
• Resolution of Function Calls for Code Generation