Memory(3) User Contributed Perl Documentation Memory(3)
NAME
Mac::Memory - MacOS Memory Manager
Provide the MacPerl interface to the memory management routines in the
MacOS.
Access to Inside Macintosh is essential for proper use of these
functions. Explanations of terms, processes and procedures are
provided there. Any attempt to use these functions without guidance
can cause severe errors in your machine, including corruption of data.
You have been warned.
SYNOPSIS
The Memory module defines Ptr and Handle classes, and function
interfaces to the memory management.
use Mac::Memory;
$handle = new Handle;
$handle2 = NewHandle;
DESCRIPTION
The following packages and functions provide low level access to the
memory management functions.
Handle
Handle provides an object interface to do simple operations on MacOS
handles. The interface is simpler than the more general memory
management functions.
new
new STRING
Create a new handle and return it. Copy $STRING into the handle if
present. Return a 0 value if a handle could not be created.
$h = new Handle;
$hs = new Handle("This string will now exist in hyperspace");
size
Return the size of a handle (i.e., its data portion).
die unless (new Handle)->size == 0;
die unless $hs->size == 40;
append DATA
Appends the DATA to the end of the handle and returns the success
as the result.
$h->append("This string will now exist in hyperspace");
die unless $h->size == 40;
set OFFSET, LENGTH, DATA
set OFFSET, LENGTH
set OFFSET
set Munge the contents of the handle with the $DATA (deleting if not
present), for the $LENGTH (through to the end of the handle
contents if not present), starting at $OFFSET (the beginning if not
present).
$h->set(5, 6, "datum");
yields
"This datum will now exist in hyperspace"
get OFFSET, LENGTH
get OFFSET
get Return a datum which is the contents of the memory referenced by
$HANDLE, starting at $OFFSET (default zero), of length $LENGTH
(default the rest of the handle).
die unless $hs->get(5, 6) eq "string";
address
Return the address of the memory block.
state
state NEWSTATE
Return the (locked) state of the handle, or return TRUE if the
$NEWSTATE of the handle is installed.
my $state = $h->state;
HLock($h);
# bunch of operations requiring $h to be locked
$h->state($state); # so nested locks exit properly
More than the lock state is stored here, so restoring the actual
state on leaving a scope is required.
open MODE
Open a stream to a handle and return it.
NOT DEFINED AT THE MOMENT
SysRet _open(hand, mode) Handle hand int mode
CODE: RETVAL = OpenHandle(hand, mode); OUTPUT:
RETVAL
dispose
Disposes of the handle. Return zero if no error was detected.
Almost all of the memory management needs in MacPerl can be handled by
the above interface
Ptr
Ptr provides an object interface to do simple operations on MacOS
pointers (nonrelocatable heap blocks). There are very few good reasons
to create pointers like this.
size
Return the size of a pointer (i.e., its data portion).
die unless $ptr->size == 40;
set OFFSET, DATA
get OFFSET, LENGTH
get OFFSET
get Return a datum which is the contents of the memory referenced by
PTR, starting at $OFFSET (default zero), of length $LENGTH (default
the rest of the block).
die unless $ps->get(5, 6) eq "string";
address
Return the address of the memory block.
dispose
Disposes of the block. Return zero if no error was detected.
Functions
GetApplLimit
Mac OS only.
The GetApplLimit function returns the current application heap
limit.
TopMem
Return a pointer to the top of memory for the application.
NewHandle BYTECOUNT
NewHandleSys BYTECOUNT
NewHandleClear BYTECOUNT
NewHandleSysClear BYTECOUNT
Mac OS only. (NewHandleSys, NewHandleSysClear)
Return a handle of $BYTECOUNT size.
NewHandleSys returns a handle in the system heap.
The NewHandleClear and NewHandleSysClear functions work much as the
NewHandle and NewHandleSys functions do but set all bytes in the
new block to 0 instead of leaving the contents of the block
undefined. Currently, this is quite inefficient.
NewPtr BYTECOUNT
NewPtrSys BYTECOUNT
Mac OS only.
NewPtrClear BYTECOUNT
NewPtrSysClear BYTECOUNT
Mac OS only. (NewPtrSys, NewPtrSysClear)
Allocate a nonrelocatable block of memory of a specified size.
NewPtrSys and NewPtrSysClear allocate blocks in the system heap.
NewPtrClear and NewPtrSysClear allocate and zero the blocks
(inefficiently).
MaxBlock
MaxBlockSys
Mac OS only. (MaxBlockSys)
The MaxBlock function returns the maximum contiguous space, in
bytes, that you could obtain after compacting the current heap
zone. MaxBlock does not actually do the compaction.
MaxBlockSys does the same for the system heap.
StackSpace
The StackSpace function returns the current amount of stack space
(in bytes) between the current stack pointer and the application
heap at the instant of return from the trap.
NewEmptyHandle
NewEmptyHandleSys
Mac OS only. (NewEmptyHandleSys)
The NewEmptyHandle function initializes a new handle by allocating
a master pointer for it, but it does not allocate any memory for
the handle to control. NewEmptyHandle sets the handle's master
pointer to NIL.
NewEmptyHandleSys does the same for the system heap.
HLock HANDLE
Lock a relocatable block so that it does not move in the heap. If
you plan to dereference a handle and then allocate, move, or purge
memory (or call a routine that does so), then you should lock the
handle before using the dereferenced handle.
HUnlock HANDLE
Unlock a relocatable block so that it is free to move in its heap
zone.
HPurge HANDLE
Mark a relocatable block so that it can be purged if a memory
request cannot be fulfilled after compaction.
HNoPurge HANDLE
Mark a relocatable block so that it cannot be purged.
HLockHi HANDLE
The HLockHi procedure attempts to move the relocatable block
referenced by the handle $HANDLE upward until it reaches a
nonrelocatable block, a locked relocatable block, or the top of the
heap. Then HLockHi locks the block.
TempNewHandle BYTECOUNT
The TempNewHandle function returns a handle to a block of size
$BYTECOUNT from temporary memory. If it cannot allocate a block of
that size, the function returns NIL.
TempMaxMem
The TempMaxMem function compacts the current heap zone and returns
the size of the largest contiguous block available for temporary
allocation.
$SIZE = &TempMaxMem;
TempFreeMem
The TempFreeMem function returns the total amount of free temporary
memory that you could allocate by calling TempNewHandle. The
returned value is the total number of free bytes. Because these
bytes might be dispersed throughout memory, it is ordinarily not
possible to allocate a single relocatable block of that size.
$SIZE = &TempFreeMem;
CompactMem BYTECOUNT
CompactMemSys BYTECOUNT
Mac OS only. (CompactMemSys)
The CompactMem function compacts the current heap zone by moving
unlocked, relocatable blocks down until they encounter
nonrelocatable blocks or locked, relocatable blocks, but not by
purging blocks. It continues compacting until it either finds a
contiguous block of at least $BYTECOUNT free bytes or has compacted
the entire zone.
The CompactMem function returns the size, in bytes, of the largest
contiguous free block for which it could make room, but it does not
actually allocate that block.
CompactMemSys does the same for the system heap.
PurgeMem BYTECOUNT
PurgeMemSys BYTECOUNT
Mac OS only. (PurgeMemSys)
The PurgeMem procedure sequentially purges blocks from the current
heap zone until it either allocates a contiguous block of at least
$BYTECOUNT free bytes or has purged the entire zone. If it purges
the entire zone without creating a contiguous block of at least
$BYTECOUNT free bytes, PurgeMem generates a memFullErr.
The PurgeMem procedure purges only relocatable, unlocked, purgeable
blocks.
The PurgeMem procedure does not actually attempt to allocate a
block of $BYTECOUNT bytes.
PurgeMemSys does the same for the system heap.
FreeMem
FreeMemSys
Mac OS only. (FreeMemSys)
The FreeMem function returns the total amount of free space (in
bytes) in the current heap zone. Note that it usually isn't
possible to allocate a block of that size, because of heap
fragmentation due to nonrelocatable or locked blocks.
FreeMemSys does the same for the system heap.
ReserveMem BYTECOUNT
ReserveMemSys BYTECOUNT
Mac OS only. (ReserveMemSys)
The ReserveMem procedure attempts to create free space for a block
of $BYTECOUNT contiguous logical bytes at the lowest possible
position in the current heap zone. It pursues every available means
of placing the block as close as possible to the bottom of the
zone, including moving other relocatable blocks upward, expanding
the zone (if possible), and purging blocks from it.
ReserveMemSys does the same for the system heap.
MaxMem
MaxMemSys
Mac OS only. (MaxMemSys)
Use the MaxMem function to compact and purge the current heap zone.
The values returned are the amount of memory available and the
amount by which the zone can grow.
($SIZE, $GROW) = &MaxMem;
MaxMemSys does the purge and compact of the system heap zone, and
the $GROW value is set to zero.
MoveHHi HANDLE
The MoveHHi procedure attempts to move the relocatable block
referenced by the handle $HANDLE upward until it reaches a
nonrelocatable block, a locked relocatable block, or the top of the
heap.
DisposePtr PTR
Releases the memory occupied by the nonrelocatable block specified
by $PTR.
GetPtrSize PTR
The GetPtrSize function returns the logical size, in bytes, of the
nonrelocatable block pointed to by $PTR.
SetPtrSize PTR, NEWSIZE
The SetPtrSize procedure attempts to change the logical size of the
nonrelocatable block pointed to by $PTR. The new logical size is
specified by $NEWSIZE. Return zero if no error was detected.
DisposeHandle HANDLE
The DisposeHandle procedure releases the memory occupied by the
relocatable block whose handle is $HANDLE. It also frees the
handle's master pointer for other uses.
SetHandleSize HANDLE, BYTECOUNT
The SetHandleSize procedure attempts to change the logical size of
the relocatable block whose handle is $HANDLE. The new logical size
is specified by $BYTECOUNT. Return zero if no error was detected.
GetHandleSize HANDLE
The GetHandleSize function returns the logical size, in bytes, of
the relocatable block whose handle is $HANDLE. In case of an error,
GetHandleSize returns 0.
ReallocateHandle HANDLE, BYTECOUNT
Allocates a new relocatable block with a logical size of $BYTECOUNT
bytes. It updates the handle $HANDLE by setting its master pointer
to point to the new block. The new block is unlocked and
unpurgeable. Return zero if no error was detected.
EmptyHandle
Free memory taken by a relocatable block without freeing the
relocatable block's master pointer for other uses.
MoreMasters
Call the MoreMasters procedure several times at the beginning of
your program to prevent the Memory Manager from running out of
master pointers in the middle of application execution. If it does
run out, it allocates more, possibly causing heap fragmentation.
BlockMove SOURCEPTR, DESTPTR, BYTECOUNT
BlockMoveData SOURCEPTR, DESTPTR, BYTECOUNT
The BlockMove/BlockMoveData procedure moves a block of $BYTECOUNT
consecutive bytes from the address designated by $SOURCEPTR to that
designated by $DESTPTR.
PurgeSpace
Determine the total amount of free memory and the size of the
largest allocatable block after a purge of the heap.
($Total, $Contiguous) = &PurgeSpace;
HGetState HANDLE
Get the current properties of a relocatable block (perhaps so that
you can change and then later restore those properties).
HSetState HANDLE, STATE
Restore properties of a block after a call to HGetState.
HandToHand HANDLE
The HandToHand function attempts to copy the information in the
relocatable block to which $HANDLE is a handle. Return "undef" if
an error was detected.
PtrToHand PTR, BYTECOUNT
The PtrToHand function returns a newly created handle to a copy of
the number of bytes specified by $BYTECOUNT, beginning at the
location specified by $PTR. Return "undef" if an error was
detected.
PtrToXHand HANDLE, PTR, BYTECOUNT
The PtrToXHand function makes the existing handle, specified by
$HANDLE, a handle to a copy of the number of bytes specified by
$BYTECOUNT, beginning at the location specified by $PTR. Return
"undef" if an error was detected.
HandAndHand AHNDLE, BHNDLE
The HandAndHand function concatenates the information from the
relocatable block to which $AHNDL is a handle onto the end of the
relocatable block to which $BHNDL is a handle. The $AHNDL variable
remains unchanged. Return zero if no error was detected.
PtrAndHand PTR, HANDLE, BYTECOUNT
The PtrAndHand function takes the number of bytes specified by
$BYTECOUNT, beginning at the location specified by $PTR, and
concatenates them onto the end of the relocatable block to which
$HANDLE is a handle.
The low level interface is not likely to be needed, except for the
HLock() function.
AUTHOR
Written by Matthias Ulrich Neeracher <neeracher@mac.com>, documentation
by Bob Dalgleish <bob.dalgleish@sasknet.sk.ca>. Currently maintained
by Chris Nandor <pudge@pobox.com>.
perl v5.10.0 2009-05-18 Memory(3)
Mac OS X 10.6 - Generated Thu Sep 17 20:13:30 CDT 2009