Main Content

C++ MEX API

참고

C++ MEX API는 C MEX 파일 응용 프로그램에 설명되어 있는 C MEX API와 호환되지 않습니다. 하나의 MEX 파일에서 이들 API를 섞어 사용할 수 없습니다.

C++ MEX API를 사용하여 이동 의미 체계(move semantics), 예외 처리, 메모리 관리 같은 C++11 기능을 이용하는 응용 프로그램을 만들 수 있습니다.

matlab::mex::FunctionC++ MEX 함수의 기본 클래스
matlab::mex::ArgumentListC++ MEX 함수의 입력값과 출력값을 위한 컨테이너
matlab::engine::MATLABEngineEngine API를 정의하는 클래스

matlab::mex::Function

모든 MEX 파일 구현은 matlab::mex::Function에서 파생되는 클래스입니다.

std::shared_ptr<matlab::engine::MatlabEngine> getEngine()MATLABEngine 객체에 대한 포인터 가져오기
void mexLock()메모리에서 MEX 파일 지우기 방지
void mexUnLock()메모리에서 MEX 파일 지우기 허용
std::u16string getFunctionName()현재 MEX 함수의 이름 가져오기

matlab::mex::ArgumentList

MexFunction 클래스의 operator()를 통해 전달되는 MEX 함수 인수는 matlab::mex::ArgumentList 컨테이너입니다. ArgumentList는 배열의 기본 컬렉션에 대한 전체 범위입니다. ArgumentList 객체는 다음 함수를 지원합니다.

operator[]ArgumentList의 요소에 대한 [] 인덱싱을 활성화합니다.
begin()이터레이터를 시작합니다.
end()이터레이터를 종료합니다.
size()인수 목록 내 요소 개수를 반환합니다. 호출하는 위치에서 지정된 입력값과 출력값의 개수를 확인하려면 이 함수를 사용하십시오.
empty()인수 목록이 비어 있는지 나타내는 논리값을 반환합니다(size() == 0).

C++ Engine API

다음 섹션에서 설명하는 matlab::engine::MATLABEngine API를 사용하여 MATLAB® 함수, 변수 및 객체에 액세스합니다. matlab::engine::MATLABEngine 함수를 호출하려면 matlab::mex::Function::getEngine 함수에서 반환되는 공유 포인터를 가져오십시오. 예를 들어, 다음과 같이 입력합니다.

std::shared_ptr<matlab::engine::MATLABEngine> matlabPtr = getEngine();

이 포인터를 사용하여 엔진 함수를 호출합니다. 예를 들어, 다음과 같이 입력합니다.

matlabPtr->feval(...);

MexFunction 클래스와 동일한 스레드에서만 엔진 함수를 호출합니다.

matlab::engine::MATLABEngine::feval인수와 함께 MATLAB 함수 호출
matlab::engine::MATLABEngine::fevalAsync인수 및 반환되는 값과 함께 MATLAB 함수를 비동기식으로 호출합니다.
matlab::engine::MATLABEngine::eval기본 작업 공간에서 MATLAB 명령문 실행
matlab::engine::MATLABEngine::evalAsync기본 작업 공간에서 비동기식으로 MATLAB 명령문 실행
matlab::engine::MATLABEngine::getVariableMATLAB 기본 작업 공간 또는 전역 작업 공간에서 변수 가져오기
matlab::engine::MATLABEngine::getVariableAsyncMATLAB 기본 작업 공간 또는 전역 작업 공간에서 비동기식으로 변수 가져오기
matlab::engine::MATLABEngine::setVariableMATLAB 기본 작업 공간 또는 전역 작업 공간에 변수 넣기
matlab::engine::MATLABEngine::setVariableAsyncMATLAB 기본 작업 공간 또는 전역 작업 공간에 비동기식으로 변수 넣기
matlab::engine::MATLABEngine::getProperty객체 속성 가져오기
matlab::engine::MATLABEngine::getPropertyAsync비동기식으로 객체 속성 가져오기
matlab::engine::MATLABEngine::setProperty객체 속성 설정
matlab::engine::MATLABEngine::setPropertyAsync비동기식으로 객체 속성 설정

matlab::engine::MATLABEngine::feval

