WOLFRAM

Wolfram Language & System Documentation Center

"RawPointer" (Compiled Type)

"RawPointer"::[t]

represents a pointer to an object with type t, suitable for use with external libraries.

Details

  • "RawPointer"::[t] is equivalent to t* in C.

Constructors

  • ToRawPointer can be used to create a pointer object that uses memory allocated on the stack and is valid until the enclosing function returns.
  • Unless wrapped with "Managed", pointer objects constructed with CreateTypeInstance are not automatically memory managed and must be manually freed with DeleteObject.
  • CreateTypeInstance["RawPointer"::[type]] constructs a raw pointer.
  • CreateTypeInstance["Managed"::["RawPointer"::[type]]] constructs a memory-manged C raw pointer.

Properties

  • Information[ptr,"BaseType"] for ptr of type "RawPointer"::[t] gives "TypeSpecifier"::[t].
  • FromRawPointer[ptr] returns the value pointed to by ptr.

Conversions

    From Expressions

  • RawPointer expressions can be converted into raw pointer types in compiled code.

    • To Expressions

  • "RawPointer" compiled elements can be converted into RawPointer expressions. Note that the raw pointer in compiled code must be allocated dynamically with CreateTypeInstance.

    • "CArray"

  • Cast can be used to bitcast pointers to and from C arrays.

    • "OpaqueRawPointer"

  • Cast can be used to bitcast pointers to and from opaque pointers.

Run-Time Errors

  • Dereferencing a pointer with FromRawPointer is an unsafe operation. Attempting to dereference an invalid pointer can lead to a crash.

Examples

Basic Examples  (4)

Create a "RawPointer"::["MachineInteger"], then dereference it:

Wolfram Language code: cf = FunctionCompile[Function[Typed[arg, "Integer64"], With[{p = ToRawPointer[arg]}, FromRawPointer[p]] ]]
Wolfram Language code: cf[4]

Represent a library function that returns its results by modifying a pointer:

Wolfram Language code: funcDec = LibraryFunctionDeclaration["addonePointer", "compilerDemoBase", {"CInt", "RawPointer"::["CInt"]} -> "CInt"];

Compile a program that uses the function:

Wolfram Language code: cf = FunctionCompile[funcDec, Function[Typed[n, "CInt"], Module[{ptr}, ptr = Typed[ToRawPointer[], "RawPointer"::["CInt"]]; LibraryFunction["addonePointer"][n, ptr]; FromRawPointer[ptr] ]]]
Wolfram Language code: cf[12]

Compile a program that returns a raw pointer containing a value:

Wolfram Language code: cf = FunctionCompile[ Function[Typed[n, "Integer64"], Module[{ptr}, ptr = CreateTypeInstance["RawPointer"]; ToRawPointer[ptr, n]; ptr ]]]
Wolfram Language code: rp = cf[12]

A compiled function that accepts the raw pointer, extracts the value and deletes the pointer:

Wolfram Language code: cf1 = FunctionCompile[ Function[Typed[rp, "RawPointer"::["Integer64"]], Module[{val}, val = FromRawPointer[rp];DeleteObject[rp];val] ]]
Wolfram Language code: cf1[rp]

Compile a program that returns a managed raw pointer containing a value:

Wolfram Language code: cf = FunctionCompile[ Function[Typed[n, "Integer64"], Module[{ptr}, ptr = CreateTypeInstance["Managed"::["RawPointer"::["Integer64"]]]; ToRawPointer[ptr, n]; ptr ]]]

Call the compiled code:

Wolfram Language code: rp = cf[12]

A compiled function that accepts the managed raw pointer and extracts the value:

Wolfram Language code: cf1 = FunctionCompile[ Function[Typed[rp, "Managed"::["RawPointer"::["Integer64"]]], FromRawPointer[rp] ]]

The pointer should not be manually freed, since that is done automatically by "Managed":

Wolfram Language code: cf1[rp]