org.abora.gold.snarf
Class SnarfHandler

java.lang.Object
  |
  +--org.abora.gold.java.AboraHeaper
        |
        +--org.abora.gold.xpp.basic.Heaper
              |
              +--org.abora.gold.snarf.SnarfHandler

public class SnarfHandler

extends Heaper

A SnarfHandler breaks a snarf into abstract subarrays of bytes into whic flocks are
stored. These indexed flock storage areas are accessed through readStreams and
writeStreams provided by the SnarfHandler. SnarfHandlers also provide the ability to
resize these flock areas and associate a couple of flag bits with them. All access to the
snarf goes through a single snarfHandler.
The beginning of the snarf is dedicated to a table that describes the locations and sizes
of the contained flock areas. Currently, we allocate space between the flock nearest the
front of the snarf and the end of the mapTable. When not enough space exists between the
two, we compact the flock storage areas towards the back (highest address) of the snarf
and try to allocate again.
An index in the snarfHAndler can be associated either with one of these flock storage
areas or with a snarfID and index to look further for the storage of a given flock. Right
now, the SnarfHAndler keeps the forwarding information in a flock storage area, but it
will soon be put into the mapTable directly.
Forwarding pointers occur when a flock outgrows a snarf, and must be moved elsewhere.
Eventually all other snarfs that have objects which point to the forwarding pointer are
updated, and the forwarding pointer can be deallocated, but decisions about this must be
made by objects external to the SnarfHandler.
The forwarded flag is stored on the snarfID. The forgotten flag is stored on the size.
Both use the same Flag mask for accessing the flag, and the Value mask for accessing the
value.

Field Summary

protected static byte	Flag
protected SnarfHandle	myHandle
protected byte	myMapCount
protected byte	myNearest
protected byte	mySpaceLeft
protected static byte	SizeOffset
protected static boolean	UseFences
protected static byte	Value

Fields inherited from class org.abora.gold.xpp.basic.Heaper

AllBlasts, BecomeMap, GarbageCount, InGC, InitializedClasses, InitializingClasses, LastMemory, NextClientRequestNumber, NotOneElementSignal, PackageTable, PromiseNameTable, StringHashSBoxes

Fields inherited from class org.abora.gold.java.AboraHeaper

ActiveClubs, CurrentAuthor, CurrentBertCanopyCache, CurrentBertCrum, CurrentChunk, CurrentGrandMap, CurrentKeyMaster, CurrentPacker, CurrentSensorCanopyCache, CurrentServer, CurrentSession, CurrentSessions, CurrentTrace, InitialEditClub, InitialOwner, InitialReadClub, InitialSponsor, InsideTransactionFlag

Constructor Summary

SnarfHandler(SnarfHandle handle)

Method Summary

