MaplePointerType - Maple Programming Help

Home : Support : Online Help : Programming : OpenMaple : C Application Programming Interface : Memory and Foreign Object Management : OpenMaple/C/MaplePointer

MaplePointerType

query the type of a MaplePointer in external code

MaplePointerSetType

set the type of a MaplePointer in external code

MaplePointerSetMarkFunction

associate a mark function with a MaplePointer in external code

MaplePointerSetDisposeFunction

associate a dispose function with a MaplePointer in external code

MaplePointerSetPrintFunction

associate a display function with a MaplePointer in external code

 Calling Sequence MaplePointerType(kv, p) MaplePointerSetType(kv, p, type) MaplePointerSetMarkFunction(kv, p, f) MaplePointerSetDisposeFunction(kv, p, f) MaplePointerSetPrintFunction(kv, p, f)

Parameters

 kv - kernel handle of type MKernelVector p - MaplePointer object type - machine word sized integer type designator f - hardware callback function

Description

 • These functions can be used in external code with OpenMaple or define_external.
 • A MaplePointer is a Maple object with embedded data and methods associated with it.  It allows arbitrary external data to be represented as a new Maple object.  Other Maple objects can contain MaplePointers.  Some operators can be overloaded using a module, so use of standard operator notation with these external objects is possible.
 • The type given when creating a MaplePointer with ToMaplePointer can be updated with MaplePointerSetType and queried with MaplePointerType.  This identifier can be used to distinguish between MaplePointers representing different data structures. To generate a unique type identifier, use the address of an external function.
 • If a MaplePointer's data contains references to other Maple objects, it is important to set up a mark callback using MaplePointerSetMarkFunction. Maple reuses memory containing objects that are not referred to by any active data structure.  Since Maple cannot traverse external data structures, it relies on user supplied mark functions to mark Maple objects as active. The supplied mark function is called during every sweep of the Maple garbage collector.  The callback must then call MapleGcMark(obj) for every object, obj, contained in the external data structure.
 • A finalizer callback can be setup using MaplePointerSetDisposeFunction. The supplied callback is called when the MaplePointer object is about to be disposed of by the Maple garbage collector, on exit, or when restarting.  This callback can be used for various tasks, such as freeing externally allocated memory and closing open file handles.
 • The MaplePointerSetPrintFunction is called whenever the MaplePointer object is about to be displayed.  The provided callback can return any valid printable Maple object that Maple  can render.  The print callback is not responsible for displaying the MaplePointer, just converting it to a non-external Maple object.
 • It is critical that MaplePointer callbacks never raise errors, or otherwise change the execution path of code.  In addition, the mark and dispose callbacks must never create any new Maple objects.  Failure to obey these rules may result in unpredictable behavior of the active Maple session.

Examples

Execute the external function from Maple.

 > $\mathrm{with}\left(\mathrm{ExternalCalling}\right):$
 > $\mathrm{dll}≔\mathrm{ExternalLibraryName}\left("HelpExamples"\right):$
 > $\mathrm{llist}≔\mathrm{DefineExternal}\left("MyLinkedList",\mathrm{dll}\right):$
 > $\mathrm{ll}≔\mathrm{llist}\left("create"\right)$
 ${\mathrm{ll}}{:=}{}$ (1)
 > $\mathrm{llist}\left("insert_head",\mathrm{ll},\mathrm{foo}\right):$
 > $\mathrm{llist}\left("insert_head",\mathrm{ll},{x}^{2}+2\right):$
 > $\mathrm{llist}\left("insert_head",\mathrm{ll},99\right):$
 > $\mathrm{llist}\left("insert_head",\mathrm{ll},\left[10,11\right]\right):$
 > $\mathrm{llist}\left("insert_head",\mathrm{ll},z\right):$
 > $\mathrm{ll}$
 ${z}{.}\left[{10}{,}{11}\right]{.}{\mathrm{...}}{.}{\mathrm{foo}}$ (2)
 > $\mathrm{llist}\left("map",\mathrm{ll},\mathrm{length}\right)$
 ${\mathrm{1 . 9 . ... . 3}}$ (3)
 > $\mathrm{llist}\left("remove_head",\mathrm{ll}\right)$
 ${1}$ (4)
 > $\mathrm{llist}\left("remove_head",\mathrm{ll}\right)$
 ${9}$ (5)
 > $\mathrm{ll}$
 ${\mathrm{2 . 13 . 3}}$ (6)