std::vector<matlab::data::Array> feval(const std::u16string &function,
   const size_t numReturned,
   const std::vector<matlab::data::Array> &args,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer>,
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer>())
matlab::data::Array feval(const std::u16string &function, 
   const std::vector<matlab::data::Array> &args, 
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer>())
matlab::data::Array feval(const std::u16string &function,
   const matlab::data::Array &arg,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer>())
ResultType feval(const std::u16string &function,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output,
   const std::shared_ptr<matlab::engine::StreamBuffer> &error,
   RhsArgs&&... rhsArgs )
ResultType feval(const std::u16string &function,
   RhsArgs&&... rhsArgs)

설명

MEX 함수에서 MATLAB 함수를 호출합니다. feval을 사용하여 MEX 함수에서 전달된 인수를 포함한 MATLAB 함수를 호출하고 MATLAB의 결과를 MEX 함수로 반환합니다.

입력값과 출력값은 MATLAB Data API에 의해 정의된 유형입니다. 기본 C++ 유형을 지원하는 구문도 있습니다.

파라미터

const std::u16string &function

실행할 MATLAB 함수 또는 스크립트의 이름입니다. 이름을 std::u16string으로 지정하십시오. 또한 이 파라미터를 std::string으로 지정할 수 있습니다.

const size_t nlhs

반환된 값의 개수입니다.

const std::vector<matlab::data::Array> &args

std::vector에서 MATLAB 함수로 전달할 여러 개의 입력 인수입니다. 벡터가 MATLAB에서 열 배열로 변환됩니다.

const matlab::data::Array &arg

MATLAB 함수로 전달할 한 개의 입력 인수입니다.

const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>()

MATLAB 함수의 표준 출력값을 저장하는 데 사용되는 스트림 버퍼입니다.

const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>()

MATLAB 함수의 오류 메시지를 저장하는 데 사용되는 스트림 버퍼입니다.

RhsArgs&&... rhsArgs

함수 입력값에 사용되는 기본 C++ 데이터형입니다. feval은 다음과 같은 C++ 데이터형의 스칼라 입력값을 받습니다. bool, int8_t, int16_t, int32_t, int64_t, uint8_t, uint16_t, uint32_t, uint64_t, float, double

반환 값

std::vector<matlab::data::Array>

MATLAB 함수에서 반환되는 출력값입니다.

matlab::data::Array

MATLAB 함수에서 반환되는 한 개의 출력값입니다.

ResultType

MATLAB 함수에서 사용자가 지정한 유형으로 반환되는 출력값입니다. 여러 개의 인수를 반환하는 경우 std::tuple일 수 있습니다.

예외

matlab::engine::MATLABException

함수에 MATLAB 런타임 오류가 있습니다.

matlab::engine::TypeConversionException

MATLAB 함수의 결과를 지정된 유형으로 변환할 수 없습니다.

matlab::engine::MATLABSyntaxException

MATLAB 함수에 구문 오류가 있습니다.

자세한 내용은 Call MATLAB Functions from MEX Functions 항목을 참조하십시오.

matlab::engine::MATLABEngine::fevalAsync

FutureResult<std::vector<matlab::data::Array>> fevalAsync(const std::u16string &function,
   const size_t numReturned,
   const std::vector<matlab::data::Array> &args,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())
FutureResult<matlab::data::Array> fevalAsync(const std::u16string &function,
   const std::vector<matlab::data::Array> &args,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())
FutureResult<matlab::data::Array> fevalAsync(const std::u16string &function,
   const matlab::data::Array &arg,
   const std::shared_ptr<matlab::engine::StreamBuffer> & output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> & error = std::shared_ptr<matlab::engine::StreamBuffer>())
FutureResult<ResultType> fevalAsync(const std::u16string &function,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output,
   const std::shared_ptr<matlab::engine::StreamBuffer> &error,
   RhsArgs&&... rhsArgs)
FutureResult<ResultType> fevalAsync(const std::u16string &function,
   RhsArgs&&... rhsArgs)

설명

인수 및 반환되는 값과 함께 MATLAB 함수를 비동기식으로 호출합니다. 자세한 내용은 Making async Requests Using mexCallMATLAB 항목을 참조하십시오.

파라미터

const std::u16string &function

실행할 MATLAB 함수 또는 스크립트의 이름입니다. 이름을 std::u16string으로 지정하십시오. 또한 이 파라미터를 std::string으로 지정할 수 있습니다.