int	actualHashForEqual()
void	allocateCells(IntegerVar indices) Add more cells to the mapTable.
void	atAllocate(IntegerVar ind, int flockSize) Allocate flockSize bytes for the flock at the index ind.
void	atStoreForget(int index, boolean flag) See the comment on isForgotten:.
void	atStoreIndex(int index, int offset) Store the offset as the starting location for the data of the flock at index. Update the cache of nearestFlock.
void	atStoreSize(int index, int size) Store size as the number of bytes for the flock at index.
boolean	checkFence(int index) If we are using fences around flock storage areas, then return true only if the fences are still in place for the flock at index.
void	checkFences() See checkFence: Check the fences for all flocks and blast if any are violated.
void	checkIndex(int index) Blast if the index is not represented in the table.
void	clearSpace(int count) This checks for count bytes available at the end of the mapTable.
void	compact() Compress flock storage areas towards the end of the snarf, leaving all freespace between the end of the mapTable and the nearest flock.
void	consistencyCheck() Generic checking hook to do slow runtime consistency checking when debugging.
void	destruct() Write my internal constants to the snarf before I go away.
static int	fenceSize() The number of bytes for one fence (Each flock requires two).
FlockLocation	fetchForward(int index) If the flock specified by index has been forwarded, return a FlockLocation with the SnarfID and index of its new location.
int	flockOffset(int index) Return the index of the first byte of the actual data associated with flock number index. This is like indexOf: except that it leaves room for fencePosts on either side of the flock storage area.
int	flocksEnd() Return the index of the cell one greater than the size of the entire snarf.
int	flockSize(int index) Return the number of bytes in the flock at index
void	forwardTo(IntegerVar index, SnarfID newSnarfID, int newIndex) Associate a forwarder with index.
int	getOffset(int index) Return the index of the first byte of the actual data associated with flock number index.
int	getSize(int index) Return the number of bytes in the flock at index.
void	initializeSnarf() Put in the minimum necessary for a starting snarf. All it needs is the number of objects and the spaceLeft. This also writes the information to the real snarf.
void	inspect()
boolean	isForgotten(int index) The forgotten flag is the flag bit associated with each flock.
boolean	isForwarded(int index) Return the internal bit that says whether the flock at index is represented by forwarding information or by a flock area
boolean	isOccupied(int index) Return true if there's a flock or forwarder at index.
boolean	isWritable() Return true if I represent a writable snarf.
static void	linkTimeNonInherited()
static Heaper	make(SnarfHandle snarfHandle)
void	makeWritable() Make the handle for the receiver writable.
int	mapCellOffset(int index) Return the offset into the snarf for the mapCell that has the data for the flock at index.
static int	mapCellOverhead() Return the number of bytes for a single map record, plus the space for the fence.
static int	mapCellSize() Return the number of bytes for a single map record.
int	mapCount() Return the number of slots allocated in the map table.
int	mapEnd() Return the index of the cell just after the end of the map.
static int	mapOverhead() The map starts just after the basic header.
void	mendFences(int index) Couldn't resist the name.
int	nearestFlock() Return the location of the nearest flock.
static void	quickSort(UInt32Array offsets, UInt32Array indices, int first, int last)
static void	quickSort(UInt32Array offsets, UInt32Array indices, OrderSpec os, IntegerVar first, IntegerVar last)
XnReadStream	readStream(int index) Return a stream on the area of the snarf allocated to mapIndex. This stream must be used immediately, then thrown away.
void	recomputeNearest() Recalculate the nearest flock by looking at the start of every flock and taking the min.
void	rewrite() Write out to the snarf any values held in instance variables (space remaining, number of entries, etc.).
SnarfID	snarfID() Return the snarfID of the snarf this handle holds.
int	snarfMapCount() Actually get from the snarf the number of map slots currently allocated, including ones that are free for reuse.
int	snarfSpaceLeft() Actually get from the snarf the amount of unallocated space remaining.
static UInt32Array	sort(UInt32Array offsets) Sort the offsets array in place, and return an array of the same size that maps from the new index of each element to its original index.
static UInt32Array	sort(UInt32Array offsets, OrderSpec os) Sort the offsets array in place, and return an array of the same size that maps from the new index of each element to its original index.
static Pair	sortTest(Array array) self sortTest: #(2 3 4 1). self sortTest: #(). self sortTest: #(1000 1000 1000). self sortTest: #(1 2 3 4). self sortTest: #(1). self sortTest: #(2 2 3 3 4 4 1 1).
static Pair	sortTestDown(Array array) self sortTestDown: #(2 3 4 1). self sortTestDown: #(). self sortTestDown: #(1000 1000 1000). self sortTestDown: #(1 2 3 4). self sortTestDown: #(1). self sortTestDown: #(2 2 3 3 4 4 1 1).
int	spaceLeft() Return the amount space left in the snarf.
static void	swap(UInt32Array array, IntegerVar i, IntegerVar j)
void	wipeFlock(IntegerVar index) Deallocate all space for the flock at index.
XnWriteStream	writeStream(IntegerVar index) Return a stream that can write into the bytes allocated to the flock at index. The stream must be used immediately and thrown away.

Methods inherited from class org.abora.gold.xpp.basic.Heaper

