WOLFRAM

Wolfram Language & System Documentation Center

"Managed" (Compiled Type)

"Managed"::[t]

represents a type that adds automatic memory management to t.

Details

  • "Managed" adds memory management to types, such as those exposed by external libraries.
  • t cannot already have automatic memory management.
  • "Managed" uses automatic reference counting to automatically free objects that are no longer in use.
  • Managed objects returned from compiled code continue to be memory managed by the Wolfram Language kernel.
  • Managed objects are automatically unwrapped when passed as arguments to functions declared by LibraryFunctionDeclaration. »

Constructors

  • CreateTypeInstance["Managed"::[t],obj,freeFunc] constructs a managed object containing obj, which executes freeFunc[obj] when the "Managed" object is freed. freeFunc must have the type signature {t}"Null".
  • CreateTypeInstance["Managed"::[t],obj] uses DeleteObject as the freeFunc.
  • There are many constructors for specific "Managed"::[t] types, which are documented on the page for the compiled type t. For example, constructors for "Managed"::["CString"] are documented with "CString".

Operations

  • For an instance of type "Managed", the following operations can be used:
  • man["BorrowValue"]get the value of the wrapped object if it is valid
    man["UnmanageObject"]take ownership of the wrapped object

Properties

  • Information[man,"BaseType"] for man of type "Managed"::[t] gives "TypeSpecifier"::[t].
  • UnmanageObject unwraps and invalidates a managed object, taking ownership of the wrapped object.
    UnmanageObject[man] is equivalent to man["UnmanageObject"].

Conversions

    Expressions

  • "Managed" objects are converted to memory-managed expressions. When the expression is freed, the freeing function of the original managed object is executed.

Runtime Errors

    InvalidManaged

  • Using a managed object after it has been unmanaged with UnmanageObject can give a runtime error.

Examples

open all close all

Basic Examples  (3)

Compile a program that returns a managed "CString" object:

Wolfram Language code: cf = FunctionCompile[Function[Typed[str, "String"], Cast[str, "Managed"::["CString"]] ]]
Wolfram Language code: cf["Hello, World!"]

The wrapped "CString" is automatically freed when the managed object goes out of scope:

Wolfram Language code: With[{before = MemoryInUse[]}, Do[cf["test"], 100];MemoryInUse[] - before]

Compile a function that returns a managed object that prints when it is freed:

Wolfram Language code: cf = FunctionCompile[Function[{}, CreateTypeInstance["Managed", 12, Function[obj, Echo["freed"];]] ]]

Create the managed object and then let it pass out of scope:

Wolfram Language code: Module[{obj}, obj = cf[];Echo["body"]];

Compile a function that returns the length of a string by casting the string to a managed C-string and using its borrowed value:

Wolfram Language code: func = FunctionCompile[ Function[{Typed[str, "String"]}, Module[{cstrMan, cstr, len}, cstrMan = Cast[str, "Managed"::["CString"]]; cstr = cstrMan["BorrowValue"]; len = LibraryFunction["strlen"][cstr]; len ] ] ]
Wolfram Language code: func["Hello, World!"]

Scope  (4)

Managed objects are memory managed in compiled code:

Wolfram Language code: cf = FunctionCompile[Function[{}, Module[{obj}, obj = CreateTypeInstance["Managed", 12, Function[obj, Echo["freed"];]]; Echo["body"]; ] ]]
Wolfram Language code: cf[]

The contents of managed objects can be accessed with UnmanageObject:

Wolfram Language code: createManaged = FunctionCompile[Function[{}, CreateTypeInstance["Managed", 12, Function[obj, Echo["freed"];]] ]]
Wolfram Language code: unmanage = FunctionCompile[Function[Typed[arg, "Managed"::["MachineInteger"]], UnmanageObject[arg] ]]

Create a managed object:

Wolfram Language code: man = createManaged[]

Extract its contents with UnmanageObject:

Wolfram Language code: unmanage[man]

UnmanageObject invalidates the managed object, so subsequent calls to UnmanageObject fail:

Wolfram Language code: unmanage[man]

Managed objects that have been unmanaged are not automatically freed. Compile functions for creating and unmanaging a managed object:

Wolfram Language code: createManaged = FunctionCompile[Function[{}, CreateTypeInstance["Managed", 12, Function[obj, Echo["freed"];]] ]]
Wolfram Language code: unmanage = FunctionCompile[Function[Typed[arg, "Managed"::["MachineInteger"]], arg["UnmanageObject"] ]]

Create a managed object and then let it pass out of scope:

Wolfram Language code: Module[{obj}, obj = createManaged[];Echo["body"]];

Unmanage the object before letting it pass out of scope:

Wolfram Language code: Module[{obj}, obj = createManaged[];unmanage[obj];Echo["body"]];

Represent a function that takes an unmanaged C array as an argument:

Wolfram Language code: 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:

Wolfram Language code: cf = FunctionCompile[dec, Function[Typed[arg, "ListVector"::["CLong"]], Module[{carr}, carr = CreateTypeInstance["Managed"::["CArray"::["CLong"]], arg]; LibraryFunction["sumArray"][carr, Length[arg]] ] ] ]
Wolfram Language code: cf[Range[100]]

Possible Issues  (1)

Borrowing values from managed objects that have been unmanaged results in an error. Compile functions for creating, unmanaging and borowing values from a managed object:

Wolfram Language code: createManaged = FunctionCompile[Function[{}, CreateTypeInstance["Managed", 12, Function[obj, Echo["freed"];]] ]]
Wolfram Language code: unmanage = FunctionCompile[Function[Typed[arg, "Managed"::["MachineInteger"]], arg["UnmanageObject"] ]]
Wolfram Language code: borrow = FunctionCompile[Function[Typed[arg, "Managed"::["MachineInteger"]], arg["BorrowValue"] ], CompilerRuntimeErrorAction -> None]

Create a managed object:

Wolfram Language code: man = createManaged[]

Unmanage its contents:

Wolfram Language code: unmanage[man]

Borrowing the contents of an unmanaged object is an error:

Wolfram Language code: borrow[man]