LibraryLinkFunctionMacro.h File Reference

Small collection of macros designed to reduce the amount of boilerplate code and to work around certain MSVC bug. Defined in a separate header file to limit their scope. Use those macros only for interface functions (functions that will be loaded with LibraryFunctionLoad). More...

Detailed Description

Small collection of macros designed to reduce the amount of boilerplate code and to work around certain MSVC bug. Defined in a separate header file to limit their scope. Use those macros only for interface functions (functions that will be loaded with LibraryFunctionLoad).

Author

Rafal Chojna rafal.nosp@m.c@wo.nosp@m.lfram.nosp@m..com

Date

10/08/2017

See also

https://stackoverflow.com/questions/45590594/generic-lambda-in-extern-c-function

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	LIBRARY_LINK_FUNCTION(name)
	This macro forward declares and begins the definition of an extern "C" LibraryLink function with given name. More...
#define	LIBRARY_WSTP_FUNCTION(name)
	This macro forward declares and begins the definition of an extern "C" LibraryLink function with given name, which uses WSTP to exchange data with WolframLanguage. More...
#define	LLU_LIBRARY_FUNCTION(name)
	This macro provides all the boilerplate code needed for a typical exception-safe LibraryLink function. More...
#define	LLU_WSTP_FUNCTION(name)

Macro Definition Documentation

LIBRARY_LINK_FUNCTION

#define LIBRARY_LINK_FUNCTION

(

name

)

Value:

    EXTERN_C DLLEXPORT int name(WolframLibraryData, mint, MArgument*, MArgument); \
    int name([[maybe_unused]] WolframLibraryData libData, mint Argc, MArgument* Args, MArgument Res)

This macro forward declares and begins the definition of an extern "C" LibraryLink function with given name.

For input parameter and return type explanation see the official LibraryLink guide. WolframLibraryData parameter is marked [[maybe_unused]] because it is a common workflow to take the instance of WolframLibraryData passed to WolframLibrary_initialize function and store it with LLU::LibraryData::setLibraryData so that it is accessible everywhere. With such setup one does not need to use the WolframLibraryData copy provided to every LibraryLink function.

LIBRARY_WSTP_FUNCTION

#define LIBRARY_WSTP_FUNCTION

(

name

)

Value:

    EXTERN_C DLLEXPORT int name(WolframLibraryData, WSLINK); \
    int name([[maybe_unused]] WolframLibraryData libData, WSLINK wsl)

This macro forward declares and begins the definition of an extern "C" LibraryLink function with given name, which uses WSTP to exchange data with WolframLanguage.

For input parameter and return type explanation see the official LibraryLink guide. WolframLibraryData parameter is marked [[maybe_unused]] because it is a common workflow to take the instance of WolframLibraryData passed to WolframLibrary_initialize function and store it with LLU::LibraryData::setLibraryData so that it is accessible everywhere. With such setup one does not need to use the WolframLibraryData copy provided to every LibraryLink function.

LLU_LIBRARY_FUNCTION

#define LLU_LIBRARY_FUNCTION

(

name

)

Value:

    void impl_##name(LLU::MArgumentManager&); /* forward declaration */ \
    LIBRARY_LINK_FUNCTION(name) {                                       \
        auto err = LLU::ErrorCode::NoError;                             \
        try {                                                           \
            LLU::MArgumentManager mngr {libData, Argc, Args, Res};      \
            impl_##name(mngr);                                          \
        } catch (const LLU::LibraryLinkError& e) {                      \
            err = e.which();                                            \
        } catch (...) {                                                 \
            err = LLU::ErrorCode::FunctionError;                        \
        }                                                               \
        return err;                                                     \
    }                                                                   \
    void impl_##name(LLU::MArgumentManager& mngr)

This macro provides all the boilerplate code needed for a typical exception-safe LibraryLink function.

LLU_LIBRARY_FUNCTION(MyFunction) defines a LibraryLink function MyFunction and a regular function impl_MyFunction of type void(LLU::MArgumentManager&), which is the one you need to provide a body for. All LLU::LibraryLinkError exceptions thrown from impl_MyFunction will be caught and the error code returned to LibraryLink. All other exceptions will also be caught and translated to a FunctionError.

Note

While this macro saves quite a lot of typing it may also decrease code readability and make debugging harder so use with caution.

LLU_WSTP_FUNCTION

#define LLU_WSTP_FUNCTION

(

name

)

Value:

    void impl_##name(WSLINK&); /* forward declaration */       \
    LIBRARY_WSTP_FUNCTION(name) {                              \
        auto err = LLU::ErrorCode::NoError;                    \
        try {                                                  \
            impl_##name(wsl);                                  \
        } catch (const LLU::LibraryLinkError& e) {             \
            err = e.which();                                   \
        } catch (...) {                                        \
            err = LLU::ErrorCode::FunctionError;               \
        }                                                      \
        return err;                                            \
    }                                                          \
    void impl_##name(WSLINK& wsl)