abstractDeclarationFor, abstractTypeFor, addMethodAttributeToInOf, addPackage, addPackageCategory, allClientProtocolOn, argumentTypesFor, arrow, blast, blast, BLAST, cachePromiseNameTable, cachePromiseNameTableIn, canYouBecome, cast, cleanPromiseClasses, cleanupGarbage, clientClassesDo, clientFunctionsOn, clientMethodsOn, clientProtocol, clientProtocolDo, clientProtocolOn, clientProtocolOn, collectibleClasses, compare, compileClientSubclasses, compileConstantPromiseMethods, compileCreateFromRcvr, compileEQ, compileGeneratedClassMethod, compileGeneratedMethod, compileHook, compilePromise, compilePromiseDefaultMethods, compilePromiseFluidDeclarations, compilePromiseHandlers, compilePromiseMethods, compileRequestCreateMsgInArguments, compileRequestEvaluateMsgInReturningArguments, compileRPCSpecialistEvaluateMsgForReturningArguments, compileSendSelfTo, compileSendSelfToSendHook, compileStubbleMethods, compileSubclassStubbleMethods, computeMangle, computePreorder, constantTypeValue, convert, convertCopyDeclarations, convertDeferredDeclarations, convertProxyDeclarations, convertSubclassCopyDeclarations, convertSubclassDeferredDeclarations, convertSubclassProxyDeclarations, copyReferencesToType, create, create, create, create, create, create, create, create, create, create, createRequestClassArguments, definesProxyMethods, delete, deref, destroy, destructor, enum, enumFlags, equals, exportName, fetchAttribute, fetchPackage, fetchSuperCategory, fileOutClientProtocol, findCategory, findSenderAndReceiverMethods, findTailInto, flushPromiseNameTable, foo, freezeClientClasses, freezeClientProtocol, freezeStProtocol, frozenClasses, garbageCollect, garbageCollectFrom, gcOpportunity, gcOpportunity, generatedCategory, generatePromiseNames, getCategory, getOrMakePackage, getSuperCategory, handlerSignaturesFrom, hash, hashForEqual, hasProxyMethods, info_clientClasses, info_clientSideClasses, info_promiseClasses, info_stProtocol, inGC, initializedClasses, initializingClasses, initPackages, initStringHashSBoxes, inspectPieces, instanceSize, IntegerVar, isByProxy, isConstructed, isDestructed, isEqual, isEqualOrSubclassOf, isGenerated, isIntType, isKindOf, isRawType, isUnlocked, make, makeClassTable, makeFillTable, makeRequestTable, mangle, markChildren, markCount, markInstances, mayBecome, mayBecomeAnySubclassOf, new1, newX, nonCopyVariables, notWorking, pack, packageClasses, packagingCategory, parseExportName, passe, pointerToStaticMember, pointerToStaticMember, pointerToVirtualMember, preorderMax, preorderNumber, printOn, PROBLEM, problems, promiseClass, promiseDefaultValue, promiseName, promiseNameTable, promiseToAbstract, registerPackageCategory, removeGeneratedCode, removeStubbleMethods, removeSubclassGeneratedCode, removeSubclassStubbleMethods, requestProcedure, requestProceduresFrom, returnTypeFor, rootName, scheduleTermination, sendProxyTo, sendSelfTo, serverNameFor, setGC, signal, signals, smalltalkSelector, stClientProtocol, stubbleSelectorTokenReturnsArguments, subclassNonCopyVariables, takeOop, togglePromiseName, togglePromiseOfParse, unimplemented, unmangle, verifyFreeze, wipeStubble

Methods inherited from class org.abora.gold.java.AboraHeaper

asOop, basicInspect, displayString, error, hack, halt, knownBug, mightNotImplement, REQUIRES, shouldImplement, shouldNotImplement, stubbleForSubclassResponsibility, thingToDo, willNotImplement

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

myHandle

protected SnarfHandle myHandle

myMapCount

protected byte myMapCount

mySpaceLeft

protected byte mySpaceLeft

myNearest

protected byte myNearest

Flag

protected static byte Flag

SizeOffset

protected static byte SizeOffset

UseFences

protected static boolean UseFences

Value

protected static byte Value

Constructor Detail

SnarfHandler

public SnarfHandler(SnarfHandle handle)

Method Detail

fetchForward

public FlockLocation fetchForward(int index)

If the flock specified by index has been forwarded, return a FlockLocation with the
SnarfID and index of its new location.

flockSize

public int flockSize(int index)

