FunctionDeclaration
FunctionDeclaration[name,typedfun]
declares name to be a typed function suitable for use in a compiler environment.
Details
- FunctionDeclaration is a symbolic representation of a declaration and does not evaluate on its own.
- The typed function in FunctionDeclaration can be of the form Typed[{t1,t2,…}tout]@Function[{x1,x2,…},body].
- A typed function in FunctionDeclaration of the form Typed[{t1,t2,…}tout]@DownValuesFunction[sym] will use function definitions attached to sym.
- A typed function in FunctionDeclaration of the form Typed[{t1,t2,…}tout]@KernelFunction[feval] will call the Wolfram Engine for the computation.
- FunctionDeclaration can be used inside of CompilerEnvironmentAppendTo and the first argument of functions like FunctionCompile.
- The name used in FunctionDeclaration can be used in more than one declaration so long as they have different types.
- The function declared in FunctionDeclaration can be used in other function declarations.
- The function declared in FunctionDeclaration can be defined for more than one type by using ForAllType.
- The type used in FunctionDeclaration can be built from new types declared by TypeDeclaration.
- A function exported from an external library can be declared by LibraryFunctionDeclaration.
- The following option is supported:
-
"Inline" Automatic whether calls to this function should be inlined or left as function calls - Possible settings for "Inline" include:
-
Automatic only inline if this function is very small "Hint" try to inline this function unless it is very large "Never" never inline this function "Always" always inline this function
Examples
open all close allBasic Examples (8)
FunctionDeclaration can be used in FunctionCompile:
decl = FunctionDeclaration[AddTwo, Typed[{"Integer64"} -> "Integer64"]@Function[arg, 2 + arg]];cf = FunctionCompile[decl, Function[Typed[arg, "Integer64"], AddTwo[arg]]]The compilation uses the function declaration:
cf[200]FunctionDeclaration can be used to add a definition to the default compiler environment:
CompilerEnvironmentAppendTo[FunctionDeclaration[AddTwo, Typed[{"Integer64"} -> "Integer64"]@Function[arg, 2 + arg]]];Use the declaration in a compilation:
cf = FunctionCompile[Function[{Typed[arg, "Integer64"]}, AddTwo[arg]]]The compilation uses the function declaration:
cf[10]Reset the compiler environment to clear the declaration:
$CompilerEnvironment = CreateCompilerEnvironment[];FunctionDeclaration can be used to add a definition to a new compiler environment:
env = CreateCompilerEnvironment[];
CompilerEnvironmentAppendTo[env, {
FunctionDeclaration[AddTwo, Typed[{"Integer64"} -> "Integer64"]@Function[arg, 2 + arg]]}];Use the CompilerEnvironment option to specify the environment:
cf = FunctionCompile[Function[{Typed[arg, "Integer64"]}, AddTwo[arg]], CompilerEnvironment -> env];cf[1]A function name can be used in more than one declaration:
decl1 = FunctionDeclaration[CheckNumber, Typed[{"Integer64"} -> "Integer64"]@Function[arg, If[arg > 2, arg, 2]]];
decl2 = FunctionDeclaration[CheckNumber, Typed[{"Integer64", "Integer64"} -> "Integer64"]@Function[{arg1, arg2}, If[arg1 > arg2, arg1, arg2]]];
CompilerEnvironmentAppendTo[{decl1, decl2}];cf = FunctionCompile[Function[{Typed[arg, "Integer64"]}, CheckNumber[arg]]];cf[1]cf = FunctionCompile[Function[{Typed[arg, "Integer64"]}, CheckNumber[arg, 4]]];cf[3]Reset the compiler environment to clear the declaration:
$CompilerEnvironment = CreateCompilerEnvironment[];A function declaration can call another declaration:
decl1 = FunctionDeclaration[CheckNumber1, Typed[{"Integer64"} -> "Integer64"]@Function[arg, CheckNumber2[arg, 2]]];
decl2 = FunctionDeclaration[CheckNumber2, Typed[{"Integer64", "Integer64"} -> "Integer64"]@Function[{arg1, arg2}, If[arg1 > arg2, arg1, arg2]]];Compilation uses both declarations:
cf = FunctionCompile[{decl1, decl2}, Function[{Typed[arg, "Integer64"]}, CheckNumber1[arg]]];cf[1]A function declaration can work for more than one type:
decl = FunctionDeclaration[printReturn, Typed[ForAllType[v, {v} -> v]]@Function[arg, Print[arg];arg]];The declaration works for an integer argument:
cf = FunctionCompile[decl, Function[{Typed[arg, "Integer64"]}, printReturn[arg]]];cf[1]
The same declaration works for a string:
cf = FunctionCompile[decl, Function[{Typed[arg, "String"]}, printReturn[arg]]];cf["hello"]
A function declaration can use definitions created with := to set up DownValues:
allGreater[list_, val_] :=
AllTrue[list, # > val&]Give the function a name and a type and state that the implementation comes from the DownValues:
decl = FunctionDeclaration[allGreater, Typed[{"PackedArray"::["MachineInteger", 1], "MachineInteger"} -> "Boolean"]@DownValuesFunction[allGreater]];Now these definitions are converted into efficient compiled code:
func = Function[{Typed[pa, "PackedArray"::["MachineInteger", 1]], Typed[val, "MachineInteger"]}, allGreater[pa, val]];
cf = FunctionCompile[decl, func];cf[{5, 6, 7, 9}, 2]What is neat is that this workflow is compatible with the uncompiled version:
func[{5, 6, 7, 9}, 2]The optimized compiled code is much faster:
data = Range[ 1, 10 ^ 4];
cf[data, 0]//RepeatedTimingfunc[data, 0]//RepeatedTimingA function declaration can be made to call the Wolfram Engine for a computation:
Call FactorInteger but give the function a different name in compiled code:
decl = FunctionDeclaration[myFactorInteger, Typed[{"MachineInteger"} -> "PackedArray"::["MachineInteger", 2]]@KernelFunction[FactorInteger]];Now a function that uses this declaration is compiled:
func = Function[{Typed[num, "Integer64"]}, myFactorInteger[num]];
cf = FunctionCompile[decl, func];The computation is done in the Wolfram Engine, so the compiled code may not have an advantage:
cf[5]Scope (1)
TypeOf and TypeEvaluate can be used to set up the types in a declaration:
type = ForAllType[{elem},
Element[elem, "Numbers"],
{elem} -> TypeEvaluate[TypeOf[Re[elem]]]];cf = FunctionCompile[FunctionDeclaration[MyFun1, Typed[type]@Function[x, Re[x]]], Function[Typed[arg, "ComplexReal64"], MyFun1[arg]]]cf[4. + 5. I]Options (1)
"Inline" (1)
A function declaration with the default setting is not inlined:
decl = FunctionDeclaration[TestFunc, Typed[{"Real64"} -> "Real64"]@Function[arg, Cos[Sin[Cos[arg]]]]];FunctionCompileExportString[decl, Function[Typed[arg, "Real64"], TestFunc[arg]], "WolframIR"]A setting of "Hint" means that the function is likely to be merged with its caller:
decl = FunctionDeclaration[TestFunc, Typed[{"Real64"} -> "Real64"]@Function[arg, Cos[Sin[Cos[arg]]]], "Inline" -> "Hint"];FunctionCompileExportString[decl, Function[Typed[arg, "Real64"], TestFunc[arg]], "WolframIR"]A very small function is merged with its caller:
decl = FunctionDeclaration[TestFunc, Typed[{"Real64"} -> "Real64"]@Function[arg, arg]];FunctionCompileExportString[decl, Function[Typed[arg, "Real64"], TestFunc[arg]], "WolframIR"]A setting of "Never" means that the function is not merged with its caller:
decl = FunctionDeclaration[TestFunc, Typed[{"Real64"} -> "Real64"]@Function[arg, arg], "Inline" -> "Never"];FunctionCompileExportString[decl, Function[Typed[arg, "Real64"], TestFunc[arg]], "WolframIR"]A setting of "Always" means that the function is always merged with its caller:
decl = FunctionDeclaration[MakePtr, Typed[{} -> "RawPointer"::["Integer64"]]@Function[{}, ToRawPointer[10]], "Inline" -> "Always"];This is useful since it means that stack allocations can be passed back:
FunctionCompileExportString[decl, Function[{}, FromRawPointer[MakePtr[]]], "WolframIR"]Text
Wolfram Research (2021), FunctionDeclaration, Wolfram Language function, https://reference.wolfram.com/language/ref/FunctionDeclaration.html.
CMS
Wolfram Language. 2021. "FunctionDeclaration." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/FunctionDeclaration.html.
APA
Wolfram Language. (2021). FunctionDeclaration. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/FunctionDeclaration.html