Documentation

matlab::cpplib::MATLABLibrary::fevalAsync

Execute a MATLAB function from a deployable archive asynchronously

Description

Execute a function with 1 output MATLAB® Data Array argument and 1 input MATLAB Data Array argument

function name as u16string

FutureResult<matlab::data::Array> fevalAsync(const std::u16string &function, const matlab::data::Array &arg, const std::shared_ptr<StreamBuffer> &output = std::shared_ptr<StreamBuffer>(), const std::shared_ptr<StreamBuffer> &error = std::shared_ptr<StreamBuffer>())

function name as string

FutureResult<matlab::data::Array> fevalAsync(const std::string &function, const matlab::data::Array &arg, const std::shared_ptr<StreamBuffer> &output = std::shared_ptr<StreamBuffer>(), const std::shared_ptr<StreamBuffer> &error = std::shared_ptr<StreamBuffer>())

Execute a function with 1 output MATLAB Data Array argument and any number of input MATLAB Data Array arguments

function name as u16string

FutureResult<matlab::data::Array> fevalAsync(const std::u16string &function, const std::vector<matlab::data::Array> &args, const std::shared_ptr<StreamBuffer> &output = std::shared_ptr<StreamBuffer>(), const std::shared_ptr<StreamBuffer> &error = std::shared_ptr<StreamBuffer>())

function name as string

FutureResult<matlab::data::Array> fevalAsync(const std::string &function, const std::vector<matlab::data::Array> &args, const std::shared_ptr<StreamBuffer> &output = std::shared_ptr<StreamBuffer>(), const std::shared_ptr<StreamBuffer> &error = std::shared_ptr<StreamBuffer>())

Execute a function with any number of output MATLAB Data Array arguments and any number of input MATLAB Data Array arguments

function name as u16string

FutureResult<std::vector<matlab::data::Array>> fevalAsync(const std::u16string &function, const size_t nlhs, const std::vector<matlab::data::Array> &args, const std::shared_ptr<StreamBuffer> &output = std::shared_ptr<StreamBuffer>(), const std::shared_ptr<StreamBuffer> &error = std::shared_ptr<StreamBuffer>())

function name as string

FutureResult<std::vector<matlab::data::Array>> fevalAsync(const std::string &function, const size_t nlhs, const std::vector<matlab::data::Array> &args, const std::shared_ptr<StreamBuffer> &output = std::shared_ptr<StreamBuffer>(), const std::shared_ptr<StreamBuffer> &error = std::shared_ptr<StreamBuffer>())

Execute a function with native scalar input and output arguments

function name as u16string

template<class ReturnType, typename...RhsArgs>

FutureResult<ReturnType> fevalAsync(const std::u16string &function, RhsArgs&&... rhsArgs)

function name as string

template<class ReturnType, typename...RhsArgs>

FutureResult<ReturnType> fevalAsync(const std::string &function, RhsArgs&&... rhsArgs)

Execute a function with native scalar input and output arguments, with output redirection

function name as u16string

template<class ReturnType, typename...RhsArgs>

FutureResult<ReturnType> fevalAsync(const std::u16string &function, const std::shared_ptr<StreamBuffer> &output, const std::shared_ptr<StreamBuffer> &error, RhsArgs&&... rhsArgs)

function name as string

template<class ReturnType, typename...RhsArgs>

FutureResult<ReturnType> fevalAsync(const std::string &function, const std::shared_ptr<StreamBuffer> &output, const std::shared_ptr<StreamBuffer> &error, RhsArgs&&... rhsArgs)

Call a packaged MATLAB function within a C++ shared library asynchronously:

  • Without redirection of standard output or standard error:

  • With redirection of standard output:

  • With redirection of standard output and standard error:

where,

LhsItemnative scalar
RhsArgs

A sequence of one or more native scalars.

StreamBuffer

std::basic_streambuf<char16_t>

It passes the name of the function, followed by the arguments. If the specified function cannot be found in the library, an exception is thrown.

Supported native types:

  • bool

  • int8_t

  • int16_t

  • int32_t

  • int64_t

  • uint8_t

  • uint16_t

  • uint32_t

  • uint64_t

  • float

  • double

  • std:string

  • std::u16string

  • std::complex<T> where T is one of the numeric types.

Parameters

const std::u16string &function

const std::string &function

The name of a compiled MATLAB function to be evaluated specified either as u16string or string.
const size_t nlhsThe number of return values.
const std::vector<matlab::data::Array> argsArguments used by the MATLAB function.
const matlab::data::Array argArgument used by the MATLAB function with single input.
const RhsArgs& rhsArgs

Template parameter pack consisting of a sequence of one or more arguments, each of which is a native scalar.

const std::shared_ptr<StreamBuffer>& outputString buffer used to store the standard output from the MATLAB function.
const std::shared_ptr<StreamBuffer>& errorString buffer used to store error output from the MATLAB function.

Return Value

FutureResult

Takes any of the permissible types for LhsItem.

Exceptions

matlab::cpplib::CanceledException

The MATLAB function is canceled.

matlab::cpplib::InterruptedException

The MATLAB function is interrupted.

matlab::cpplib::MATLABNotAvailableError

The MATLAB session is not available.

matlab::cpplib::MATLABSyntaxError

The MATLAB function returned a syntax error.

matlab::cpplib::MATLABExecutionError

The function returns a MATLAB error.

matlab::cpplib::TypeConversionError

The result of a MATLAB function cannot be converted into a user-specific type.

Examples

Execute a User-Written MATLAB Function repeatdouble in a C++ Shared Library Asynchronously

 / Call the function repeatdouble, which iteratively continues to
        // double a number, printing out results along the way.  The 
        // (optional) second and third parameters determine, respectively, how 
        // many iterations should be performed and how many seconds should 
        // elapse between operations. We call the function asynchronously, 
        // then call it again (also asynchronously) with a different base 
        // number before all the iterations from the first call have completed.

        // We pass the arguments to the function as C++ native types (namely 
        // doubles) rather than a md::Array. The return type is also a native 
        // type (a double), so fevalAsync and the FutureResult need to take 
        // "double" as a template parameter.
        mc::FutureResult<double> futureA = lib->fevalAsync<double>(
            mc::convertUTF8StringToUTF16String("repeatdouble"), 10.0, 3.0, 0.5);
        mc::FutureResult<double> futureB = lib->fevalAsync<double>(
            mc::convertUTF8StringToUTF16String("repeatdouble"), 11.0, 3.0, 0.5);
            
        // Get the result once it's ready.
        double resultA = futureA.get();
        double resultB = futureB.get();

Introduced in R2018a