const size_t numReturned

반환된 값의 개수

const std::vector<matlab::data::Array> &args

std::vector에서 MATLAB 함수로 전달할 여러 개의 입력 인수입니다. 벡터가 MATLAB에서 열 배열로 변환됩니다.

const matlab::data::Array arg

MATLAB 함수로 전달할 한 개의 입력 인수입니다.

const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>()

MATLAB 함수의 표준 출력값을 저장하는 데 사용되는 스트림 버퍼입니다.

const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>()

MATLAB 함수의 오류 메시지를 저장하는 데 사용되는 스트림 버퍼입니다.

RhsArgs&&... rhsArgs

함수 입력값에 사용되는 기본 C++ 데이터형입니다. feval은 다음과 같은 C++ 데이터형의 스칼라 입력값을 받습니다. bool, int8_t, int16_t, int32_t, int64_t, uint8_t, uint16_t, uint32_t, uint64_t, float, double

반환 값

FutureResult

MATLAB 함수 호출의 결과를 얻는 데 사용되는 FutureResult 객체입니다.

예외

없음

matlab::engine::MATLABEngine::eval

void eval(const std::u16string &statement,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer> (),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer> ())

설명

호출하는 함수 작업 공간에서 MATLAB 명령문을 텍스트 문자열로 실행합니다.

파라미터

const std::u16string &statement

실행할 MATLAB 명령문

const std::shared_ptr<matlab::engine::StreamBuffer> &output

MATLAB 명령문의 표준 출력값을 저장하는 데 사용되는 스트림 버퍼

const std::shared_ptr<matlab::engine::StreamBuffer> &error

MATLAB 명령의 오류 메시지를 저장하는 데 사용되는 스트림 버퍼

예외

matlab::engine::MATLABExecutionException

MATLAB 명령문에 런타임 오류가 있습니다.

matlab::engine::MATLABSyntaxException

MATLAB 명령문에 구문 오류가 있습니다.

자세한 내용은 Execute MATLAB Statements from MEX Function 항목을 참조하십시오.

matlab::engine::MATLABEngine::evalAsync

FutureResult<void> evalAsync(const std::u16string &str,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer> (),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer> ())

설명

MATLAB 명령문을 비동기식으로 문자열로 실행합니다. 자세한 내용은 Making async Requests Using mexCallMATLAB 항목을 참조하십시오.

파라미터

const std::u16string &str

실행할 MATLAB 명령문

const std::shared_ptr<matlab::engine::StreamBuffer> & output

MATLAB 명령문의 표준 출력값을 저장하는 데 사용되는 스트림 버퍼입니다.

const std::shared_ptr<matlab::engine::StreamBuffer> & error

MATLAB 명령의 오류 메시지를 저장하는 데 사용되는 스트림 버퍼입니다.

반환 값

matlab::engine::FutureResult

MATLAB 명령문이 완료될 때까지 대기하는 데 사용되는 FutureResult 객체입니다.

예외

없음

matlab::engine::MATLABEngine::getVariable

matlab::data::Array getVariable(const std::u16string &varName,
    WorkspaceType workspaceType = WorkspaceType::BASE)

설명

MATLAB 기본 작업 공간 또는 전역 작업 공간에서 변수를 가져옵니다.

파라미터

const std::u16string& varName

MATLAB 작업 공간에 있는 변수의 이름입니다. 이름을 std::u16string으로 지정하십시오. 또한 이 파라미터를 std::string으로 지정할 수 있습니다.

matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE

변수를 가져올 MATLAB 작업 공간(BASE 또는 GLOBAL)입니다. 자세한 내용은 globalmatlab::engine::WorkspaceType을 참조하십시오.

반환 값

matlab::data::Array

MATLAB 기본 작업 공간 또는 전역 작업 공간에서 가져온 변수

예외

matlab::engine::MATLABExecutionException

요청한 변수가 지정된 MATLAB 기본 작업 공간 또는 전역 작업 공간에 존재하지 않습니다.

자세한 내용은 Set and Get MATLAB Variables from MEX 항목을 참조하십시오.

matlab::engine::MATLABEngine::getVariableAsync

FutureResult<matlab::data::Array> getVariableAsync(const std::u16string &varName,
    WorkspaceType workspaceType = WorkspaceType::BASE)