Return the number of bytes in the flock at index

isForgotten

public boolean isForgotten(int index)

The forgotten flag is the flag bit associated with each flock. It is set when the
flock has been forgotten, which means that there are no more persistent pointers
to the flock. When a flock is forgotten AND is not in RAM, the SnarfPacker is
free to bring the flock back into RAM and destroy it, which deletes it from the snarf.
Return true if the forgotten flag has been set for the flock at index.

isOccupied

public boolean isOccupied(int index)

Return true if there's a flock or forwarder at index.

mapCount

public int mapCount()

Return the number of slots allocated in the map table.

readStream

public XnReadStream readStream(int index)

Return a stream on the area of the snarf allocated to mapIndex.
This stream must be used immediately, then thrown away.

snarfID

public SnarfID snarfID()

Return the snarfID of the snarf this handle holds.

spaceLeft

public int spaceLeft()

Return the amount space left in the snarf.

allocateCells

public void allocateCells(IntegerVar indices)

Add more cells to the mapTable. Make sure that there is enough space for
those cells, then initialize. The size is initially 0 and the offset points past
the end of the snarf.

atAllocate

public void atAllocate(IntegerVar ind,
                       int flockSize)

Allocate flockSize bytes for the flock at the index ind.

atStoreForget

public void atStoreForget(int index,
                          boolean flag)

See the comment on isForgotten:. Set or clear the forgetFlag for the flock at index.

forwardTo

public void forwardTo(IntegerVar index,
                      SnarfID newSnarfID,
                      int newIndex)

Associate a forwarder with index. Throw away whatever storage
was assigned to it and store the forwarder information in the mapCell.

isWritable

public boolean isWritable()

Return true if I represent a writable snarf.

makeWritable

public void makeWritable()

Make the handle for the receiver writable.

rewrite

public void rewrite()

Write out to the snarf any values held in instance variables (space
remaining, number of entries, etc.).

wipeFlock

public void wipeFlock(IntegerVar index)

Deallocate all space for the flock at index. The slot for index remains however, and can
be reused for another flock.

writeStream

public XnWriteStream writeStream(IntegerVar index)

Return a stream that can write into the bytes allocated to the flock at index.
The stream must be used immediately and thrown away.

initializeSnarf

public void initializeSnarf()

Put in the minimum necessary for a starting snarf.
All it needs is the number of objects and the spaceLeft.
This also writes the information to the real snarf.

checkFence

public boolean checkFence(int index)

If we are using fences around flock storage areas, then return true only if the fences are
still in place for the flock at index. Fences are extra storage at the front and back of
a flock storage area that contains the index of that flock. These are used for runtime
checks that one flock hasn't stepped into the space of another.

checkFences

public void checkFences()

See checkFence: Check the fences for all flocks and blast if any are violated.

checkIndex

public void checkIndex(int index)

Blast if the index is not represented in the table. This is just simple bounds checking.

clearSpace

public void clearSpace(int count)

This checks for count bytes available at the end of the mapTable. If
there isn't enough, it compacts everything and tries again.

compact

public void compact()

Compress flock storage areas towards the end of the snarf, leaving all
freespace between the end of the mapTable and the nearest flock.

consistencyCheck

public void consistencyCheck()

Generic checking hook to do slow runtime consistency checking when debugging. No checks
are active currently.

mendFences

public void mendFences(int index)

Couldn't resist the name. Set up the fences for the flock at index. See checkFence:

nearestFlock

public int nearestFlock()

Return the location of the nearest flock. Everything between the
end of the map and the nearest flock is free space. We normally
allocate everything from the back of the snarf forward. When we
run out of enough contiguous space, we simply compact.
We keep a cache of the current nearest flock. The cache maintins the invariant that it
*must* point to an offset less than or equal to the nearestFlock. Thus it can be too
close
to the mapTable, in which case we will recompute it from scratch.

recomputeNearest

public void recomputeNearest()

Recalculate the nearest flock by looking at the start of every flock and taking the min.

atStoreIndex

public void atStoreIndex(int index,
                         int offset)

Store the offset as the starting location for the data of the flock at index.
Update the cache of nearestFlock. This also clears the forwarded flag.

