TypeDeclaration
TypeDeclaration["Product",name,<field1type1,field2type2,…>]
represents a declaration of a product type with the specified fields.
TypeDeclaration["Abstract",name]
represents a declaration of the abstract type name.
TypeDeclaration["Alias",name,targetType]
represents a declaration of the type name using the internal representation of targetType.
TypeDeclaration["Macro",name,targetType]
represents a declaration specifying that all instances of name should be replaced with targetType.
Details and Options
- TypeDeclaration is a symbolic representation of a declaration and does not evaluate on its own.
- TypeDeclaration can be used inside of CompilerEnvironmentAppendTo and the first argument of functions like FunctionCompile.
- The following kinds of declarations are supported:
-
"Product" a type containing several fields; analogous to a struct in C "Abstract" an abstract type that concrete types can be instances of; a type class "Alias" a type that uses the same internal implementation as another type "Macro" a replacement rule that is applied to all types - When interfacing with C-compatible programs, the following type declarations are equivalent:
- The fields of a product type instance prod can be accessed and set with prod["field"].
- The following options are supported:
-
"AbstractTypes" {} abstract types containing the declared type "Creator" None a function to call to create an instance of the declared type "MemoryManaged" Automatic whether to automatically free unreferenced instances "Operations" {} operations that are available for the declared type "ReferenceSemantics" Automatic whether to internally represent the type with a pointer - By default, "Product" declarations have "MemoryManaged"True and "ReferenceSemantics"True.
- "ReferenceSemantics" can only be set to True for "Product" declarations.
- "MemoryManaged" can only be set to True for "Product" declarations with reference semantics.
- "Creator" can only be set for "Product" declarations .
- "Operations" can only be set for "Product" and "Abstract" declarations .
- "AbstractTypes" cannot be set for "Macro" declarations.
- For compatibility with C structs, product types must generally set "MemoryManaged" and "ReferenceSemantics" generally must be set to False.
- The following methods are defined for objects prod that are instances of product types:
-
prod["field"] get the value of "field" prod["field"]=val set the value of "field" DeleteObject[prod] free prod (only available if prod is not memory managed)
Examples
open all close allBasic Examples (2)
Represent a declaration of "fooInteger" as a macro type for "MachineInteger":
dec = TypeDeclaration["Macro", "fooInteger", "MachineInteger"];Compile a function using the declaration:
cf = FunctionCompile[dec, Function[Typed[arg, "fooInteger"], arg + 2]]cf[5]Globally declare "fooInteger" as a macro for "MachineInteger":
CompilerEnvironmentAppendTo[{
TypeDeclaration["Macro", "fooInteger", "MachineInteger"]
}];Compile a function using "fooInteger":
cf = FunctionCompile[Function[Typed[arg, "fooInteger"], arg + 2]]cf[5]Reset the compiler environment to clear the declaration:
$CompilerEnvironment = CreateCompilerEnvironment[];Scope (6)
"Product" (2)
A declaration of a product type:
dec = TypeDeclaration["Product", "simpleProd", <|"field1" -> "MachineInteger", "field2" -> "Boolean"|>];Compile a function that instantiates a product type and then extracts a field:
cf = FunctionCompile[dec, Function[{},
With[{prod = CreateTypeInstance["simpleProd", <|"field1" -> 12, "field2" -> True|>]},
prod["field1"]]
]]cf[]A declaration of a polymorphic product type:
dec = TypeDeclaration["Product", "polyProd"::[T], <|"field1" -> T, "field2" -> "Boolean"|>];Compile a function that accepts a machine integer and uses it to create the product type above:
cf = FunctionCompile[dec,
Function[{Typed[n, "MachineInteger"]},
Module[{prod = CreateTypeInstance["polyProd", <|"field1" -> n, "field2" -> True|>]},
prod["field1"] + 1
]
]
]cf[42]"Abstract" (1)
A declaration of an abstract type:
dec1 = TypeDeclaration["Abstract", "simpleAbstract"];A declaration of a product type that is an instance of the abstract type:
dec2 = TypeDeclaration["Product", "abstractInstance1", <|"field1" -> "MachineInteger", "field2" -> "Boolean"|>, "AbstractTypes" -> {"simpleAbstract"}];A declaration of a product type that is not an instance of the abstract type:
dec3 = TypeDeclaration["Product", "abstractInstance2", <|"field1" -> "MachineInteger", "field2" -> "Real64"|>];A declaration of a function that accepts any instance of the abstract type:
dec4 = FunctionDeclaration[fieldExtractor,
Typed[ForAllType[t, t∈"simpleAbstract", {t} -> "MachineInteger"]]@
Function[arg, arg["field1"]]
];Compile a program using the function on a type that is an instance of the abstract type:
cf = FunctionCompile[{dec1, dec2, dec3, dec4}, Function[{},
fieldExtractor[CreateTypeInstance["abstractInstance1", <|"field1" -> 12, "field2" -> True|>]]
]]cf[]The function does not accept inputs from types that are not instances of the abstract type:
FunctionCompile[Function[{},
fieldExtractor[CreateTypeInstance["abstractInstance2", <|"field1" -> 12, "field2" -> 3.4|>]]
]]
"Alias" (1)
An alias for the "String" type:
dec = TypeDeclaration["Alias", "aliasString", "String"];A function for the alias that differs from its implementation on the original type:
funcDec = FunctionDeclaration[StringLength,
Typed[{"aliasString"} -> "MachineInteger"]@
Function[arg, 12]
];Compile a program that instantiates the alias through bitcasting and then evaluates the function on it:
cf = FunctionCompile[{dec, funcDec}, Function[Typed[str, "String"],
StringLength[Cast[str, "aliasString", "BitCast"]]]]cf["hello"]"Macro" (2)
A macro for the "String" type:
dec = TypeDeclaration["Macro", "macroString", "String"];A function that refers to "String" using the macro:
cf = FunctionCompile[{dec}, Function[Typed[expr, "macroString"], StringLength[expr]]]cf["hello"]Macros are not types, but replacement rules that are applied to types when they are resolved. Therefore, it is impossible to have different definitions of the same function for a macro and the type to which it refers:
dec = TypeDeclaration["Macro", "macroString", "String"];funcDec = FunctionDeclaration[StringLength, Typed[{"macroString"} -> "MachineInteger"]@
Function[arg, 12]
];FunctionCompile[{dec, funcDec},
Function[Typed[arg, "macroString"], StringLength[arg]]]
Unlike macros, aliases are types, so functions can recognize whether they are applied to a type or an alias of that type.
Options (11)
"AbstractTypes" (2)
absDec = TypeDeclaration["Abstract", "simpleAbstract"];Represent an object that is a member of the abstract type:
prodDec = TypeDeclaration["Product", "abstractInstance", <|"field1" -> "MachineInteger", "field2" -> "Boolean"|>, "AbstractTypes" -> {"simpleAbstract"}];Represent a function that accepts any instance of the abstract type:
funcDec = FunctionDeclaration[abstractEater,
Typed[ForAllType[t, t∈"simpleAbstract", {t} -> "MachineInteger"]]@
Function[arg, 42]];Compile the function, showing that it accepts the product type that is a member of the abstract type:
cf = FunctionCompile[{absDec, prodDec, funcDec},
Function[{}, With[{
obj = CreateTypeInstance["abstractInstance", <|"field1" -> 12, "field2" -> False|>]},
abstractEater[obj]]
]]cf[]superDec = TypeDeclaration["Abstract", "superType"];Represent another abstract type that is a member of the first:
subDec = TypeDeclaration["Abstract", "subType", "AbstractTypes" -> {"superType"}];Represent a product type that is an instance of the second abstract type:
prodDec = TypeDeclaration["Product", "abstractInstance", <|"field1" -> "MachineInteger", "field2" -> "Boolean"|>, "AbstractTypes" -> {"subType"}];Represent a function that accepts any instance of the abstract type "superType":
funcDec = FunctionDeclaration[abstractEater,
Typed[ForAllType[t, t∈"superType", {t} -> "MachineInteger"]]@
Function[arg, 42]];Compile the function, showing that it accepts the product type that inherited membership in "superType" through "subType":
cf = FunctionCompile[{superDec, subDec, prodDec, funcDec},
Function[{}, With[{
obj = CreateTypeInstance["abstractInstance", <|"field1" -> 12, "field2" -> False|>]},
abstractEater[obj]]
]]cf[]"Creator" (1)
Represent a type with its own creation function:
typeDec = TypeDeclaration["Product", "TestType", <|"value" -> "MachineInteger"|>, "Creator" -> CreateTestType];Represent the implementation of the creation function:
createDec = FunctionDeclaration[CreateTestType,
Typed[{} -> "TestType"]@
Function[{}, CreateTypeInstance["TestType", <|"value" -> 10|>]]];Compile a function that uses CreateTypeInstance and calls the "Creator" function:
cf = FunctionCompile[{typeDec, createDec}, Function[{},
With[{obj = CreateTypeInstance["TestType"]},
obj["value"]
]
]]cf[]"MemoryManaged" (3)
Represent a type without automatic memory management:
unmanaged = TypeDeclaration["Product", "unmanagedType", <|"field" -> "MachineInteger"|>, "MemoryManaged" -> False];Compile a function that uses the type:
cf = FunctionCompile[unmanaged, Function[{},
With[{obj = CreateTypeInstance["unmanagedType", <|"field" -> 12|>]},
obj["field"]
]
]]The resulting function leaks memory because the object is not automatically freed:
With[{before = MemoryInUse[]},
Do[cf[], 1000];
MemoryInUse[] - before]By default, product types are automatically memory managed:
managed = TypeDeclaration["Product", "managedType", <|"field" -> "MachineInteger"|>];cf2 = FunctionCompile[managed, Function[{},
With[{obj = CreateTypeInstance["managedType", <|"field" -> 12|>]},
obj["field"]
]
]]The function that uses the memory-managed type does not leak memory:
With[{before = MemoryInUse[]},
Do[cf2[], 1000];
MemoryInUse[] - before]Represent a type without automatic memory management:
unmanaged = TypeDeclaration["Product", "unmanagedType", <|"field" -> "MachineInteger"|>, "MemoryManaged" -> False];Compile a function that uses the type and frees it with DeleteObject:
cf = FunctionCompile[unmanaged, Function[{},
Module[{obj, out},
obj = obj = CreateTypeInstance["unmanagedType", <|"field" -> 12|>];
out = obj["field"];
DeleteObject[obj];
out
]
]]The resulting function does not leak memory because it was manually freed:
With[{before = MemoryInUse[]},
Do[cf[], 1000];
MemoryInUse[] - before]Memory-managed product types include a reference count and are not compatible with external programs. When passing a product type to and from a library function, memory management should be disabled.
Compile a library defining a struct foo:
Needs["CCompilerDriver`"];
CreateLibrary["
#include \"dllexport.h\"
typedef struct {
int f1;
float f2;
} foo;
DLLEXPORT int getIntFieldRef(foo* arg) {
return arg->f1;
}", "memoryManagementExample"];Represent a compatible type with TypeDeclaration:
fooTypeDec = TypeDeclaration["Product", "foo", <|"f1" -> "CInt", "f2" -> "CFloat"|>, "MemoryManaged" -> False];Note that the compiled type "foo" is a reference type by default, and is equivalent to foo* in C.
Compile a function that calls the library using the type:
cf = FunctionCompile[{
fooTypeDec, LibraryFunctionDeclaration["getIntFieldRef", "memoryManagementExample", {"foo"} -> "CInt"]
},
Function[{},
With[{foo = CreateTypeInstance["foo", <|"f1" -> Typed[42, "CInt"], "f2" -> Typed[3.1, "CFloat"]|>]},
LibraryFunction["getIntFieldRef"][foo]
]
]
]cf[]"Operations" (3)
A declaration of a product type with one operation:
dec1 = TypeDeclaration["Product", "simpleValue", <|"value" -> "MachineInteger"|>, "Operations" -> {"Increment"}, "AbstractTypes" -> {"DataStructures"}];A declaration of the operation:
dec2 = OperationDeclaration["simpleValue", "Increment", Typed[{"simpleValue"} -> "MachineInteger"]@Function[{arg},
arg["value"]++
]];Compile a function to create an instance of the type and another to call the "Increment" operation:
funs = FunctionCompile[{dec1, dec2}, <|"create" -> Function[{}, CreateTypeInstance["simpleValue", <|"value" -> 0|>]],
"increment" -> Function[{Typed[ arg, "simpleValue"]}, arg["Increment"]]
|>]obj = funs["create"][];Call the "Increment" operation; the old value of 0 is returned:
funs["increment"][obj]Call the "Increment" operation again; now the old value is 1:
funs["increment"][obj]Operations can also be defined for an abstract type. In this case, they are available for any type that implements the abstract type.
absDec = TypeDeclaration["Abstract", "incrementer", "Operations" -> {"Increment"}];Represent an object that implements the abstract type:
prodDec = TypeDeclaration["Product", "testType", <|"value" -> "MachineInteger"|>, "AbstractTypes" -> {"incrementer", "DataStructures"}];A declaration of the operation:
decOp = OperationDeclaration["testType", "Increment", Typed[ {"testType"} -> "MachineInteger"]@Function[{arg},
arg["value"]++
]];Compile a function to create an instance of the type and another to call the "Increment" operation:
funs = FunctionCompile[{absDec, prodDec, decOp}, <|"create" -> Function[{}, CreateTypeInstance["testType", <|"value" -> 0|>]],
"increment" -> Function[{Typed[ arg, "testType"]}, arg["Increment"]]
|>]obj = funs["create"][];Call the "Increment" operation; the old value of 0 is returned:
funs["increment"][obj]Call the "Increment" operation again; now the old value is 1:
funs["increment"][obj]Operations defined for an abstract type can refer to an actual implementation:
absDec = TypeDeclaration["Abstract", "incrementer", "Operations" -> {"Increment" -> increment}];A declaration of the operation; it is written polymorphically with ForAllType:
decOp = FunctionDeclaration[increment,
Typed[ForAllType[v, {v} -> "MachineInteger"]]@Function[{arg},
arg["value"]++
]];Represent an object that is a member of the abstract type:
prodDec = TypeDeclaration["Product", "testType", <|"value" -> "MachineInteger"|>, "AbstractTypes" -> {"incrementer", "DataStructures"}];Compile a function to create an instance of the type and another to call the "Increment" operation:
funs = FunctionCompile[{absDec, prodDec, decOp}, <|"create" -> Function[{}, CreateTypeInstance["testType", <|"value" -> 0|>]],
"increment" -> Function[{Typed[ arg, "testType"]}, arg["Increment"]]
|>]obj = funs["create"][];Call the "Increment" operation; the old value of 0 is returned:
funs["increment"][obj]Call the "Increment" operation again; now the old value is 1:
funs["increment"][obj]The implementation of the operation is entirely set up by the abstract type.
A different implementation of an operation can be given. Since it is declared in a narrower way, using the actual type, it overrides that given from the abstract type:
decOp1 = OperationDeclaration["testType", "Increment", Typed[{"testType"} -> "MachineInteger"]@Function[{arg},
arg["value"] += 2
]];Compile a function to create an instance of the type and another to call the "Increment" operation:
funs = FunctionCompile[{absDec, prodDec, decOp, decOp1}, <|"create" -> Function[{}, CreateTypeInstance["testType", <|"value" -> 0|>]],
"increment" -> Function[{Typed[ arg, "testType"]}, arg["Increment"]]
|>]obj = funs["create"][];Now the "Increment" operation is different:
funs["increment"][obj]"ReferenceSemantics" (2)
Represent a type that will be passed by value instead of by reference:
valueTypeDec = TypeDeclaration["Product", "valueType", <|"field" -> "MachineInteger"|>, "ReferenceSemantics" -> False];Compile a function using the value type:
cf = FunctionCompile[valueTypeDec, Function[{},
With[{obj = CreateTypeInstance["valueType", <|"field" -> 12|>]},
obj["field"]
]
]]cf[]Compile a library defining a struct foo:
Needs["CCompilerDriver`"];
CreateLibrary["
#include \"dllexport.h\"
typedef struct {
int f1;
float f2;
} foo;
DLLEXPORT int getIntField(foo arg) {
return arg.f1;
}", "valueTypeExample"];Represent a compatible type with TypeDeclaration:
fooTypeDec = TypeDeclaration["Product", "foo", <|"f1" -> "CInt", "f2" -> "CFloat"|>, "ReferenceSemantics" -> False];Compile a function using the type:
cf = FunctionCompile[{
fooTypeDec, LibraryFunctionDeclaration["getIntField", "valueTypeExample", {"foo"} -> "CInt"]
},
Function[{},
With[{foo = CreateTypeInstance["foo", <|"f1" -> Typed[42, "CInt"], "f2" -> Typed[3.1, "CFloat"]|>]},
LibraryFunction["getIntField"][foo]
]
]
]cf[]Applications (1)
The C standard library includes a function called ldiv that computes the quotient and remainder of two integers. It returns an object declared as:
typedef struct {
long quot; /* quotient */
long rem; /* remainder */
} ldiv_t;
Represent the declaration of the ldiv_t type:
divtDec = TypeDeclaration["Product", "CLDivT", <|"quot" -> "CLong", "rem" -> "CLong"|>, "ReferenceSemantics" -> False];Represent the declaration of the ldiv function:
funcDec = LibraryFunctionDeclaration["ldiv", Automatic, {"CLong", "CLong"} -> "CLDivT"];Compile a program that calls the function from the C standard library:
quotRem = FunctionCompile[{divtDec, funcDec},
Function[{Typed[n, "CLong"], Typed[d, "CLong"]},
With[{divt = LibraryFunction["ldiv"][n, d]},
{divt["quot"], divt["rem"]}]
]
]quotRem[7, 2]Possible Issues (1)
Macros are not types, but replacement rules that are applied to types when they are resolved. Therefore, it is impossible to have different definitions of the same function for a macro and the type to which it refers:
dec = TypeDeclaration["Macro", "macroString", "String"];funcDec = FunctionDeclaration[StringLength, Typed[{"macroString"} -> "MachineInteger"]@
Function[arg, 12]
];FunctionCompile[{dec, funcDec},
Function[Typed[arg, "macroString"], StringLength[arg]]]
Unlike macros, aliases are types, so functions can recognize whether they are applied to a type or an alias of that type.
Text
Wolfram Research (2022), TypeDeclaration, Wolfram Language function, https://reference.wolfram.com/language/ref/TypeDeclaration.html.
CMS
Wolfram Language. 2022. "TypeDeclaration." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/TypeDeclaration.html.
APA
Wolfram Language. (2022). TypeDeclaration. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/TypeDeclaration.html