설명

MATLAB 기본 작업 공간 또는 전역 작업 공간에서 변수를 비동기식으로 가져옵니다.

파라미터

const std::u16string& varName

MATLAB 작업 공간에 있는 변수의 이름 이름을 std::u16string으로 지정하십시오. 또한 이 파라미터를 std::string으로 지정할 수 있습니다.

WorkspaceType workspaceType = WorkspaceType::BASE

변수를 가져올 MATLAB 작업 공간(BASE 또는 GLOBAL)입니다. 자세한 내용은 global을 참조하십시오.

반환 값

matlab::engine::FutureResult

MATLAB 작업 공간에서 얻은 변수를 matlab.data.Array로 가져오기 위해 사용할 수 있는 FutureResult 객체입니다.

예외

없음

matlab::engine::MATLABEngine::setVariable

void setVariable(const std::u16string &varName,
   const matlab::data::Array &var,
   WorkspaceType workspaceType = WorkspaceType::BASE)

설명

MATLAB 기본 작업 공간 또는 전역 작업 공간에 변수를 넣습니다. 같은 이름을 가진 변수가 MATLAB 작업 공간에 존재하는 경우 setVariable이 그 변수를 덮어씁니다.

파라미터

const std::u16string& varName

MATLAB 작업 공간에 만들 변수의 이름입니다. 이름을 std::u16string으로 지정하십시오. 또한 이 파라미터를 std::string으로 지정할 수 있습니다.

const matlab::data::Array var

MATLAB 작업 공간에 만들 변수의 값입니다.

matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE

변수를 넣을 MATLAB 작업 공간(BASE 또는 GLOBAL)입니다. 자세한 내용은 globalmatlab::engine::WorkspaceType을 참조하십시오.

자세한 내용은 Set and Get MATLAB Variables from MEX 항목을 참조하십시오.

matlab::engine::MATLABEngine::setVariableAsync

FutureResult<void> setVariableAsync(const std::u16string &varName,
   const matlab::data::Array var,
   WorkspaceType workspaceType = WorkspaceType::BASE)

설명

MATLAB 기본 작업 공간 또는 전역 작업 공간에 변수를 비동기식으로 넣습니다. 같은 이름을 가진 변수가 MATLAB 기본 작업 공간에 존재하는 경우 setVariableAsync이 그 변수를 덮어씁니다.

파라미터

const std::u16string& varName

MATLAB 작업 공간에 만들 변수의 이름입니다. 이름을 std::u16string으로 지정하십시오. 또한 이 파라미터를 std::string으로 지정할 수 있습니다.

const matlab::data::Array var

MATLAB 작업 공간에 만들 변수의 값

WorkspaceType workspaceType = WorkspaceType::BASE

MATLAB 작업 공간(BASE 또는 GLOBAL)에 변수를 넣습니다. 자세한 내용은 global을 참조하십시오.

예외

없음

matlab::engine::MATLABEngine::getProperty

matlab::data::Array getProperty(const matlab::data::Array &objectArray,
    size_t index,
    const std::u16string &propertyName)
matlab::data::Array getProperty(const matlab::data::Array &object,
    const std::u16string &propertyName)

설명

객체 속성의 값을 가져옵니다. 객체 입력 인수가 객체로 구성된 배열인 경우에는, 가져오려는 속성값을 가진 객체에 대응되는 배열 요소의 인덱스를 지정합니다.

파라미터

const matlab::data::Array &objectArray

MATLAB 객체로 구성된 배열

const matlab::data::Array &object

스칼라 MATLAB 객체

size_t index

객체 배열에 대해 0부터 시작하는 인덱스로, 속성값이 반환되는 배열에 있는 객체를 지정함

const std::u16string &propertyName

속성의 이름. 이름을 std::u16string으로 지정하십시오. 또한 이 파라미터를 std::string으로 지정할 수 있습니다.

반환 값

matlab::data::Array

명명된 속성의 값

예외

matlab::engine::MATLABExecutionException

속성이 존재하지 않습니다.

자세한 내용은 MATLAB Objects in MEX Functions 항목을 참조하십시오.

matlab::engine::MATLABEngine::getPropertyAsync