atStoreSize

public void atStoreSize(int index,
                        int size)

Store size as the number of bytes for the flock at index. If the
space is at a 0, then change the corresponding pointer to past the end of
the snarf so that we don't find it in our searches.

flockOffset

public int flockOffset(int index)

Return the index of the first byte of the actual data associated with flock number index.
This is like indexOf: except that it leaves room for fencePosts on either side of the
flock storage area.

flocksEnd

public int flocksEnd()

Return the index of the cell one greater than the size of the entire snarf. This is just
past the end of the storage area for flocks.

getOffset

public int getOffset(int index)

Return the index of the first byte of the actual data associated with
flock number index. This area includes space for fencePosts and whatever
other things we might dream up that go with the flock in its storage area.

getSize

public int getSize(int index)

Return the number of bytes in the flock at index. This includes space allocated
internally for fencePosts and the like.

isForwarded

public boolean isForwarded(int index)

Return the internal bit that says whether the flock at index is represented by forwarding
information or by a flock area

mapCellOffset

public int mapCellOffset(int index)

Return the offset into the snarf for the mapCell that has the data for the flock at index.

mapEnd

public int mapEnd()

Return the index of the cell just after the end of the map. This is based on the number
of entries in the map.

snarfMapCount

public int snarfMapCount()

Actually get from the snarf the number of map slots currently allocated,
including ones that are free for reuse. This is stored as the first thing in the
snarf.

snarfSpaceLeft

public int snarfSpaceLeft()

Actually get from the snarf the amount of unallocated space remaining.

destruct

public void destruct()

Write my internal constants to the snarf before I go away.

Overrides:

destruct in class Heaper

inspect

public void inspect()

Overrides:

inspect in class AboraHeaper

actualHashForEqual

public int actualHashForEqual()

Overrides:

actualHashForEqual in class Heaper

linkTimeNonInherited

public static void linkTimeNonInherited()

make

public static Heaper make(SnarfHandle snarfHandle)

fenceSize

public static int fenceSize()

The number of bytes for one fence (Each flock requires two).

mapCellOverhead

public static int mapCellOverhead()

Return the number of bytes for a single map record, plus the space for the
fence. The fence will be just the index of the flock stored at the beginning and
the end of the flock's memory

mapCellSize

public static int mapCellSize()

Return the number of bytes for a single map record.

mapOverhead

public static int mapOverhead()

The map starts just after the basic header. The basic header currently has
the number of entries in the map and total amount of free space remaining.

sortTest

public static Pair sortTest(Array array)

self sortTest: #(2 3 4 1).
self sortTest: #().
self sortTest: #(1000 1000 1000).
self sortTest: #(1 2 3 4).
self sortTest: #(1).
self sortTest: #(2 2 3 3 4 4 1 1).

sortTestDown

public static Pair sortTestDown(Array array)

self sortTestDown: #(2 3 4 1).
self sortTestDown: #().
self sortTestDown: #(1000 1000 1000).
self sortTestDown: #(1 2 3 4).
self sortTestDown: #(1).
self sortTestDown: #(2 2 3 3 4 4 1 1).

quickSort

public static void quickSort(UInt32Array offsets,
                             UInt32Array indices,
                             int first,
                             int last)

quickSort

public static void quickSort(UInt32Array offsets,
                             UInt32Array indices,
                             OrderSpec os,
                             IntegerVar first,
                             IntegerVar last)

sort

public static UInt32Array sort(UInt32Array offsets)

Sort the offsets array in place, and return an array of the same size that maps from the
new index of each element to its original index. The offsets array is *assumed* to be
terminated with a guard element which is greater than or equal to all the other elements
of the array according to descending order. If this isn't true, havoc may result.

sort

public static UInt32Array sort(UInt32Array offsets,
                               OrderSpec os)

Sort the offsets array in place, and return an array of the same size that maps from the
new index of each element to its original index. The offsets array is *assumed* to be
terminated with a guard element which is greater than or equal to all the other elements
of the array according to the sorting order. If this isn't true, havoc may result.

swap

public static void swap(UInt32Array array,
                        IntegerVar i,
                        IntegerVar j)