Grant's CGI Framework
Documentation: Memory Handling

Version: 2.0d6
Release Date: Tuesday, October 14, 1997
Expires no later than: December 31, 1997

Important: THIS DOCUMENTATION IS INCOMPLETE AND PROBABLY A BIT INACCURATE

It is subject to change as the API matures.
Feedback and contributions are encouraged:

grantcgi@list.nisto.com
or grant@achilles.net

Be aware that any of the functions which return a CGIErr may return
CGIErr_Unimplemented if the function has not been implemented for the
type of plug-in or application you are compiling (e.g., some services
are only available to plug-ins, or specific types of plug-ins, while
others may be only available to CGIs).

Most of the CGI API functions require an APIData structure to be
passed in to them. You should never have to directly access or modify
the contents of that structure.


Introduction to Memory Handling

The framework has its own memory handling system. This means that
allocation and deallocation of memory blocks should only be done
through the Framework's API.

The CGI API functions for memory handling correspond directly with the
MacOS memory functions. So, if you understand Mac memory handling, you
shouldn't have much to learn here.

If you are not familiar with Mac memory handling you should read
"Inside Macintosh: Memory". In the mean time, note that 'NewPtr' is
pretty much equivalent to 'malloc' and 'DisposePtr' is pretty much
equivalent to 'free'. Additionally, it's important to note that
Handles are pointers to pointers and that *theHandle may get moved by
the system so you have to lock it down (HLock/HUnlock) when you need
to keep it in one place for a while.

You should exercise caution when trying to make calls to grow memory
allocations when using this framework. In general, you should instead
allocate new blocks and copy the old data into them.


Dangerous Toolbox Calls

Most Mac Toolbox memory handling calls should probably not be used
within the context of this framework (ANSI C memory calls should not
be used, either). The following are those which should be considered
'off-limits' (one's with equivalent functions in the CGI framework are
marked with a '*'):

*DisposeHandle
*DisposePtr
EmptyHandle
*GetHandleSize
*GetPtrSize
HPurge
HandAndHand
HandToHand
NewEmptyHandle
NewEmptyHandleSys
*NewHandle
*NewHandleClear
NewHandleSys
NewHandleSysClear
*NewPtr
*NewPtrClear
NewPtrSys
NewPtrSysClear
PtrAndHand
PtrToHand
PtrZone
ReallocateHandle
RecoverHandle
SetHandleSize
SetPtrSize

If you need to use one of these, please contact me <grant@kagi.com> or
write a custom wrapper for the function (which takes into account the
special memory handling of the framework).


Memory De/Allocation

These functions correspond to their Mac toolbox equivalents.

CGINewHandle

CGIErr CGINewHandle ( const APIData apidata, long theSize, Handle *newHandle )

CGINewHandleClear

CGIErr CGINewHandleClear ( const APIData apidata, long theSize, Handle *newHandle )

CGINewPtr

CGIErr CGINewPtr ( const APIData apidata, long theSize, Ptr *newPtr )

CGINewPtrClear

CGIErr CGINewPtrClear ( const APIData apidata, long theSize, Ptr *newPtr )

CGIDisposeHandle

CGIErr CGIDisposeHandle ( const APIData apidata, Handle theHandle )

CGIDisposePtr

CGIErr CGIDisposePtr ( const APIData apidata, Ptr thePtr )


Block Size Info

CGIGetHandleSize

CGIErr CGIGetHandleSize ( const APIData apidata, Handle theHandle, UInt32 *outSize )

Get "the logical size of the relocatable block corresponding to a handle."

outSize
will be set to the size of theHandle if there is no error.

CGIGetPtrSize

CGIErr CGIGetPtrSize ( const APIData apidata, Ptr thePtr, UInt32 *outSize )

Get "the logical size of the nonrelocatable block corresponding to a pointer."

outSize
will be set to the size of thePtr if there is no error.

Debugging

CGIDebugPtr

Boolean CGIDebugPtr ( APIData apidata, Ptr thePtr )

Returns true if there's a detected problem with the Ptr.

Important: Only use this function on Ptrs allocated by the framework.

CGIDebugHandle

Boolean CGIDebugHandle ( APIData apidata, Handle theHandle )

Returns true if there's a detected problem with the Handle.

Important: Only use this function on Handles allocated by the framework.


Grant's CGI Framework

Contents: Nisto - Products - Mail Lists - Cree - Standards - Babylon 5

Privacy Statement, Legal Notices
Copyright ©1997-1998 Grant Neufeld. All rights reserved. abc