matlab::engine::FutureResult<matlab::data::Array> getPropertyAsync(const matlab::data::Array &objectArray,
    size_t index,
    const std::u16string &propertyName)
matlab::engine::FutureResult<matlab::data::Array> getPropertyAsync(const matlab::data::Array &object,
   const std::u16string &propertyName)

설명

객체 속성의 값을 비동기식으로 가져옵니다. 객체 입력 인수가 객체로 구성된 배열인 경우에는, 가져오려는 속성값을 가진 객체에 대응되는 배열 요소의 인덱스를 지정합니다.

파라미터

const matlab::data::Array &objectArray

MATLAB 객체로 구성된 배열

const matlab::data::Array &object

스칼라 MATLAB 객체

size_t index

객체 배열에 대해 0부터 시작하는 인덱스로, 속성값이 반환되는 배열에 있는 객체를 지정함

const std::u16string &propertyName

속성의 이름. 이름을 std::u16string으로 지정하십시오. 또한 이 파라미터를 std::string으로 지정할 수 있습니다.

반환 값

matlab::engine::FutureResult

작업을 동기화하는 데 사용되는 matlab::engine::FutureResult 객체입니다.

예외

없음

matlab::engine::MATLABEngine::setProperty

void setProperty(matlab::data::Array &objectArray,   
    size_t index,
    const std::u16string &propertyName,
    const matlab::data::Array &propertyValue)
void setProperty(matlab::data::Array &object, 
    const std::u16string &propertyName,
    const matlab::data::Array &propertyValue)

설명

객체 속성의 값을 설정합니다. 객체 입력 인수가 객체로 구성된 배열인 경우에는, 설정하려는 속성값을 가진 객체에 대응되는 배열 요소의 인덱스를 지정합니다.

파라미터

matlab::data::Array &objectArray

MATLAB 객체로 구성된 배열

matlab::data::Array &object

스칼라 MATLAB 객체

size_t index

객체 배열에 대해 0부터 시작하는 인덱스로, 속성값이 설정되는 배열에 있는 객체를 지정함

const std::u16string &propertyName

설정할 속성의 이름입니다. 이름을 std::u16string으로 지정하십시오. 또한 이 파라미터를 std::string으로 지정할 수 있습니다.

const matlab::data::Array &propertyValue

속성에 할당되는 값

예외

matlab::engine::MATLABExecutionException

속성이 존재하지 않습니다.

자세한 내용은 MATLAB Objects in MEX Functions 항목을 참조하십시오.

matlab::engine::MATLABEngine::setPropertyAsync

FutureResult<void> setPropertyAsync(matlab::data::Array &objectArray,   
    size_t index,
    const std::u16string &propertyName,
    const matlab::data::Array &propertyValue)
FutureResult<void> setPropertyAsync(matlab::data::Array &object,
 const std::u16string &propertyName,
 const matlab::data::Array &propertyValue)

설명

객체 속성의 값을 비동기식으로 설정합니다. 객체 입력 인수가 객체로 구성된 배열인 경우에는, 설정하려는 속성값을 가진 객체에 대응되는 배열 요소의 인덱스를 지정합니다.

파라미터

matlab::data::Array &objectArray

MATLAB 객체로 구성된 배열

matlab::data::Array &object

스칼라 MATLAB 객체

size_t index

객체 배열에 대해 0부터 시작하는 인덱스로, 속성값이 설정되는 배열에 있는 객체를 지정함

const std::u16string &propertyName

설정할 속성의 이름입니다. 이름을 std::u16string으로 지정하십시오. 또한 이 파라미터를 std::string으로 지정할 수 있습니다.

const matlab::data::Array &propertyValue

속성에 할당되는 값입니다.

예외

없음

예외 클래스

예외원인

matlab::engine::EngineException

함수에 MATLAB 런타임 오류가 있거나 MATLAB이 시작하지 못합니다.

matlab::engine::MATLABSyntaxException

MATLAB 함수에 구문 오류가 있습니다.

matlab::engine::MATLABExecutionException

MATLAB 함수 또는 명령문에 MATLAB 런타임 오류가 있습니다.

matlab::engine::TypeConversionException

MATLAB 함수의 결과를 지정된 유형으로 변환할 수 없습니다.

자세한 내용은 Catch Exceptions in MEX Function 항목을 참조하십시오.

관련 항목