Advanced Programming Guide

336 • Chapter 7: Advanced ConnectivityUser Information The MapleUserInfo command displays "msg" wheninfolevel[’name’] is set to level. This command is only available inthe C API.void MapleUserInfo( MKernelVector kv, int level, char*name, char *msg );Memory Managementusing the C API.The following functions are available only whenvoid* MapleAlloc( MKernelVector kv, M_INT nbytes );void MapleDispose( MKernelVector kv, ALGEB s );void MapleGcAllow( MKernelVector kv, ALGEB a );void MapleGcProtect( MKernelVector kv, ALGEB a );MapleAlloc allocates nbytes bytes of memory and returns a pointerto it. Garbage collection of this memory is handled by Maple. Note thatto allocate this memory, a new BINARY dag structure is created, and apointer to the data part of the dag is returned.The following code snapshot might be seen in a wrapper that convertsan integer reference (a name) in Maple to C.ALGEB arg1;INTEGER32 *i;i = MapleAlloc(kv,sizeof(INTEGER32));*i = MapleToInteger32(kv,arg1);MapleDispose frees the memory allocated to the structure s. Thisshould only be used on data structures created using MapleAlloc, orthose that were created externally and are guaranteed not to be pointedto by any other Maple structure. The Maple garbage collector reclaimsany memory not pointed to by any other data structure, so in typicalcases it is not necessary to use MapleDispose.MapleGcProtect prevents the algebraic a from being collected by theMaple garbage collector. The memory pointed to (by a) is not freed untilMaple exits, or a call to MapleGcAllow is issued. Any dags that mustpersist between external function invocations must be protected. Thisincludes any external global or static ALGEB variables that will be referredto in a later external call. Failure to protect such a persistent variable leadsto unexpected results if the Maple garbage collector removes it betweenfunction calls.MapleGcAllow allows the algebraic structure a to be collected by theMaple garbage collector. Any algebraic structure that is not referenced