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:

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

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

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

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

Scope  (4)

Managed objects are memory managed in compiled code:

The contents of managed objects can be accessed with UnmanageObject:

Create a managed object:

Extract its contents with UnmanageObject:

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

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

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

Unmanage the object before letting it pass out of scope:

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

The managed C array is borrowed and automatically unwrapped before it is passed to the library function:

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:

Create a managed object:

Unmanage its contents:

Borrowing the contents of an unmanaged object is an error: