UnmanageObject
UnmanageObject[man]
takes ownership of memory wrapped in a managed object.
Details
- man can be a ManagedObject or an object with the "Managed" type in compiled code.
- In compiled code, UnmanageObject has the type signature {"Managed"::[t]}t.
- UnmanageObject[man] mutably invalidates the managed object man. In compiled code, reusing man after it has been invalidated is a runtime error.
- UnmanageObject can be used when passing an object to external code that will hold a long-term reference to it.
Examples
open all close allBasic Examples (2)
man = CreateManagedObject[foo, Echo]man["Active"]Unmanage it, returning the original wrapped value:
UnmanageObject[man]The managed object is no longer active:
man["Active"]Compile a function that creates a managed object:
createManaged = FunctionCompile[Function[{},
CreateTypeInstance["Managed", 12, Function[obj, Null;]]
]]Compile a function that unmanages the object:
unmanage = FunctionCompile[Function[Typed[arg, "Managed"::["MachineInteger"]],
UnmanageObject[arg]
]]managed = createManaged[]Unmanage it, returning the original wrapped value:
unmanage[managed]Scope (3)
The freeing function is evaluated when the managed object is no longer referenced:
With[{man = CreateManagedObject[foo, Echo]}, Null]The freeing function is not evaluated if the managed object was unmanaged:
With[{man = CreateManagedObject[foo, Echo]}, UnmanageObject[man];]Managed objects are invalidated by UnmanageObject and are not freed when they go out of scope. Compile functions for creating an unmanaged object:
createManaged = FunctionCompile[Function[{},
CreateTypeInstance["Managed", 12, Function[obj, Echo["freed"];]]
]]unmanage = FunctionCompile[Function[Typed[arg, "Managed"::["MachineInteger"]],
UnmanageObject[arg]
]]Create a managed object and then let it pass out of scope:
Module[{obj}, obj = createManaged[];Echo["body"]];Unmanage the object before letting it pass out of scope:
Module[{obj}, obj = createManaged[];unmanage[obj];Echo["body"]];The contents of managed objects can effectively be borrowed by unmanaging them and then creating a new managed object. Compile a function for creating a managed C array:
createManagedArray = FunctionCompile[Function[{},
CreateTypeInstance["Managed"::["CArray"::["MachineInteger"]], {1, 2, 3}]
]]Compile a function that unmanages, modifies and then remanages the C array:
modifyManagedArray = FunctionCompile[Function[Typed[carr, "Managed"::["CArray"::["MachineInteger"]]],
Module[{unmanagedArr},
unmanagedArr = UnmanageObject[carr];
ToRawPointer[unmanagedArr, 0, 42];
CreateTypeInstance["Managed", unmanagedArr]
]
]]carr = createManagedArray[]Modify it, returning a new managed C array:
carr2 = modifyManagedArray[carr]Properties & Relations (2)
Functions that allocate raw memory usually return a managed object:
ptr = RawMemoryAllocate["UnsignedInteger8", 10]rawPtr = UnmanageObject[ptr]RawMemoryWrite[rawPtr, 42]Since the pointer is unmanaged, call RawMemoryFree when the memory is no longer used:
RawMemoryFree[rawPtr]Managed objects are automatically unwrapped by functions declared with LibraryFunctionDeclaration, so no calls to UnmanageObject are needed:
dec = LibraryFunctionDeclaration["sumArray", "compilerDemoBase", {"CArray"::["CLong"], "CLong"} -> "CInt"];The managed C array is borrowed and automatically unwrapped before it is passed to the library function:
cf = FunctionCompile[dec,
Function[Typed[arg, "ListVector"::["CLong"]],
Module[{carr},
carr = CreateTypeInstance["Managed"::["CArray"::["CLong"]], arg];
LibraryFunction["sumArray"][carr, Length[arg]]
]
]
]cf[Range[100]]Possible Issues (1)
Compile functions that handle the management of integers:
funcs = FunctionCompile[
<|
"create" -> Function[{},
CreateTypeInstance["Managed", 12, Function[obj, Null;]]
],
"unmanage" -> Function[Typed[arg, "Managed"::["MachineInteger"]],
UnmanageObject[arg]
]
|>]managed = funcs["create"][]Unmanage it, returning the original wrapped value:
funcs["unmanage"][managed]Subsequent calls to UnmanageObject fail, as the managed object is invalidated when it is unmanaged:
funcs["unmanage"][managed]
Text
Wolfram Research (2022), UnmanageObject, Wolfram Language function, https://reference.wolfram.com/language/ref/UnmanageObject.html.
CMS
Wolfram Language. 2022. "UnmanageObject." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/UnmanageObject.html.
APA
Wolfram Language. (2022). UnmanageObject. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/UnmanageObject.html